Single Sign-on authentication

Keel provides an abstraction over the complex OAuth gymnastics which you would normally need to build into your application. This is especially useful if you want to support multiple different authentication providers (such as Google, Facebook, GitLab, etc.). What this means is that all you need to do is provide some simple configuration in your keelconfig.yaml file and integrate with a singular auth endpoint. Keel handles the rest.

These are the general steps:

1. Configure the 3rd party provider's client ID into the keelconfig.yaml - see here.
2. Set the 3rd party provider's client secret - see here.
3. Configure a redirectUrl in the keelconfig.yaml - see here.
4. Point the browser to the relevant provider login; /auth/authorize/{name}. This will redirect the user to the provider's login page. Once the user has successfully authenticated, the provider will redirect the user back to the redirectUrl configured in the keelconfig.yaml file.
   {name} here is the name of the provider as configured in your keelconfig.yaml file. More on this in the getting started section.
5. Handle the redirect after the completed authentication flow (configured at redirectUrl in the keelconfig.yaml). To handle this, you will need to:
   1. Parse the query string and extract the value of the code parameter.
   2. Give the authorization code to our /auth/token endpoint to authenticate the provider with Keel. This will return a Keel access token and refresh token. See here.
6. Use the access and refresh tokens to query your Keel API

Let's break these down in more detail.

Setting the callbackUrl with the Provider

Configure the callbackUrl below to the client's allowed redirect URLs. This can be found at GET /auth/providers:

[
  {
    "name": "Auth0",
    "type": "oidc",
    "authorizeUrl": "http://localhost:8000/auth/authorize/auth0",
    "callbackUrl": "http://localhost:8000/auth/callback/auth0"
  }
]

Setting the Client Secret

The Single Sign-On flow requires a client secret, which is obtained from the auth provider's console, typically when creating the client. This secret must be set as a secret in your environment.

• For local CLI use, keel secrets set MY_SECRET 'my-value' is used to set a secret
• For hosted environments, use the environment variables page in the Console

The name of the secret has the format AUTH_PROVIDER_SECRET_{name} where {name} is the uppercased name of the provider as configured in your keelconfig.yaml file.

We cover this in much more detail in the broader getting started section as it covers both flows.

Setting the redirectUrl in keelconfig.yaml

Configure a redirectUrl in the keelconfig.yaml with the URL you want authentication to redirect after it has completed like so:

auth:
  redirectUrl: http://localhost:8000/callback
  providers:
    - type: google
      name: google_client
      clientId: 1234

After the user has successfully authenticated with the provider, the provider will redirect the user back to the redirectUrl configured in the keelconfig.yaml file and pass some query params along with it. The code query param is the one we are interested in. This is the authorization code which we will use to get a Keel access token.

Getting Access Tokens

After logging in on the external provider, being redirecting to your redirectUrl, having extracting the code URL query parameter, you must then trade that authorization code for a Keel access token.

You can trade the authorization code for a set of Keel tokens by calling the /auth/token endpoint with the authorization_code grant like so:

curl --request POST \
  --url 'http://localhost:8000/auth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data subject_token={{auth_code}}

The expected Content-Type of the /auth/token endpoint is application/x-www-form-urlencoded because this is enforced by the OAuth standard, however we also support application/json for convenience. After making this request, if you are successfully authenticated, the token endpoint will respond with HTTP 200 and the following application/json response body.

{
  "access_token": "{{keel_access_token}}",
  "token_type": "Bearer",
  "expires_in": 86400, // one day
  "refresh_token": "{{keel_refresh_token}}",
  "identity_created": false
}

You can read more about the tokens here.

Other Considerations

Make sure to enable the Authorization Code Grant flow on the auth provider's console, if necessary. Auth0 requires this to be explicitly enabled.

Perform authenticated requests to your Keel APIs

After authenticating, proceed to use the access token you have received to perform authenticated requests to your Keel APIs. This is done by including the access token (prefixed with Bearer) in the Authorization header of the request.

curl --request POST \
  --url 'http://localhost:8000/api/json/searchAuthors' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
  --data '{ "where": { "name": { "startsWith": "Bob" } } }'