> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainlit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

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

<Note>
  To active an OAuth provider, you need to define both the OAuth callback in
  your code and the provider(s) environment variables.
</Note>

## 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.

<Warning>
  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`.
</Warning>

### GitHub

Go to this page to [create a new GitHub OAuth app](https://github.com/settings/applications/new).

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](https://docs.gitlab.com/ee/integration/oauth_provider.html). 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](https://console.developers.google.com/apis/credentials).

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](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-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

Optional environment variables:

* `OAUTH_AZURE_AD_ENABLE_SINGLE_TENANT`: Set to `true` if your application supports "Accounts in this organizational directory only" (Single tenant). If not, do not set this environment variable at all.
* `OAUTH_AZURE_AD_SCOPES`: Space-separated list of OAuth scopes (default: `https://graph.microsoft.com/User.Read offline_access`).
* `OAUTH_AZURE_AD_HYBRID_SCOPES`: Space-separated list of scopes for the hybrid flow (default: `https://graph.microsoft.com/User.Read https://graph.microsoft.com/openid offline_access`).

<Note>
  `OAUTH_AZURE_AD_SCOPES` and `OAUTH_AZURE_AD_HYBRID_SCOPES` are available
  since version **2.11.0**.
</Note>

### Okta

Follow this guide to [create OIDC app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm).

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](https://company.okta.com)

There are several ways to configure the Okta OAuth routes:

* When using the [Single Sign-On to Okta](https://developer.okta.com/docs/reference/api/oidc/#composing-your-base-url) 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](https://developer.okta.com/docs/reference/api/oidc/#_2-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](https://www.descope.com/sign-up), 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](https://app.descope.com/settings/project) in the console.
* `OAUTH_DESCOPE_CLIENT_SECRET`: Descope Access Key, which can be created under [Access Keys](https://app.descope.com/accesskeys) in the console.

### Auth0

Follow this guide to [create an Auth0 application](https://auth0.com/docs/get-started/auth0-overview/create-applications).

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](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html).

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
* `OAUTH_COGNITO_SCOPE`: Access level

### Keycloak

Follow this documentation to [create a new client](https://www.keycloak.org/docs/latest/server_admin/index.html#assembly-managing-clients_server_administration_guide) 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](https://github.com/Chainlit/cookbook/tree/main/auth) describes how to do it, also check [base class](https://github.com/Chainlit/chainlit/blob/2cb38ad8596ac547355f87266bc15ab3dfd632d2/backend/chainlit/oauth_providers.py#L13) for reference.

## Prompt Configuration

<Note>
  Since version **1.3.0**.
</Note>

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:

```bash theme={null}
# 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](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).

## Examples

### Allow all users who passed the oauth authentication.

```python theme={null}
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.

```python theme={null}
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
```