Skip to main content
Weaviate Docs (migrated from docs.weaviate.io) Docs

Search documentation

Type to search this documentation.

On this pageOverview

OIDC Configuration

If OpenID Connect (OIDC) authentication is enabled, its details will be available through the /v1/.well-known/openid-configuration endpoint.

If a token is configured, the endpoint redirects to it.

The discovery endpoint accepts a GET request:

JavaScript
GET /v1/.well-known/openid-configuration

If there is an OIDC provider, the endpoint returns the following fields:

  • href: The reference to the client.
  • clientId: The ID of the client.

If there is no OIDC provider, the endpoint returns a 404 HTTP status code.

Python
open_id_configuration = client.get_open_id_configuration()

print(open_id_configuration)
JavaScript/TypeScript
import weaviate from 'weaviate-client';

const client = await weaviate.connectToLocal()
const response = await client.getOpenIDConfig()

console.log(response);
Go
package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v5/weaviate"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  openIDConfig, err := client.Misc().OpenIDConfigurationGetter().Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", openIDConfig)
}
Curl
curl http://localhost:8080/v1/.well-known/openid-configuration

If OIDC is configured, the endpoint returns a document like this:

JSON
{
  "href": "http://my-token-issuer/auth/realms/my-weaviate-usecase",
  "clientId": "my-weaviate-client"
}

The OIDC standard allows for many different methods (flows) of obtaining tokens. The appropriate method can vary depending on your situation, including configurations at the token issuer, and your requirements.

Here are some options to consider:

  1. Use the client credentials flow for machine-to-machine authorization. (Note that this authorizes an app, not a user.)
    • Validated using Okta and Azure as identity providers; GCP does not support client credentials grant flow (as of December 2022).
    • Weaviate's Python client directly supports this method.
    • Client credential flows usually do not come with a refresh token and the credentials are saved in the respective clients to acquire a new access token on expiration of the old one.
  2. Use the resource owner password flow for trusted applications.
  3. Use hybrid flow if Azure is your token issuer or if you would like to prevent exposing passwords.

The recommended pattern is to obtain an access token from your IdP using one of the flows above, then pass it to the Weaviate client as a bearer token. The client transparently attaches it to every request and, if a refresh token is provided, renews the access token before it expires.

The examples below show how each official client accepts a bearer token. See Get and pass tokens manually for an end-to-end example of the token-acquisition step (talking to your IdP), or use your IdP's SDK.

Python
import os
import weaviate
from weaviate.classes.init import Auth

# Connect to a self-hosted Weaviate instance configured with OIDC.
# Obtain the access token from your identity provider before connecting.
client = weaviate.connect_to_custom(
    http_host="localhost",
    http_port=8580,
    http_secure=False,
    grpc_host="localhost",
    grpc_port=50551,
    grpc_secure=False,
    auth_credentials=Auth.bearer_token(
        access_token=os.environ["WEAVIATE_OIDC_ACCESS_TOKEN"],
        refresh_token=os.environ.get("WEAVIATE_OIDC_REFRESH_TOKEN"),
        expires_in=int(os.environ.get("WEAVIATE_OIDC_EXPIRES_IN", "60")),
    ),
)
JavaScript/TypeScript
// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
const client = await weaviate.connectToCustom({
  httpHost: 'localhost',
  httpPort: 8580,
  httpSecure: false,
  grpcHost: 'localhost',
  grpcPort: 50551,
  grpcSecure: false,
  authCredentials: new weaviate.AuthAccessTokenCredentials({
    accessToken: process.env.WEAVIATE_OIDC_ACCESS_TOKEN!,
    refreshToken: process.env.WEAVIATE_OIDC_REFRESH_TOKEN,
    expiresIn: Number(process.env.WEAVIATE_OIDC_EXPIRES_IN ?? 60),
  }),
});
Go
// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
cfg := weaviate.Config{
    Host:   os.Getenv("WEAVIATE_HTTP_HOST"),
    Scheme: "http",
    AuthConfig: auth.BearerToken{
        AccessToken:  os.Getenv("WEAVIATE_OIDC_ACCESS_TOKEN"),
        RefreshToken: os.Getenv("WEAVIATE_OIDC_REFRESH_TOKEN"),
        ExpiresIn:    60,
    },
}
client, err := weaviate.NewClient(cfg)
if err != nil{
    fmt.Println(err)
}
Java
// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
String accessToken = System.getenv("WEAVIATE_OIDC_ACCESS_TOKEN");
String refreshToken = System.getenv("WEAVIATE_OIDC_REFRESH_TOKEN");
long expiresIn = Long.parseLong(
    System.getenv().getOrDefault("WEAVIATE_OIDC_EXPIRES_IN", "60"));

WeaviateClient client = WeaviateClient.connectToCustom(config -> config
    .scheme("http")
    .httpHost("localhost")
    .httpPort(8580)
    .grpcHost("localhost")
    .grpcPort(50551)
    .authentication(Authentication.bearerToken(accessToken, refreshToken, expiresIn)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources
C#
// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
var accessToken = Environment.GetEnvironmentVariable("WEAVIATE_OIDC_ACCESS_TOKEN")!;
var refreshToken = Environment.GetEnvironmentVariable("WEAVIATE_OIDC_REFRESH_TOKEN") ?? "";
var expiresIn = int.Parse(Environment.GetEnvironmentVariable("WEAVIATE_OIDC_EXPIRES_IN") ?? "60");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: "localhost",
        restPort: "8580",
        grpcEndpoint: "localhost",
        grpcPort: "50551",
        useSsl: false,
        credentials: Auth.BearerToken(accessToken, expiresIn, refreshToken)
    )
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);

