Configuration

All configuration for authentication your Keel application is done in the keelconfig.yaml file.

Configuring Tokens

You can configure your tokens like so:

auth:
  tokens:
    # Lifespan of the access token in seconds. Default is 24 hours.
    accessTokenExpiry: 3600
    # Lifespan of the refresh token in seconds. Default is 3 months.
    refreshTokenExpiry: 604800
    # Enable refresh token rotation. Default is true.
    refreshTokenRotationEnabled: true

It's recommended to keep the lifespan of an access token extremely short, since if they're stolen they can be used to access your application as a specific user. Refresh tokens are used to acquire new access tokens, and can live longer.

Redirect URL

For Single Sign-On, you can configure a redirectUrl in your keelconfig.yaml. Users will be sent here after the auth/authorize/{provider} flow has successfully completed. An auth code will be provided in the query parameter code, which can then be used at the token endpoint to acquire an access and refresh token.

auth:
  redirectUrl: http://localhost:8000/callback

The redirectUrl is optional. If omitted, clients can provide their own redirect_uri as a query parameter on the authorize request. This is useful when multiple clients (such as MCP clients) each have their own callback URL. See the Single Sign-On page for more details.

When redirectUrl is configured, it always takes precedence over any client-provided redirect_uri — the client value is ignored. This prevents open redirect attacks in deployments that have a fixed redirect URL.

Password Reset URL

For the password authentication flow, you can configure allowed redirect URLs for password reset emails using passwordResetUrl:

auth:
  passwordResetUrl: https://app.example.com/reset-password

You can also allowlist multiple URLs:

auth:
  passwordResetUrl:
    - https://app.example.com/reset-password
    - https://admin.example.com/reset-password
    - http://localhost:3000/reset-password

When a password reset is requested, the redirectUrl in the request is optional. If omitted, Keel uses the first configured URL. If provided, it must match one of the configured URLs — otherwise the request is rejected.

URLs must be absolute HTTPS URLs, except for localhost and loopback addresses which may use HTTP.

Providers

Various providers can be configured. Depending on the type various other fields may be required.

Parameter Name	Description
`type`	The type of provider
`name`	The unique name you give to this provider
`clientId`	The client ID given to you by your provider

Types of Providers

We support google, facebook, gitlab, and slack out-of-the-box. See the providers page for more.

You can also configure your own custom OpenId Connect (oidc) provider type. Read on for more.

Out of the Box Providers

No additional fields need to be provided.

auth:
  providers:
    - type: google
      name: google_client
      clientId: hfjuwaa3a2983h1hfsdf

Custom OpenID Connect Provider

Parameter Name	Description
`issuerUrl`	The provider's issuer URL used for discovery purposes

auth:
  providers:
    # Custom OIDC
    - type: oidc
      name: Baidu
      issuerUrl: https://dev-skhlutl45lbqkvhv.us.auth0.com
      clientId: kasj28fnq09ak

Client Secret Configuration

This is only necessary for the Single Sign-On flow.

The name of the secret has the format AUTH_PROVIDER_SECRET_{name} where {name} is the UPPER_SNAKE_CASED name of the provider as configured in your keelconfig.yaml file. See the Single Sign-On page for more.

User Creation

The userCreation setting controls how Keel manages User records alongside authentication. See the Identity page for more on how identities and users relate.

auth:
  userCreation: auto

There are three modes:

off (default) — No built-in User model is injected. Identities are created but no User records are managed automatically.
auto — A User record is automatically created or linked by email on every authentication. No custom code required.
required — Authentication is denied unless a pre-existing User with a matching email exists. Use this when users must be pre-provisioned before they can log in.

Email Verification and User Linking

When authenticating with a third-party provider (via SSO or ID Token), Keel checks whether the provider's email is verified before linking the identity to an existing User.

If email_verified is true in the provider's claims, Keel links the identity to the matching User (or creates one in auto mode).
If email_verified is false:
- In auto mode, the identity is created but is not linked to any User. No new User is created.
- In required mode, the identity is created but is not linked to any User, even if a matching User exists.

This prevents an unverified email from being used to gain access to another user's account. Password-based identities are not affected by this check since the email is provided directly by the user.

Tokens Providers