Custom OAuth 101

Using Gelato's Single Sign On functionality, you can let your Developers login and register on your portal with their existing user accounts for your service. This is a great integrated Developer Experience, and it also helps when provisioning API Credentials (as now you can associate them with the correct user account)

Plus, you get a great looking branded Login button:

71mdu8ccws  M07

For a Custom OAuth setup, you will need the following:

  • A Gelato Enterprise account (Request a Demo if you haven't already)
  • An OAuth Provider (this means users can authenticate with your app via 3-legged OAuth, usually the Authorization Code Grant. The OAuth Bible site has more information.
  • A User Information Endpoint that can be accessed with an OAuth Token (more on that below)

User Flow

Here's what the whole process looks like :arrow_lower_left:

Sso Flow

First, Gelato will do an OAuth Authorize redirect to your app, which will present a login page the user. Once they've successfully logged in, you'll redirect back to Gelato and we'll get the user's OAuth Access Token. Gelato will then make a request to your User Information Endpoint (authenticated using that access token) to get some JSON details.

Lastly (but very much not leastly!) we can show your Developer their details (including their avatar!) from your system. Amazing! :sparkles: :fireworks:

User Information Endpoint

In order to present information about your Developer, we need an API endpoint we can use to get their basic information. Usually this is something like /user or /me (you can customize the exact path under "Login Methods > Custom OAuth Settings > Advanced")

Your user information endpoint should return JSON like the following (the more details the better!)

{
  "id":          123,
  "email":       "jason@mashape.com",
  "name":        "Jason Theape",
  "nickname":    "jase",
  "description": "The Amazing API Ape",
  "avatar":      "https://placekitten.com/200/300"
}

Setup Steps

Step 1

Create an OAuth Application to use for Gelato SSO. Make a note of the Client ID and Secret for the application. If you need to specify a Redirect URI, use: https://YOUR-PORTAL-DOMAIN/auth/custom/callback (so for https://awesomeco.gelato.io, you would use https://awesomeco.gelato.io/auth/custom/callback)

Step 2

Login to Gelato, and head on over to Portal Settings > Login Methods / SSO, then click "Set Up to Activate" on "Custom OAuth"

Mdotly6zu3  M07

Step 3

Enter your OAuth Application details as per step one (if you're using custom paths, you can set those under "Advanced") You can also customize your button so that it matches your brand here.

Mmswcnvekn  M07

Step 4

Hit "Save & Activate", and you're done! Enjoy your awesome new Custom OAuth. :smile_cat:

3oonso1vy0 M07  1

Troubleshooting

Please get in touch with support if you have any issues!