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

# multi-tenant Auth Mode

> Enable multi-tenancy in your Dittofeed instance.

Multi-tenancy, facilitated by the `multi-tenant` "auth mode", allows you to run multiple Dittofeed workspaces on a single instance of Dittofeed. These workspaces allow you to isolate data for different customers, and can be managed programmatically.

The `multi-tenant` auth mode also provides separate workspace member accounts, which can log into Dittofeed using their own credentials and permissions.

The `multi-tenant` auth mode is only available in dittofeed-ee, and Dittofeed cloud. See [dittofeed-ee](/deployment/self-hosted/dittofeed-ee) for more information on installing dittofeed-ee.

## Setup

Multi-tenancy utilizes OIDC ([OpenID Connect](https://openid.net/developers/how-connect-works/)) for authentication. To enable multi-tenancy, you will need to configure an OIDC provider.

### Auth0

In order to configure Auth0 as an OIDC provider for multi-tenancy, use the following environment variables.

```bash .env theme={null}
OPEN_ID_CLIENT_ID='<your-auth0-client-id>'
OPEN_ID_CLIENT_SECRET='<your-auth0-client-secret>'
SECRET_KEY='<your-secret-key>'
AUTH_MODE='multi-tenant'
AUTH_PROVIDER='auth0'
SIGNOUT_URL='/dashboard/signout'
# Example: https://dittofeed.us.auth0.com/
OPEN_ID_ISSUER='https://<your-auth0-domain>.auth0.com/'
OPEN_ID_AUTHORIZATION_URL='https://<your-auth0-domain>.auth0.com/authorize'
OPEN_ID_TOKEN_URL='https://<your-auth0-domain>.auth0.com/oauth/token'
OPEN_ID_USER_INFO_URL='https://<your-auth0-domain>.auth0.com/userinfo'
```

#### Configuring Auth0

In auth0 create a Regular Web Application.

Then in the settings of the application, (`https://manage.auth0.com/dashboard/us/<organization-name>/applications/<application-id>/settings`) take the following actions.

* Copy the `Client ID` which will be used as the `OPEN_ID_CLIENT_ID`.
* Copy the `Client Secret` which will be used as the `OPEN_ID_CLIENT_SECRET`.
* Add a callback URL of the form `https://<your-dittofeed-instance>/dashboard/oauth2/callback`.
* Add a `Logout URL` of the form `https://<your-dittofeed-instance>/dashboard/signout/complete`.
* Add an `Allowed Web Origins` of the form `https://<your-dittofeed-instance>`.
* Allow Cross-Origin Authentication.
* Click Save Changes.

### AWS Cognito

In order to configure AWS Cognito as an OIDC provider for multi-tenancy, use the following environment variables.

Note that many of these values can be found on your Cognito user pool's `OpenID Connect` settings page.

`https://cognito-idp.<your-region>.amazonaws.com/<your-user-pool-id>/.well-known/openid-configuration`

```bash .env theme={null}
OPEN_ID_CLIENT_ID='<your-cognito-client-id>'
OPEN_ID_CLIENT_SECRET='<your-cognito-client-secret>'
SECRET_KEY='<your-secret-key>'
AUTH_MODE='multi-tenant'
AUTH_PROVIDER='cognito'
SIGNOUT_URL='/dashboard/signout'
OPEN_ID_ISSUER=https://cognito-idp.us-east-1.amazonaws.com/<your-user-pool-id>
OPEN_ID_AUTHORIZATION_URL='https://<your-user-pool-id>.auth.<your-region>.amazoncognito.com/oauth2/authorize'
OPEN_ID_TOKEN_URL='https://<your-user-pool-id>.auth.<your-region>.amazoncognito.com/oauth2/token'
OPEN_ID_USER_INFO_URL='https://<your-user-pool-id>.auth.<your-region>.amazoncognito.com/oauth2/userInfo'
OPEN_ID_END_SESSION_ENDPOINT='https://<your-user-pool-id>.auth.<your-region>.amazoncognito.com/logout'
OPEN_ID_RETURN_TO_QUERY_PARAM=logout_uri
```

#### Configuring Cognito

* Create a new user pool using a traditional web application.
* Create a new App client.
* Configure your app client as follows:
  * Set the "Allowed callback Urls": `https://<your-dittofeed-instance>/dashboard/oauth2/callback`
  * Set Allowed sign-out URLs: `https://<your-dittofeed-instance>/dashboard/signout/complete`
  * Select the "OAuth 2.0 grant types": Authorization code grant
  * Select the "OpenID Connect scopes": Email, OpenID, and Profile

### Keycloak

In order to configure Keycloak as an OIDC provider for multi-tenancy, use the following environment variables.

```bash .env theme={null}
OPEN_ID_CLIENT_ID='<your-keycloak-client-id>'
OPEN_ID_CLIENT_SECRET='<your-keycloak-client-secret>'
SECRET_KEY='<your-secret-key>'
AUTH_MODE='multi-tenant'
AUTH_PROVIDER='keycloak'
SIGNOUT_URL='/dashboard/signout'
OPEN_ID_ISSUER='https://<your-keycloak-domain>/realms/<your-realm-name>'
OPEN_ID_AUTHORIZATION_URL='https://<your-keycloak-domain>/realms/<your-realm-name>/protocol/openid-connect/auth'
OPEN_ID_TOKEN_URL='https://<your-keycloak-domain>/realms/<your-realm-name>/protocol/openid-connect/token'
OPEN_ID_USER_INFO_URL='https://<your-keycloak-domain>/realms/<your-realm-name>/protocol/openid-connect/userinfo'
OPEN_ID_END_SESSION_ENDPOINT='https://<your-keycloak-domain>/realms/<your-realm-name>/protocol/openid-connect/logout'
OPEN_ID_RETURN_TO_QUERY_PARAM='post_logout_redirect_uri'
```

#### Configuring Keycloak

1. **Access Keycloak Admin Console**
   * Navigate to `https://<your-keycloak-domain>`
   * Login with admin credentials

2. **Create a Realm**
   * Click on the dropdown in the top-left corner (likely showing "Master")
   * Click "Create Realm"
   * Name it `dittofeed` (or your preferred realm name)
   * Click "Create"

3. **Create an OpenID Connect Client**
   * Navigate to **Clients** → **Create client**
   * **General Settings:**
     * Client type: `OpenID Connect`
     * Client ID: `dittofeed-client` (this will be your `OPEN_ID_CLIENT_ID`)
   * Click **Next**
   * **Capability config:**
     * Client authentication: `ON`
     * Authorization: `OFF`
     * Standard flow: `ON`
     * Direct access grants: `OFF`
   * Click **Next**
   * **Login settings:**
     * Valid redirect URIs:
       * `https://<your-dittofeed-domain>/dashboard/oauth2/callback`
     * Valid post logout redirect URIs:
       * `https://<your-dittofeed-domain>/dashboard/signout/complete`
     * Web origins:
       * `https://<your-dittofeed-domain>`
   * Click **Save**

4. **Get Client Secret**
   * Navigate to **Clients** → Select `dittofeed-client`
   * Go to the **Credentials** tab
   * Copy the **Client secret** (this will be your `OPEN_ID_CLIENT_SECRET`)

5. **Configure Client Scopes**
   * The default scopes (openid, profile, email) should be sufficient
   * If needed, navigate to **Client scopes** to customize

#### Verifying the Configuration

You can verify your Keycloak OIDC configuration by accessing the discovery endpoint:

```
https://<your-keycloak-domain>/realms/dittofeed/.well-known/openid-configuration
```

This endpoint will show all available OIDC endpoints for your realm.

#### Notes

* The `AUTH_PROVIDER` environment variable should be set to `keycloak` for proper provider identification
* The `OPEN_ID_RETURN_TO_QUERY_PARAM` for Keycloak is `post_logout_redirect_uri`.
* Ensure your Keycloak instance is accessible from your Dittofeed application
* For production deployments, always use HTTPS for all URLs

### Generating a Secret Key

See our documentation on [Authentication Modes](/deployment/self-hosted/auth-modes) for instructions on how to generate a new `SECRET_KEY`.

### Enabling PKCE

If your OIDC provider requires PKCE (e.g., strict Keycloak setups), enable it with the environment variable below:

```bash .env theme={null}
ENABLE_PKCE='true'
```

PKCE is disabled by default. When enabled, Dittofeed will generate PKCE code challenges for `/dashboard/login` and include the matching verifier on `/dashboard/oauth2/callback`.