|
1 | 1 | --- |
2 | | -title: Auth |
| 2 | +title: 🔒 Auth |
3 | 3 | --- |
| 4 | + |
| 5 | + |
| 6 | +You can configure Chroma to use authentication when in server/client mode only. |
| 7 | + |
| 8 | +Supported authentication methods: |
| 9 | + |
| 10 | +{% special_table %} |
| 11 | +{% /special_table %} |
| 12 | + |
| 13 | +| Authentication Method | Basic Auth (Pre-emptive) | Static API Token | |
| 14 | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | |
| 15 | +| Description | [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) Basic Auth with `user:password` base64-encoded `Authorization` header. | Static auth token in `Authorization: Bearer <token>` or in `X-Chroma-Token: <token>` headers. | |
| 16 | +| Status | `Alpha` | `Alpha` | |
| 17 | +| Server-Side Support | ✅ `Alpha` | ✅ `Alpha` | |
| 18 | +| Client/Python | ✅ `Alpha` | ✅ `Alpha` | |
| 19 | +| Client/JS | ✅ `Alpha` | ✅ `Alpha` | |
| 20 | + |
| 21 | +### Basic Authentication |
| 22 | + |
| 23 | +#### Server Setup |
| 24 | + |
| 25 | +##### Generate Server-Side Credentials |
| 26 | + |
| 27 | +{% note type="note" title="Security Practices" %} |
| 28 | +A good security practice is to store the password securely. In the example below we use [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) (currently the only supported hash in Chroma server side auth) to hash the plaintext password. |
| 29 | +{% /note %} |
| 30 | + |
| 31 | +To generate the password hash, run the following command: |
| 32 | + |
| 33 | +```bash |
| 34 | +docker run --rm --entrypoint htpasswd httpd:2 -Bbn admin admin > server.htpasswd |
| 35 | +``` |
| 36 | + |
| 37 | +This creates the bcrypt password hash for the password `admin` and puts it into `server.htpasswd` alongside the user `admin`. It will look like `admin:<password hash>`. |
| 38 | + |
| 39 | +##### Running the Server |
| 40 | + |
| 41 | +Set the following environment variables: |
| 42 | + |
| 43 | +```bash |
| 44 | +export CHROMA_SERVER_AUTHN_CREDENTIALS_FILE="server.htpasswd" |
| 45 | +export CHROMA_SERVER_AUTHN_PROVIDER="chromadb.auth.basic_authn.BasicAuthenticationServerProvider" |
| 46 | +``` |
| 47 | + |
| 48 | +And run the server as normal: |
| 49 | + |
| 50 | +```bash |
| 51 | +chroma run --path /db_path |
| 52 | +``` |
| 53 | + |
| 54 | +{% tabs group="code-lang" hideTabs=true %} |
| 55 | +{% tab label="Python" %} |
| 56 | + |
| 57 | +#### Client Setup |
| 58 | + |
| 59 | +```python |
| 60 | +import chromadb |
| 61 | +from chromadb.config import Settings |
| 62 | + |
| 63 | +client = chromadb.HttpClient( |
| 64 | + settings=Settings(chroma_client_auth_provider="chromadb.auth.basic_authn.BasicAuthClientProvider",chroma_client_auth_credentials="admin:admin")) |
| 65 | +client.heartbeat() # this should work with or without authentication - it is a public endpoint |
| 66 | + |
| 67 | +client.get_version() # this should work with or without authentication - it is a public endpoint |
| 68 | + |
| 69 | +client.list_collections() # this is a protected endpoint and requires authentication |
| 70 | +``` |
| 71 | + |
| 72 | +{% /tab %} |
| 73 | +{% tab label="Javascript" %} |
| 74 | + |
| 75 | +#### Client Setup |
| 76 | + |
| 77 | +```js |
| 78 | +import { ChromaClient } from "chromadb"; |
| 79 | + |
| 80 | +const client = new ChromaClient({ |
| 81 | + auth: { provider: "basic", credentials: "admin:admin" }, |
| 82 | +}); |
| 83 | +``` |
| 84 | + |
| 85 | + |
| 86 | +{% /tab %} |
| 87 | + |
| 88 | +{% /tabs %} |
| 89 | + |
| 90 | +### Static API Token Authentication |
| 91 | + |
| 92 | +{% note type="note" title="Tokens" %} |
| 93 | +Tokens must be alphanumeric ASCII strings. Tokens are case-sensitive. |
| 94 | +{% /note %} |
| 95 | + |
| 96 | +#### Server Setup |
| 97 | + |
| 98 | +{% note type="note" title="Security Note" %} |
| 99 | +Current implementation of static API token auth supports only ENV based tokens. |
| 100 | +{% /note %} |
| 101 | + |
| 102 | +##### Running the Server |
| 103 | + |
| 104 | +Set the following environment variables to use `Authorization: Bearer test-token` to be your authentication header. All environment variables can also be set as [Settings](https://docs.trychroma.com/deployment#step-5-configure-the-chroma-library). |
| 105 | + |
| 106 | +```bash |
| 107 | +export CHROMA_SERVER_AUTHN_CREDENTIALS="test-token" |
| 108 | +export CHROMA_SERVER_AUTHN_PROVIDER="chromadb.auth.token_authn.TokenAuthenticationServerProvider" |
| 109 | +``` |
| 110 | + |
| 111 | +To configure multiple tokens and use them for role-based access control (RBAC), use a file like [this](https://github.com/chroma-core/chroma/blob/main/examples/basic_functionality/authz/authz.yaml) and the following configuration settings: |
| 112 | + |
| 113 | +```bash |
| 114 | +export CHROMA_SERVER_AUTHN_CREDENTIALS_FILE=<path_to_authz.yaml> |
| 115 | +export CHROMA_SERVER_AUTHZ_CONFIG_FILE=<path_to_authz.yaml> # Note: these are the same! |
| 116 | +export CHROMA_SERVER_AUTHN_PROVIDER="chromadb.auth.token_authn.TokenAuthenticationServerProvider" |
| 117 | +export CHROMA_SERVER_AUTHZ_PROVIDER="chromadb.auth.simple_rbac_authz.SimpleRBACAuthorizationProvider" |
| 118 | +``` |
| 119 | + |
| 120 | +To use `X-Chroma-Token: test-token` type of authentication header you can set the `CHROMA_AUTH_TOKEN_TRANSPORT_HEADER` environment variable or configuration setting. |
| 121 | + |
| 122 | +```bash |
| 123 | +export CHROMA_SERVER_AUTHN_CREDENTIALS="test-token" |
| 124 | +export CHROMA_SERVER_AUTHN_PROVIDER="chromadb.auth.token_authn.TokenAuthenticationServerProvider" |
| 125 | +export CHROMA_AUTH_TOKEN_TRANSPORT_HEADER="X_CHROMA_TOKEN" |
| 126 | + |
| 127 | +{% tabs group="code-lang" hideTabs=true %} |
| 128 | +{% tab label="Python" %} |
| 129 | + |
| 130 | +#### Client Setup |
| 131 | + |
| 132 | +```python |
| 133 | +import chromadb |
| 134 | +from chromadb.config import Settings |
| 135 | +
|
| 136 | +client = chromadb.HttpClient( |
| 137 | + settings=Settings(chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider", |
| 138 | + chroma_client_auth_credentials="test-token")) |
| 139 | +client.heartbeat() # this should work with or without authentication - it is a public endpoint |
| 140 | +
|
| 141 | +client.get_version() # this should work with or without authentication - it is a public endpoint |
| 142 | +
|
| 143 | +client.list_collections() # this is a protected endpoint and requires authentication |
| 144 | +``` |
| 145 | + |
| 146 | +{% /tab %} |
| 147 | +{% tab label="Javascript" %} |
| 148 | + |
| 149 | +#### Client Setup |
| 150 | + |
| 151 | +Using the default `Authorization: Bearer <token>` header: |
| 152 | + |
| 153 | +```js |
| 154 | +import { ChromaClient } from "chromadb"; |
| 155 | +
|
| 156 | +const client = new ChromaClient({ |
| 157 | + auth: { provider: "token", credentials: "test-token" }, |
| 158 | +}); |
| 159 | +//or explicitly specifying the auth header type |
| 160 | +const client = new ChromaClient({ |
| 161 | + auth: { |
| 162 | + provider: "token", |
| 163 | + credentials: "test-token", |
| 164 | + tokenHeaderType: "AUTHORIZATION", |
| 165 | + }, |
| 166 | +}); |
| 167 | +``` |
| 168 | +
|
| 169 | +Using custom Chroma auth token `X-Chroma-Token: <token>` header: |
| 170 | +
|
| 171 | +```js |
| 172 | +import { ChromaClient } from "chromadb"; |
| 173 | +
|
| 174 | +const client = new ChromaClient({ |
| 175 | + auth: { |
| 176 | + provider: "token", |
| 177 | + credentials: "test-token", |
| 178 | + tokenHeaderType: "X_CHROMA_TOKEN", |
| 179 | + }, |
| 180 | +}); |
| 181 | +``` |
| 182 | +
|
| 183 | +
|
| 184 | +{% /tab %} |
| 185 | +
|
| 186 | +{% /tabs %} |
0 commit comments