OAuth

OAuth lets you use third-party services to authenticate your users.

​

Providers

Follow these guides to create an OAuth app for your chosen provider(s). Then copy the information into the right environment variable to active the provider.

​

GitHub

Go to this page to create a new GitHub OAuth app.

The callback URL should be: CHAINLIT_URL/auth/oauth/github/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/github/callback.

You need to set the following environment variables:

• OAUTH_GITHUB_CLIENT_ID: Client ID
• OAUTH_GITHUB_CLIENT_SECRET: Client secret

​

Gitlab

Go to this page to create a new GitLab OAuth app. When creating the app, you need to allow the openid, profile and email scopes.

The callback URL should be: CHAINLIT_URL/auth/oauth/gitlab/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/gitlab/callback.

You need to set the following environment variables:

• OAUTH_GITLAB_CLIENT_ID: Client ID
• OAUTH_GITLAB_CLIENT_SECRET: Client secret
• OAUTH_GITLAB_DOMAIN: domain name (without the protocol)

​

Google

Go to this page to create a new Google OAuth app.

The callback URL should be: CHAINLIT_URL/auth/oauth/google/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/google/callback.

You need to set the following environment variables:

• OAUTH_GOOGLE_CLIENT_ID: Client ID
• OAUTH_GOOGLE_CLIENT_SECRET: Client secret

​

Azure Active Directory

Follow this guide to create a new Azure Active Directory OAuth app.

The callback URL should be: CHAINLIT_URL/auth/oauth/azure-ad/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/azure-ad/callback.

You need to set the following environment variables:

• OAUTH_AZURE_AD_CLIENT_ID: Client ID
• OAUTH_AZURE_AD_CLIENT_SECRET: Client secret
• OAUTH_AZURE_AD_TENANT_ID: Azure tenant ID

​

Okta

Follow this guide to create OIDC app integrations.

The callback URL should be: CHAINLIT_URL/auth/oauth/okta/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/okta/callback.

You need to set the following environment variables:

• OAUTH_OKTA_CLIENT_ID: Client ID
• OAUTH_OKTA_CLIENT_SECRET: Client secret
• OAUTH_OKTA_DOMAIN: Domain name for your okta setup - e.g. https://company.okta.com

There are several ways to configure the Okta OAuth routes:

• When using the Single Sign-On to Okta setup, you need to set the OAUTH_OKTA_AUTHORIZATION_SERVER_ID environment variable to false.
• When using Okta as the identity platform for your app or API either:
  • set the OAUTH_OKTA_AUTHORIZATION_SERVER_ID environment variable to default if you have a developer account,
  • or set it to the authorization server id from your Custom Authorization Server.

​

Descope

Head to the Descope sign-up page, to get started with your account and set up your authentication.

The callback URL should be: CHAINLIT_URL/auth/oauth/descope/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/descope/callback.

You need to set the following environment variables:

• OAUTH_DESCOPE_CLIENT_ID: Descope Project ID, which can be found under Project Settings in the console.
• OAUTH_DESCOPE_CLIENT_SECRET: Descope Access Key, which can be created under Access Keys in the console.

​

Auth0

Follow this guide to create an Auth0 application.

The callback URL should be: CHAINLIT_URL/auth/oauth/auth0/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/auth0/callback.

You need to set the following environment variables:

• OAUTH_AUTH0_CLIENT_ID: Client ID
• OAUTH_AUTH0_CLIENT_SECRET: Client secret
• OAUTH_AUTH0_DOMAIN: Domain name for your auth0 setup

Optional environment variables:

• OAUTH_AUTH0_ORIGINAL_DOMAIN: Original domain name for your auth0 setup, if you are using a custom domain

​

Amazon Cognito

Follow this guide to create a new Amazon Cognito User Pool.

The callback URL should be: CHAINLIT_URL/auth/oauth/aws-cognito/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/aws-cognito/callback.

You need to set the following environment variables:

• OAUTH_COGNITO_CLIENT_ID: Client ID
• OAUTH_COGNITO_CLIENT_SECRET: Client secret
• OAUTH_COGNITO_DOMAIN: Cognito Domain

​

Keycloak

Follow this documentation to create a new client in your realm.

You have the option of changing the id of your Keycloak provider, which by default is keycloak. This is useful if you want to display a more appropriate name on your login page. Use the OAUTH_KEYCLOAK_NAME environment variable to set the name. Don’t choose an id that conflicts with any of the other Oauth providers.

The callback URL for your client should be: CHAINLIT_URL/auth/oauth/${OAUTH_KEYCLOAK_NAME}/callback. If your Chainlit app is hosted at localhost:8000, you should use http://localhost:8000/auth/oauth/${OAUTH_KEYCLOAK_NAME}/callback.

You need to set the following environment variables:

• OAUTH_KEYCLOAK_CLIENT_ID: Client ID
• OAUTH_KEYCLOAK_CLIENT_SECRET: Client secret
• OAUTH_KEYCLOAK_REALM: The realm which contains your client.
• OAUTH_KEYCLOAK_BASE_URL: Your Keycloak URL.
• OAUTH_KEYCLOAK_NAME: Optional, see above.

​

Custom Provider

It’s possible to plug-in for any OAuth provider using Chainlit. Required steps are:

• modifying providers variable in runtime
• implementing CustomOAuthProvider(OAuthProvider) class with methods and fields:
  • get_token(self, code, url)
  • get_user_info(self, token)
  • authorize_params
  • env
• providing environmental variables as described in env, for example:
  • YOUR_PROVIDER_CLIENT_ID
  • YOUR_PROVIDER_CLIENT_SECRET

This cookbook example describes how to do it, also check base class for reference.

​

Prompt Configuration

Starting from version 1.3.0, Chainlit allows you to configure how OAuth providers handle re-authentication through the prompt parameter. This is particularly useful for controlling the login behavior when users log out.

You can configure this behavior using two environment variables:

• OAUTH_PROMPT: Sets the default prompt behavior for all OAuth providers
• OAUTH_<PROVIDER>_PROMPT: Sets the prompt behavior for a specific provider (e.g., OAUTH_GITHUB_PROMPT)

The supported values for these variables are:

• none: No interaction required (default if not set)
• login: Forces re-authentication
• consent: Asks for approval of the requested scopes
• select_account: Allows users to select a different account

For example:

# Force consent prompt for all providers
OAUTH_PROMPT=consent

# Override specific provider to force login
OAUTH_GITHUB_PROMPT=login

Note: The behavior and support for different prompt values may vary between OAuth providers. For instance:

• GitHub responds well to prompt=consent
• Some providers like Descope only respect prompt=login

This feature is particularly useful when you want to:

• Allow users to properly log out and switch accounts
• Force re-authentication for security purposes
• Give users the option to change which scopes they approve
• Prevent automatic re-authentication after logout

The prompt parameter is defined in the OpenID Connect Core 1.0 specification. For more technical details, refer to the OpenID Connect documentation.

​

Examples

​

Allow all users who passed the oauth authentication.

from typing import Dict, Optional
import chainlit as cl


@cl.oauth_callback
def oauth_callback(
  provider_id: str,
  token: str,
  raw_user_data: Dict[str, str],
  default_user: cl.User,
) -> Optional[cl.User]:
  return default_user

​

Only allow users from a specific google domain.

from typing import Dict, Optional
import chainlit as cl


@cl.oauth_callback
def oauth_callback(
  provider_id: str,
  token: str,
  raw_user_data: Dict[str, str],
  default_user: cl.User,
) -> Optional[cl.User]:
  if provider_id == "google":
    if raw_user_data["hd"] == "example.org":
      return default_user
  return None