OAuth lets you use third-party services to authenticate your users.
To active an OAuth provider, you need to define both the OAuth callback in your code and the provider(s) environment variables.

​
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.
If your app is served behind a reverse proxy (like cloud run) you will have to set the CHAINLIT_URL environment variable. For instance, if you host your application at https://mydomain.com, CHAINLIT_URL should be set to https://mydomain.com.

​
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
If your application supports “Accounts in this organizational directory only” (Single tenant), you will need to explicitly set: OAUTH_AZURE_AD_ENABLE_SINGLE_TENANT=true. If not, do not set this environment variable at all.

​
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