# Authentication

## API Authentication

Personal Access Tokens are used for API authentication and are required for use of the [Python SDK](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk.md).

To create a Personal Access Token click on your profile badge in the lower left of the UI, then click on "Personal Access Token." We recommend saving this as an environment variable like `DBNL_API_TOKEN` for future use.

{% hint style="warning" %}
New tokens can be generated at any time, but old tokens cannot currently be revoked, so please remember to keep your tokens safe.
{% endhint %}

## User Authentication

The DBNL platform uses [OpenID Connect](https://openid.net/developers/how-connect-works/) or OIDC for user authentication. OIDC providers that are known to work with DBNL include:

* [Auth0](https://auth0.com/)
* [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id)
* [Okta](https://www.okta.com/)

{% hint style="warning" %}
The DBNL [Sandbox Deployment](https://docs.dbnl.com/v0.29.x/platform/deployment/sandbox) does not use OIDC for authentication, but just a default [username/password](https://docs.dbnl.com/v0.29.x/deployment/sandbox#authentication) for all users. For fuller authentication controls please consider a full [Deployment](https://docs.dbnl.com/v0.29.x/platform/deployment).
{% endhint %}

### Configuration

OIDC can be configured using the following options in the DBNL Helm chart or Terraform module:

* `audience`
* `clientId`
* `issuer`
* `scopes`

Instructions on how to get those options for each provider can be found below.

{% tabs %}
{% tab title="Auth0" %}

1. Follow the [Auth0 instructions](https://auth0.com/docs/get-started/auth0-overview/create-applications/single-page-web-apps) to create a new SPA (single page application).
   1. In *Settings > Application URIs*, add the DBNL deployment domain to the list of *Allowed Callback URLs* (e.g. dbnl.mydomain.com).
2. Navigate to *Settings > Basic Information* and copy the **Client ID** as the OIDC `clientId` option.
3. Navigate to *Settings > Basic Information* and copy the **Domain** and prepend with `https://` to use as the OIDC `issuer` option (e.g. `https://my-app.us.auth0.com/`).
4. Follow the [Auth0 instructions](https://auth0.com/docs/get-started/apis/api-settings) to create a custom API.
   1. Use your DBNL deployment domain as the Identifier (e.g. dbnl.mydomain.com).
5. Navigate to *Settings > General Settings* and copy the **Identifier** as the OIDC `audience` option.
6. Set the OIDC `scopes` option to `"openid profile email"`.
   {% endtab %}

{% tab title="Microsoft Entra ID" %}

1. Follow the [Microsoft Entra ID instructions](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc) to create a new SPA (single page application) and enable OIDC.
   1. Add the DBNL deployment domain as the callback URL (e.g. dbnl.mydomain.com).
2. \[Optional] Follow the [Microsoft Entra ID instructions](https://learn.microsoft.com/en-us/entra/identity-platform/howto-restrict-your-app-to-a-set-of-users) to restrict access to certain users.
3. Navigate to *App Registrations > (Application) > Manage > API permissions* and add the Microsoft Graph **email**, **openid** and **profile** permissions to the application.\
   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXd8pbhruvYAq8a5Vu_oal3hU8fEgW0DEVuKL_uawiFlYOG8IbZh5jmT1ma0TWzGr5c3Qa9KSMmifguvCLq01bNLe5IaPBwJd9Xd_2yWpHmRmTF6hUKgZ9ScOnIo4hrb4trssuFQrIpQVYlmw76dPFS0VXpc?key=RDpRvPFm_ApGIi4n-TMN1w)
4. Navigate to *App Registrations > (Application) > Manage > Manifest* and set access token version to 2.0 with `"accessTokenAcceptedVersion": 2` .
5. Navigate to *App Registrations > (Application) > Manage > Token configuration > Add optional claim > Access > email* to add the **email** optional claim to the access token type.\
   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeoOkKeWfMlgAps3i954ZPXoqB-qGmmiilsJLa73yWUCJqPFy1QrjHQVK8bdD7BehLGFt4hvAV6CuZuCL8Ki7uMa54-UA8RoBaJf-WdFKF1EFGX6208XB8swvXBLh1lr_9jj4JEwj3eggtXqN18pWI37zFe?key=RDpRvPFm_ApGIi4n-TMN1w)
6. Navigate to *App Registrations > (Application)* and copy the *Application (client) ID* (`APP_ID`) to be used as the OIDC `clientId` and OIDC `audience` options.
7. Set the OIDC `issuer` option to `https://login.microsoftonline.com/{APP_ID}/v2.0` .
8. Set the OIDC `scopes` option to `"openid email profile {APP_ID}/.default"`.
   {% endtab %}

{% tab title="Okta" %}

1. Follow the [Okta instructions](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) to create a new SPA (single page application) and enable OIDC.
   1. Set the *Sign-in redirect URIs* to your DBNL domain (e.g. dbnl.mydomain.com)
2. Navigate to *General > Client Credentials* and copy the Client ID to be used as the OIDC `clientId` option.
3. Navigate to *Sign on > OpenID Connect ID Token* and copy the *Issuer URL* to be used as the OIDC `issuer` and OIDC `audience` options.
4. Set the OIDC `scopes` option to `"openid email profile"` .
   {% endtab %}
   {% endtabs %}