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 for more information on installing dittofeed-ee.

Setup

Multi-tenancy utilizes OIDC (OpenID Connect) 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.
.env
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/dittofeed/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.

Generating a Secret Key

See our documentation on Authentication Modes for instructions on how to generate a new SECRET_KEY.

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
.env
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.
.env
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 ClientsCreate 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