Authentication

In order for users to securely interact with your application, they will need to be authenticated. Keel provides rich support for seamlessly integrating with third-party authentication providers, such as Google, Facebook and GitHub.

We currently support three authentication flows, two of which for authenticating with third-party providers.

Single Sign-On (SSO): Use this flow if you want Keel to handle the authentication handshake with your preferred 3rd-party authentication provider (e.g. Google).
ID Token: If you have already built 3rd-party authentication into your application (probably using Authorization Code Flow (opens in a new tab)) and you have an ID Token.
Password: Basic username and password authentication.

Configuring 3rd-party authentication

To get set up with Single Sign-On or ID Token authentication, you will need to follow these steps:

Create a new OAuth client with your provider
Configure your keelconfig.yaml
Authenticate your users! 🚀
Perform authenticated requests to your Keel APIs

We will cover each of these below.

Create a new OAuth client with your provider

To use an authentication flow with an external service, you will need to set up a client with each of the third-party providers you have configured. For example, to setup "Login with Google" authentication flow, you'll need to create a Google client (opens in a new tab). You'll need to do similar things on Facebook (opens in a new tab), GitLab (opens in a new tab), and any other provider you want to use.

Once you've done this, you will be provided with the following:

Client ID: An identifier for your app with the external service. This is how they know your app is communicating with them. This needs to be configured in your keelconfig.yaml as shown in the next section.
Client Secret: Your app's password on the external service. This should always be kept a secret. This needs to be configured in your host, as discussed soon.

If you only intend to use ID Token authentication, then you can ignore the client secret. It is only necessary for Single Sign-On.

Visit the Providers page for more information.

Configure your `keelconfig.yaml`

3rd-party authentication providers are all configured in your keelconfig.yaml file. For example, let's enable Google:

keelconfig.yaml

auth:
  providers:
    - type: google
      name: google_client
      clientId: {{clientId}}

If you would like to configure your own custom provider, please read the Configuration page for more details on how to do this.

Setting secrets

If you plan to use the Single Sign-On flow, then you will need to configure the client secret on every host on which your Keel app will run.

Secrets for authentication providers follow this pattern: AUTH_PROVIDER_SECRET_{provider name} where {{provider name}} is a provider name written in UPPER_SNAKE_CASE. In our case, it will be AUTH_PROVIDER_SECRET_GOOGLE_CLIENT.

Locally

If you are running Keel locally, you can set the client secret by setting the environment variable AUTH_PROVIDER_SECRET_GOOGLE_CLIENT to the client secret you obtained from your provider. Then, you'll need to add it to your local Keel backend. You can do so by running the following command using the Keel CLI.

keel secrets set AUTH_PROVIDER_SECRET_GOOGLE_CLIENT <your client secret>

The secrets command has the following signature:

keel secrets set <key> <value>

So here, we're setting the AUTH_PROVIDER_SECRET_GOOGLE_CLIENT to your secrent for the development environment. You can also set alternate secrets for other environments, such as testing.

In Production on the Keel Console

If you're hosting your app with Keel, you can set the client secret by going to the Secrets tab on the Keel Console (opens in a new tab), where you can find an "Add secret" button. Clicking this will give you two form fields: key and value. There, you can add AUTH_PROVIDER_SECRET_GOOGLE_CLIENT as the key and your client secret as the value.

Every subsequent deployment will have access to this secret.

Authenticate your users

Now that you are all configured, the next step is to authenticate users:

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/web/json/searchAuthors' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
  --data '{ "where": { "name": { "startsWith": "Bob" } } }'

Auth hooks

If is possible to provide your own custom logic to the authentication flows using auth hooks. Read more here.

Linked Actions Single Sign-On