When you use an API key to authenticate to Weaviate, add the API key in the request header.

The format is: Authorization: Bearer WEAVIATE_API_KEY. Replace WEAVIATE_API_KEY with the API key for your Weaviate instance.

For example, the cURL command looks like this:

Bash
curl https://localhost:8080/v1/objects -H "Authorization: Bearer ${WEAVIATE_API_KEY}" | jq
Manually obtaining and passing tokens

For cases or workflows where you may wish to manually obtain a token, we outline below the steps to do so, for the resource owner password flow and hybrid flow.

Resource owner password flow

  1. Send a GET request to WEAVIATE_INSTANCE_URL/v1/.well-known/openid-configuration to fetch Weaviate's OIDC configuration (wv_oidc_config). Replace WEAVIATE_INSTANCE_URL with your instance URL.
  2. Parse the clientId and href from wv_oidc_config.
  3. Send a GET request to href to fetch the token issuer's OIDC configuration (token_oidc_config).
  4. If token_oidc_config includes the optional grant_types_supported key, check that password is in the list of values.
    • If password is not in the list of values, the token issuer is likely not configured for resource owner password flow. You may need to reconfigure the token issuer or use another method.
    • If the grant_types_supported key is not available, you may need to contact the token issuer to see if resource owner password flow is supported.
  5. Send a POST request to the token_endpoint of token_oidc_config with the body:
    • {"grant_type": "password", "client_id": client_id, "username": USERNAME, "password": PASSWORD. Replace USERNAME and PASSWORD with the actual values.
  6. Parse the response (token_resp), and look for access_token in token_resp. This is your Bearer token.

Hybrid flow

  1. Send a GET request to WEAVIATE_INSTANCE_URL/v1/.well-known/openid-configuration to fetch Weaviate's OIDC configuration (wv_oidc_config). Replace WEAVIATE_INSTANCE_URL with your instance URL.
  2. Parse the clientId and href from wv_oidc_config
  3. Send a GET request to href to fetch the token issuer's OIDC configuration (token_oidc_config)
  4. Construct a URL (auth_url) with the following parameters, based on authorization_endpoint from token_oidc_config. This will look like the following:
    • {authorization_endpoint}?client_id={clientId}&response_type=code%20id_token&response_mode=fragment&redirect_url={redirect_url}&scope=openid&nonce=abcd
    • the redirect_url must have been pre-registered with your token issuer.
  5. Go to the auth_url in your browser, and log in if prompted. If successful, the token issuer will redirect the browser to the redirect_url, with additional parameters that include an id_token parameter.
  6. Parse the id_token parameter value. This is your Bearer token.

Code example

This example demonstrate how to obtain an OIDC token.

Python
import requests
import re

url = "http://localhost:8080"  # <-- Replace with your actual Weaviate URL

# Get Weaviate's OIDC configuration
weaviate_open_id_config = requests.get(url + "/v1/.well-known/openid-configuration")
if weaviate_open_id_config.status_code == "404":
    print("Your Weaviate instance is not configured with openid")

response_json = weaviate_open_id_config.json()
client_id = response_json["clientId"]
href = response_json["href"]

# Get the token issuer's OIDC configuration
response_auth = requests.get(href)

if "grant_types_supported" in response_auth.json():
    # For resource owner password flow
    assert "password" in response_auth.json()["grant_types_supported"]

    username = "username"  # <-- Replace with the actual username
    password = "password"  # <-- Replace with the actual password

    # Construct the POST request to send to 'token_endpoint'
    auth_body = {
        "grant_type": "password",
        "client_id": client_id,
        "username": username,
        "password": password,
    }
    response_post = requests.post(response_auth.json()["token_endpoint"], auth_body)
    print("Your access_token is:")
    print(response_post.json()["access_token"])
else:
    # For hybrid flow
    authorization_url = response_auth.json()["authorization_endpoint"]
    parameters = {
        "client_id": client_id,
        "response_type": "code%20id_token",
        "response_mode": "fragment",
        "redirect_url": url,
        "scope": "openid",
        "nonce": "abcd",
    }
    # Construct 'auth_url'
    parameter_string = "&".join([key + "=" + item for key, item in parameters.items()])
    response_auth = requests.get(authorization_url + "?" + parameter_string)

    print("To login, open the following url with your browser:")
    print(authorization_url + "?" + parameter_string)
    print(
        "After the login you will be redirected, the token is the 'id_token' parameter of the redirection url."
    )

    # You could use this regular expression to parse the token
    resp_txt = "Redirection URL"
    token = re.search("(?<=id_token=).+(?=&)", resp_txt)[0]

print("Set as bearer token in the clients to access Weaviate.")

Token lifetime

The token has a configurable expiry time that is set by the token issuer. We suggest establishing a workflow to periodically obtain a new token before expiry.

Configuring the OIDC token issuer is outside the scope of Weaviate's configuration, but here are a few options as a starting point:

  • You can use commercial OIDC providers like Okta.
  • You can run your own OIDC token issuer server. Popular open-source solutions include Java-based Keycloak and Golang-based dex.

Have a question or feedback? Here's how to reach us.

Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu