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

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