# Authentication :::callout{intent="info" title="Authentication and authorization"} Authentication and authorization are closely related concepts, and sometimes abbreviated as `AuthN` and `AuthZ`. Authentication (`AuthN`) is the process of verifying the identity of a user, while authorization (`AuthZ`) is the process of determining what permissions the user has. ::: Weaviate controls access through user authentication via API keys or OpenID Connect (OIDC), with an option for anonymous access. Users can then be assigned different [authorization](deploy-configuration-authorization.md) levels, as shown in the diagram below. ```mermaid flowchart LR %% Define main nodes Request["Client
Request"] AuthCheck{"AuthN
Enabled?"} AccessCheck{"Check
AuthZ"} Access["✅ Access
Granted"] Denied["❌ Access
Denied"] %% Define authentication method nodes subgraph auth ["AuthN"] direction LR API["API Key"] OIDC["OIDC"] AuthResult{"Success?"} end %% Define connections Request --> AuthCheck AuthCheck -->|"No"| AccessCheck AuthCheck -->|"Yes"| auth API --> AuthResult OIDC --> AuthResult AuthResult -->|"Yes"| AccessCheck AuthResult -->|"No"| Denied AccessCheck -->|"Pass"| Access AccessCheck -->|"Fail"| Denied %% Style nodes style Request fill:#ffffff,stroke:#B9C8DF,color:#130C49 style AuthCheck fill:#ffffff,stroke:#B9C8DF,color:#130C49 style AccessCheck fill:#ffffff,stroke:#B9C8DF,color:#130C49 style Access fill:#ffffff,stroke:#B9C8DF,color:#130C49 style Denied fill:#ffffff,stroke:#B9C8DF,color:#130C49 style API fill:#ffffff,stroke:#B9C8DF,color:#130C49 style OIDC fill:#ffffff,stroke:#B9C8DF,color:#130C49 style AuthResult fill:#ffffff,stroke:#B9C8DF,color:#130C49 %% Style subgraph style auth fill:#ffffff,stroke:#130C49,stroke-width:2px,color:#130C49 ``` For example, a user logging in with the API key `jane-secret` may be granted administrator permissions, while another user logging in with the API key `ian-secret` may be granted read-only permissions. In summary, Weaviate allows the following authentication methods: - API key - OpenID Connect (OIDC) - Anonymous access (no authentication, strongly discouraged except for development or evaluation) Note that API key and OIDC authentication can be both enabled at the same time. The way to configure authentication differs by your deployment method, depending on whether you are running Weaviate in Docker or Kubernetes. Below, we provide examples for both. :::callout{intent="info" title="What about Weaviate Cloud (WCD)?"} For Weaviate Cloud (WCD) instances, authentication is pre-configured with API key access. You can [authenticate against Weaviate](../connect-to-weaviate/connect-cloud.md) [with API keys](../manage-clusters/connect.md). ::: ## API Key Authentication API key authentication is a simple and effective way to authenticate users. Each user is assigned a unique API key, which is used to authenticate the user. ### API keys: Database users When [creating database users programmatically](weaviate-configuration-rbac-manage-users.md#create-a-database-user), each user is assigned a distinct API key at creation time. These API keys can also be [regenerated (rotated)](weaviate-configuration-rbac-manage-users.md#rotate-database-user-api-key). ### API keys: Docker API key authentication can be configured using environment variables. In Docker Compose, set them in the configuration file (`docker-compose.yml`) such as in the following example: ```yaml services: weaviate: ... environment: ... # Disable anonymous access. AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false' # Enables API key authentication. AUTHENTICATION_APIKEY_ENABLED: 'true' # List one or more keys in plaintext separated by commas. Each key corresponds to a specific user identity below. AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'user-a-key,user-b-key' # List one or more user identities, separated by commas. Each identity corresponds to a specific key above. AUTHENTICATION_APIKEY_USERS: 'user-a,user-b' ``` This configuration: - Disables anonymous access - Enables API key authentication - Defines plaintext API keys in `AUTHENTICATION_APIKEY_ALLOWED_KEYS` - Associates users with the API keys in `AUTHENTICATION_APIKEY_USERS` These users can now be assigned permissions based on the authorization settings. :::callout{intent="tip" title="TIP: User management API available from `v1.30`"} Instead of adding additional users via the `AUTHENTICATION_APIKEY_USERS` environment variable, we suggest using the [user management API](weaviate-configuration-rbac-manage-users.md) which you can use to create and delete users, manage their roles and rotate their API keys. ::: :::callout{intent="note"} Note that you can either: - Set one user for all API keys, or - Define one user per API key (the number of users must match the number of API keys) Make sure all listed users are also configured in the authorization settings. ::: ### API keys: Kubernetes For Kubernetes deployments using Helm, API key authentication can be configured in the `values.yaml` file under the `authentication` section. Here's an example configuration: ```yaml authentication: anonymous_access: # Disable anonymous access. enabled: false apikey: # Enables API key authentication. enabled: true # List one or more keys in plaintext separated by commas. Each key corresponds to a specific user identity below. allowed_keys: - user-a-key - user-b-key # List one or more user identities, separated by commas. Each identity corresponds to a specific key above. users: - user-a - user-b ``` This configuration: - Disables anonymous access - Enables API key authentication - Defines plaintext API keys in `allowed_keys` - Associates users with the API keys in `users` :::callout{intent="warning" title="Environment Variables Take Precedence"} If you configure API keys using environment variables, those settings will take precedence over the values in `values.yaml`. To use the Helm values configuration, ensure you have not set the corresponding environment variables. ::: For enhanced security in production environments, you can store API keys in Kubernetes secrets and reference them using environment variables instead of storing them as plaintext in the Helm values. ## OIDC Authentication OIDC authentication requires the resource (Weaviate) to validate tokens issued by an identity provider. The identity provider authenticates the user and issues tokens, which are then validated by Weaviate. Any "OpenID Connect" compatible token issuer that implements OpenID Connect Discovery is compatible with Weaviate. This document discusses how to configure Weaviate as the resource. For details on OIDC flows, token handling, and configuring a token issuer, see the [OIDC configuration guide](deploy-configuration-oidc.md). :::accordion{title="More about OIDC"} With [OpenID Connect](https://openid.net/connect/) (based on OAuth2), an external identity provider and token issuer ('token issuer' hereafter) is responsible for managing users. OIDC authentication requires obtaining a valid token from the token issuer so that it can be sent in the header of any request to Weaviate. This applies to both REST and GraphQL requests. When Weaviate receives a token (JSON Web Token or JWT), it verifies that it was indeed signed by the configured token issuer. If the signature is correct, all contents of the token are trusted, which authenticates the user based on the information in the token. ::: :::callout{intent="tip" title="TIP: OIDC and RBAC"} The [user management API](weaviate-configuration-rbac-manage-users.md#oidc-users-permissions-management) allows you to assign custom roles and permissions to OIDC users via [Role-Based Access Control (RBAC)](weaviate-configuration-rbac.md). ::: ### OIDC: Docker To configure Weaviate for OIDC-based authentication, add the following environment variables to your configuration file. An example `docker-compose.yml` file looks like this: ```yaml services: weaviate: ... environment: ... # enabled (optional - defaults to false) turns OIDC auth on. All other fields in # this section will only be validated if enabled is set to true. AUTHENTICATION_OIDC_ENABLED: 'true' # issuer (required) tells weaviate how to discover the token issuer. This # endpoint must implement the OpenID Connect Discovery spec, so that weaviate # can retrieve the issuer's public key. # # The example URL below uses the path structure commonly found with keycloak # where an example realm 'my-weaviate-usecase' was created. The exact # path structure depends on the token issuer. See the token issuer's documentation # about which endpoint implements OIDC Discovery. AUTHENTICATION_OIDC_ISSUER: 'http://my-token-issuer/auth/realms/my-weaviate-usecase' # client_id (required unless skip_client_id_check is set to true) tells # Weaviate to check for a particular OAuth 2.0 client_id in the audience claim. # This is to prevent that a token which was signed by the correct issuer # but never intended to be used with Weaviate can be used for authentication. # # For more information on what clients are in OAuth 2.0, see # https://tools.ietf.org/html/rfc6749#section-1.1 AUTHENTICATION_OIDC_CLIENT_ID: 'my-weaviate-client' # username_claim (required) tells Weaviate which claim in the token to use for extracting # the username. The username will be passed to the authorization plugin. AUTHENTICATION_OIDC_USERNAME_CLAIM: 'email' # skip_client_id_check (optional, defaults to false) skips the client_id # validation in the audience claim as outlined in the section above. # Not recommended to set this option as it reduces security, only set this # if your token issuer is unable to provide a correct audience claim AUTHENTICATION_OIDC_SKIP_CLIENT_ID_CHECK: 'false' # scope (optional) these will be used by clients as default scopes for authentication AUTHENTICATION_OIDC_SCOPES: '' ``` :::callout{intent="info" title="OIDC and Azure"} As of November 2022, we were aware of some differences in Microsoft Azure's OIDC implementation compared to others. If you are using Azure and experiencing difficulties, [this external blog post](https://xsreality.medium.com/making-azure-ad-oidc-compliant-5734b70c43ff) may be useful. ::: ### OIDC: Kubernetes For Kubernetes deployments using Helm, OIDC authentication can be configured in the `values.yaml` file under the `authentication` section. Here's an example configuration: ```yaml authentication: anonymous_access: # Disable anonymous access. enabled: false oidc: # enabled (optional - defaults to false) turns OIDC auth on. All other fields in # this section will only be validated if enabled is set to true. enabled: true # issuer (required) tells weaviate how to discover the token issuer. This # endpoint must implement the OpenID Connect Discovery spec, so that weaviate # can retrieve the issuer's public key. # # The example URL below uses the path structure commonly found with keycloak # where an example realm 'my-weaviate-usecase' was created. The exact # path structure depends on the token issuer. See the token issuer's documentation # about which endpoint implements OIDC Discovery. issuer: "http://my-token-issuer/auth/realms/my-weaviate-usecase" # client_id (required unless skip_client_id_check is set to true) tells # Weaviate to check for a particular OAuth 2.0 client_id in the audience claim. # This is to prevent that a token which was signed by the correct issuer # but never intended to be used with Weaviate can be used for authentication. # # For more information on what clients are in OAuth 2.0, see # https://tools.ietf.org/html/rfc6749#section-1.1 client_id: "my-weaviate-client" # username_claim (required) tells Weaviate which claim in the token to use for extracting # the username. The username will be passed to the authorization plugin. username_claim: "email" # skip_client_id_check (optional, defaults to false) skips the client_id # validation in the audience claim as outlined in the section above. # Not recommended to set this option as it reduces security, only set this # if your token issuer is unable to provide a correct audience claim skip_client_id_check: "false" # scope (optional) these will be used by clients as default scopes for authentication scopes: "" # groups_claim: '' ``` ## Anonymous Access Weaviate can be configured to accept anonymous requests. This is strongly discouraged except for development or evaluation purposes. Users that send requests without explicit authentication are authenticated as `user: anonymous`. You can use the authorization plugin to specify which permissions to apply to this `anonymous` user. If anonymous access is disabled altogether, any request without an allowed authentication scheme returns `401 Unauthorized`. ### Anonymous access: Docker To enable anonymous access in Docker Compose, add the following environment variable to your configuration file: ```yaml services: weaviate: ... environment: ... AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true' ``` ### Anonymous access: Kubernetes To enable anonymous access in Kubernetes, add the following configuration to your `values.yaml` file: ```yaml authentication: anonymous_access: enabled: true ``` ## Further resources - [Configuration: Authorization and RBAC](deploy-configuration-authorization.md) - [References: Environment variables / Authentication and Authorization](../database-configuration/overview.md#authentication-and-authorization) ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=