Authentication
Flows
ID Token

ID Token authentication

With ID Token authentication, we are able to securely authenticate a user with just an ID token from a third-party provider. With this flow you would have already performed the necessary authentication steps to get an access and ID token. For example, if you're authenticating with Google, then you'll most likely have implemented the Authorization Code Flow (opens in a new tab) to sign the user in.

These are the general steps:

  1. Configure the 3rd party provider's client ID into the keelconfig.yaml - see here.
  2. Perform the relevant authentication flow with your provider
  3. Extract the id_token from the successful token endpoint response
  4. Perform "token exchange" with our /auth/token endpoint to authenticate
  5. Use the access and refresh tokens to query your Keel API

Retrieving the ID Token

An ID token is an artifact that proves that a user has been authenticated. It was introduced by OpenID Connect (OIDC), an open standard for authentication used by many identity providers such as Google and Facebook.

For OpenID Connect-compatible providers, the ID token will normally be returned from the provider's token endpoint. For example, this is the response from Auth0's token endpoint after successfully authenticating:

{
	"access_token": "{{provider_access_token}}",
	"id_token": "{{provider_id_token}}",
	"scope": "openid profile email address phone",
	"expires_in": 86400,
	"token_type": "Bearer"
}

If an ID token is not returned with your providers token endpoint, then you might need to request it by providing the scope value openid.

Getting Access Tokens

Once you have obtained the ID token, you must then exchange it for a Keel access token. This is done by calling the /auth/token endpoint with the token_exchange grant.

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

If you are successfully authenticated, the token endpoint will respond with HTTP 200 and an application/json response body.

HTTP 200
{
  "access_token": "{{keel_access_token}}",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "{{keel_refresh_token}}",
  "identity_created": false
}

If the ID token cannot be verified, then you will receive an HTTP 401 response. These are some reasons as to why the ID token would fail to authenticate:

  • The ID token has expired (they typically have a short lifespan).
  • The provider is not configured - visit the Configuration page for more.
  • The ID token was issued by a different client to what is configured in your Keel app.
  • The ID token was not legitimately issued by the provider. We perform various handshakes to ensure this is the case.

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" } } }'
Single Sign-OnPassword