Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Configure JWT Authentication

  • how-to
Operational Insights supports JSON Web Token (JWT) authentication, allowing clients to authenticate using bearer tokens issued by a trusted Identity Provider instead of a username and password.

Prerequisites

To use JWT authentication with Operational Insights, you need:

Identity Provider (IdP)

The trusted server that verifies a user’s credentials and issues a signed JWT. Any OpenID Connect-compatible identity provider can serve as the IdP. For setup instructions, see the documentation for your IdP — for example, Keycloak or Okta.

JSON Web Token (JWT)

A self-contained, signed token with three parts: a header, a payload containing user claims, and a cryptographic signature. The signature proves the token has not been tampered with.

Operational Insights as Resource Server

Operational Insights does not store user passwords. Instead, it receives a JWT, verifies its signature against the IdP public keys using JWKS, examines the claims to determine identity and permissions, and then enforces authorization.

Before you begin, also confirm:

  • Your IdP issues JWT tokens and has a publicly accessible JWKS URI.

  • You have the JWKS URI, the issuer name (the iss claim value), the signing algorithm, and the audience values from your IdP.

  • You’re running Operational Insights 2.2 or later.

  • You have administrator credentials for Operational Insights. For more information about how to configure credentials, see Manage Users, Groups, and Roles.

Configure JWT Authentication

Use the REST API to enable JWT authentication, register your IdP, and optionally enable bearer token support for SDK clients.

Step 1: Enable JWT and Register Your IdP

Use PUT /settings/jwt to enable JWT authentication and register your IdP as a trusted issuer.

curl -sv -X PUT http://localhost:8091/settings/jwt \
  -H 'Content-Type: application/json' \
  -u $ADMIN_USERNAME:$ADMIN_PASSWORD \
  -d '{
    "enabled": true,
    "issuers": [{
      "name": "https://your-idp.example.com/realms/cb",
      "signingAlgorithm": "RS256",
      "subClaim": "preferred_username",
      "audClaim": "azp",
      "audienceHandling": "any",
      "audiences": ["your-client-id"],
      "publicKeySource": "jwks_uri",
      "jwksUri": "https://your-idp.example.com/realms/cb/protocol/openid-connect/certs",
      "jwksUriTlsVerifyPeer": true
    }]
  }'

The key parameters in the issuers object are:

Parameter Description

name

The value of the iss (issuer) claim in the JWT. The value must match the issuer field in tokens from your IdP.

signingAlgorithm

The algorithm the IdP uses to sign tokens — for example, RS256 or RS384. Check your IdP JWKS or OpenID configuration endpoint.

subClaim

The JWT claim that contains the username. preferred_username is a common value. See your IdP token payload for the correct field.

audClaim

The JWT claim that holds the audience value — typically aud or azp.

audiences

The list of accepted audience values. Operational Insights rejects tokens whose audience does not match.

jwksUri

The URI where Operational Insights fetches the IdP public keys to verify token signatures. Find this in your IdP /.well-known/openid-configuration endpoint.

jwksUriTlsVerifyPeer

Set to true to verify the TLS certificate of the JWKS URI. Recommended for production.

To read the configuration back and confirm it was applied:

curl -sv -X GET http://localhost:8091/settings/jwt \
  -H 'Content-Type: application/json' \
  -u $ADMIN_USERNAME:$ADMIN_PASSWORD

Step 2: Enable Bearer Token Support for SDK Clients (Optional)

To allow Couchbase SDK clients to authenticate using JWT bearer tokens, enable oauthBearerEnabled on the security settings endpoint.

curl -sv -X POST http://localhost:8091/settings/security \
  -u $ADMIN_USERNAME:$ADMIN_PASSWORD \
  -d 'oauthBearerEnabled=true'
This setting is only required for SDK-based use. REST API authentication with JWT bearer tokens works without this setting.

Step 3: Authorize JWT Users in RBAC

For each JWT-authenticated user, create an entry in the external authentication domain and assign their roles.

curl -sv -X PUT http://localhost:8091/settings/rbac/users/external/$USERNAME \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u $ADMIN_USERNAME:$ADMIN_PASSWORD \
  --data-urlencode "name=$DISPLAY_NAME" \
  --data-urlencode "roles=$ROLES"

Replace $USERNAME with the value that appears in the subClaim field of the JWT, and $ROLES with a comma-separated list of Couchbase roles — for example, analytics_access.

Once the user exists in RBAC, clients can authenticate REST API calls by passing the JWT as a bearer token:

curl -sv http://localhost:8091/pools/default \
  -H "Authorization: Bearer $ACCESS_TOKEN"

See Also