Prior to setting up any authentication, we recommend setting up the base project using the make first-run
command. If you've already done so, you can skip ahead.
By default, the Toolkit does not enforce any authentication strategies, but they can be enabled from src/backend/config/auth.py
.
This is the current list of implemented Auth strategies:
-
BasicAuthentication: for email and password auth, no setup required.
-
GoogleOAuth: for authentication with a Gmail account.
- Requires a GCP project.
- Requires setting up Google OAuth 2.0.
- In your
secrets.yaml
file, update theauth.google_oauth.client_id
andauth.google_oauth.client_secret
variables.
-
OpenIDConnect: generic auth class for OpenIDConnectOAuth providers.
- Requires an OIDC app for your provider (Google, Microsoft, Amazon, etc.)
- In your
secrets.yaml
file, update theauth.oidc.client_id
,auth.oidc.client_secret
, andauth.oidc.well_known_endpoint
variables.
To enable one or more of these strategies, add them to the ENABLED_AUTH_STRATEGIES
list in the backend/config/auth.py
file, then add any required environment variables in your secrets.yaml
file, then generate a secret key to be used as the auth.secret_key
environment variable. This is used to encode and decode your access tokens for both login OAuth flows and Tool auth.
To generate an appropriate production auth.secret_key
value, you can use the following python code:
import secrets
print(secrets.token_hex(32))
When configuring your OAuth apps, make sure to whitelist the Redirect URI to the frontend endpoint, it should look like
<FRONTEND_HOST>/auth/<STRATEGY_NAME>
. For example, your Redirect URI will be http://localhost:4000/auth/google
if you're running the GoogleOAuth class locally.
Many OIDC-compliant auth providers also implement PKCE for added protection. This involves generating code_verifier
and code_challenge
values in the frontend and using these values to validate that the same entity that initially logged in with the auth provider is the one requesting an access token from an authorization code.
For more details click here.
To enable the additional PKCE auth flow, you will need to first ensure your auth provider is PKCE-compliant, then set the PKCE_ENABLED
class attribute in your OIDCConnect auth strategy to True
.
To implement a new strategy, refer to the backend/services/auth/strategies
folder. Auth strategies will need to inherit from one of two base classes, BaseAuthenticationStrategy
or BaseOAuthStrategy
.
If your strategy requires environment variables, create a new <AUTH_METHOD>Settings
class, you can refer to the settings.py
file for more examples.
OAuth strategies should implement the authorize
method to verify an authorization code and return an access token.
Notes:
- Currently, we only support OKTA for SCIM. We will add more providers as requested in the future.
- This only works if you already set up SSO via OIDC beforehand. We do not support password syncing.
SCIM allows you organization to synchronize your users and groups from your identity provider to the Toolkit. This has the benefit of:
- Automatically creating / deactivating users in the Toolkit when they are created / deactivated in your identity provider.
- Automatically assigning users to groups in the Toolkit when they are assigned to groups in your identity provider for access management.
- Fill in the following values in your configuration: SCIM_USER, SCIM_PASSWORD. Make sure to generate a secure secret for SCIM_PASSWORD
- Login to Okta as an Admin
- From the Left nav goto: Applications->Applications
- From the Applications screen, click “Browse App Catalog”:
- Search for the application: SCIM 2.0 Test App (Basic Auth)
- Click "Add Integration"
- For "Application Label" enter a name for the application (e.g: Cohere Toolkit)
- On the next screen leave the default configuration and click "Done"
- Navigate to the tab "Provisioning"
- Click "Configure API Integration"
- Activate "Enable API integration"
- Enter the following values:
- SCIM 2.0 Base Url:
https://your-domain/scim/v2
- Username: Set this to the value of SCIM_USER
- Password: Set this to the value of SCIM_PASSWORD
- SCIM 2.0 Base Url:
- Click "Test API Credentials" to verify the credentials
- Click "Save"
- Select "To App" on the left side
- Activate the following fields:
- Create Users
- Update User Attributes
- Deactivate Users
In this step you will synchronize selected users. Note that while we can select groups here, it will only sync users in those groups, not the groups itself. This needs to be done in the next step.
- Navigate to the "Assignments" tab
- Click either "Assign to People" or "Assign to Groups"
- Click "Save and Go Back"
This is optional but if groups should be synchronized, it needs to be configured like this:
- Navigate to "Push Groups"
- Click "Push Groups"
- Select "Find Groups by name"
- Enter the group you would like to push
- Select the group
- Click "Save"