You can configure Chroma to use authentication when in server/client mode only.
Supported authentication methods:
| Authentication Method | Basic Auth (Pre-emptive) | Static API Token |
|---|---|---|
| Description | RFC 7617 Basic Auth with user:password base64-encoded Authorization header. | Static auth token in Authorization: Bearer <token> or in X-Chroma-Token: <token> headers. |
| Status | Alpha | Alpha |
| Server-Side Support | ✅ Alpha | ✅ Alpha |
| Client/Python | ✅ Alpha | ✅ Alpha |
| Client/JS | ✅ Alpha | ✅ Alpha |
In this guide we will add authentication to a simple Chroma server running locally using our CLI:
We also have dedicated auth guides for various deployments:
Encrypted User:Password Authentication#
Server Set-Up#
Generate Server-Side Credentials#
Security Practices
A good security practice is to store the password securely. In the example below we use bcrypt (currently the only supported hash in Chroma server side auth) to hash the plaintext password. If you'd like to see support for additional hash functions, feel free to contribute new ones!
To generate the password hash, run the following command (you may need to install httpasswd):
This creates the bcrypt password hash for the password admin, for the admin user, and puts it into server.htpasswd in your current working directory. It will look like admin:<password hash>.
Running the Server#
Set the following environment variables:
And run the Chroma server:
Client Set-Up#
We will use Chroma's Settings object to define the authentication method on the client.
We recommend setting the environment variable CHROMA_CLIENT_AUTH_CREDENTIALS instead of specifying the credentials in code.
Static API Token Authentication#
Server Set-Up#
Security Note
Current implementation of static API token auth supports only ENV based tokens. Tokens must be alphanumeric ASCII strings. Tokens are case-sensitive.
If, for example, you want the static API token to be "test-token", set the following environment variables. This will set Authorization: Bearer test-token as your authentication header.
To use X-Chroma-Token: test-token type of authentication header you can set the CHROMA_AUTH_TOKEN_TRANSPORT_HEADER environment variable:
Then, run the Chroma server:
To configure multiple tokens and use them for role-based access control (RBAC), use a file like this and the following environment variables:
Client Set-Up#
We will use Chroma's Settings object to define the authentication method on the client.
If you are using a custom CHROMA_AUTH_TOKEN_TRANSPORT_HEADER (like X-Chroma-Token), add it to your Settings:
We recommend setting the environment variable CHROMA_CLIENT_AUTH_CREDENTIALS instead of specifying the token in code. Similarly, you can read the value of CHROMA_AUTH_TOKEN_TRANSPORT_HEADER in the client construction.