Skip to content
This repository was archived by the owner on May 10, 2024. It is now read-only.

Commit 4c65791

Browse files
committed
docs: CIP-2: Auth Providers
- Merged all three tables into what which only lists first-party clients + server-side support for auth methods - Added Section for the Basic Auth (in the future we'll add more of those as auth methods are added) - Added Windows commands where applicable [DX]. - Added a common subsection how to create .htpasswd file Refs: chroma-core/chroma#986
1 parent a953a4a commit 4c65791

File tree

1 file changed

+64
-23
lines changed

1 file changed

+64
-23
lines changed

docs/usage-guide.md

Lines changed: 64 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -720,68 +720,109 @@ You can configure Chroma to use authentication when in server/client mode only.
720720

721721
Supported authentication methods are:
722722

723-
| Authentication Method | Description | Status |
724-
|-----------------------|---------------------------------------------------------------------------------------------------------------------------|---------|
725-
| Basic (Pre-emptive) | [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) Basic Auth with `user:password` base64-encoded `Authorization` header. | `Alpha` |
723+
| Authentication Method | Description | Status | Server-Side Support | Client/Python | Client/JS |
724+
|-----------------------|---------------------------------------------------------------------------------------------------------------------------|---------|---------------------|---------------|-----------|
725+
| Basic (Pre-emptive) | [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) Basic Auth with `user:password` base64-encoded `Authorization` header. | `Alpha` |`Alpha` |||
726726

727-
Client-side supported authentication methods per client:
727+
### Basic Authentication
728728

729-
| Authentication Method | Python | JS | Javascript | Ruby | Java | Go | C# | Rust |
730-
|-----------------------|--------|----|------------|------|------|----|----|------|
731-
| Basic Auth |||||||||
729+
<Tabs queryString groupId="lang" className="hideTabSwitcher">
730+
<TabItem value="py" label="Python">
732731

733-
Server-side supported authentication methods per server:
732+
#### Server Setup
734733

735-
| Authentication Method | Status |
736-
|-----------------------|-----------|
737-
| Basic Auth |`Alpha` |
738734

739-
<Tabs queryString groupId="lang" className="hideTabSwitcher">
740-
<TabItem value="py" label="Python">
735+
##### Generate Server-Side Credentials
741736

742-
### Server Setup
737+
:::note Security Practices
738+
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.
739+
:::
743740

744-
#### CLI
741+
**_Linux/MacOS:_**
745742

746743
```bash
747744
export CHROMA_USER=admin
748745
export CHROMA_PASSWORD=admin
749746
docker run --rm --entrypoint htpasswd httpd:2 -Bbn ${CHROMA_USER} ${CHROMA_PASSWORD} > server.htpasswd
747+
```
748+
749+
**_Windows:_**
750+
751+
```bash
752+
set CHROMA_USER=admin
753+
set CHROMA_PASSWORD=admin
754+
755+
docker run --rm --entrypoint htpasswd httpd:2 -Bbn %CHROMA_USER% %CHROMA_PASSWORD% > server.htpasswd
756+
```
757+
758+
##### CLI
759+
760+
```bash
750761
CHROMA_SERVER_AUTH_CREDENTIALS_FILE="./server.htpasswd" \
751762
CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER='chromadb.auth.providers.HtpasswdFileServerAuthCredentialsProvider' \
752763
CHROMA_SERVER_AUTH_PROVIDER='chromadb.auth.basic.BasicAuthServerProvider' \
753764
uvicorn chromadb.app:app --workers 1 --host 0.0.0.0 --port 8000 --proxy-headers --log-config log_config.yml
754765
```
755766

756-
#### Docker
767+
##### Docker
768+
769+
**_Linux/MacOS:_**
757770

758771
```bash
759-
export CHROMA_USER=admin
760-
export CHROMA_PASSWORD=admin
761-
docker run --rm --entrypoint htpasswd httpd:2 -Bbn ${CHROMA_USER} ${CHROMA_PASSWORD} > server.htpasswd
762772
cat << EOF > .env
763773
CHROMA_SERVER_AUTH_CREDENTIALS_FILE="/chroma/server.htpasswd"
764774
CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER='chromadb.auth.providers.HtpasswdFileServerAuthCredentialsProvider'
765775
CHROMA_SERVER_AUTH_PROVIDER='chromadb.auth.basic.BasicAuthServerProvider'
766776
EOF
777+
767778
docker-compose up -d --build
768779
```
769780

770-
#### Verify the Server
781+
**_Windows:_**
782+
783+
```bash
784+
echo CHROMA_SERVER_AUTH_CREDENTIALS_FILE="/chroma/server.htpasswd" > .env
785+
echo CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER='chromadb.auth.providers.HtpasswdFileServerAuthCredentialsProvider' >> .env
786+
echo CHROMA_SERVER_AUTH_PROVIDER='chromadb.auth.basic.BasicAuthServerProvider' >> .env
787+
788+
docker-compose up -d --build
789+
```
790+
791+
##### Verify the Server
792+
793+
Now let's verify that the server is running and that authentication is working.
794+
795+
**Success:**
771796

772-
Success:
797+
**_Linux/MacOS:_**
773798

774799
```bash
775800
curl -v http://localhost:8000/api/v1/collections -u admin:admin
776801
```
777802

778-
Auth failure:
803+
**_Windows:_**
804+
805+
```bash
806+
$headers = @{ Authorization = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("admin:admin")) }
807+
Invoke-RestMethod -Uri 'http://localhost:8000/api/v1/collections' -Headers $headers -Verbose
808+
```
809+
810+
**Auth failure:**
811+
812+
**_Linux/MacOS:_**
779813

780814
```bash
781815
curl -v http://localhost:8000/api/v1/collections -u admin:admin1
782816
```
783817

784-
### Client Setup
818+
**_Windows:_**
819+
820+
```bash
821+
$headers = @{ Authorization = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("admin:admin1")) }
822+
Invoke-RestMethod -Uri 'http://localhost:8000/api/v1/collections' -Headers $headers -Verbose
823+
````
824+
825+
#### Client Setup
785826

786827
```python
787828
import chromadb

0 commit comments

Comments
 (0)