Generic OIDC provider

Use OpenID Connect (OIDC) authentication with Optimizely Graph to secure access to your content APIs. By integrating with Opti ID or another OIDC-compliant identity provider, you can enforce role-based access, support single sign-on (SSO), and protect sensitive data across services and environments. This guide shows how to configure OIDC authentication, prepare your JWT, and connect your application to Optimizely Graph.

Prerequisites

• An OpenID Connect compliant identity provider, for example, Okta, Keycloak, or Entra ID.
• A separate key to configure the OpenID Connect (OIDC) endpoints. Contact Optimizely Support to request it.

Understand JSON Web Token (JWT) requirements

The JWT must include specific claims such as roles and preferred_username for proper authentication and authorization.

Required JWT claims

Your JWT payload must include the following claims:

• iss – Token issuer (OIDC authority URL)
• aud – Audience configured for Optimizely Graph
• roles – User roles used for authorization
• preferred_username – User identifier

Example JWT

{
  "ver": 1,
  "jti": "NEjTGbsWFYlRSsCebzkOnYL8dg4vxMTa00oFnJHrYvU",
  "iss": "https://youridentityprovider.com/oauth2",
  "aud": "your_graph",
  "iat": 1734541108,
  "exp": 1734544708,
  "cid": "0oalyh8sx9IofUzDA5d7",
  "uid": "00yly5t8nrCK5D5hU5d7",
  "scp": [
    "openid"
  ],
  "auth_time": 1000,
  "sub": "[email protected]",
  "roles": [
    "Everyone"
  ],
  "preferred_username": "[email protected]"
} 

Configure OIDC authentication in Optimizely Graph

To integrate an OpenID Connect (OIDC) provider with Optimizely Graph, the provider must be registered with a valid issuer and audience so the tokens can be validated.

1. Configure OIDC endpoints – Send a PUT request to the OIDC REST API endpoint, <https://cg.optimizely.com/api/config/oidc> with a Basic or HMAC authorization header. See Upsert OIDC config API reference for information.

   sh

   curl -XPUT \
     -H 'Authorization: Basic base64({appKey}:{secret})' \
     -d '{
       "issuer": "{your_issuer}",
       "audience": "{your_audience}",
     }' https://cg.optimizely.com/api/config/oidc 

   The issuer is the authority of your identity provider and must be a valid URL, for example, https://youridentityprovider.com/oauth2.

2. JWT payload requirements – Ensure your JWT payload includes issuer, audience, roles, and preferred_username claims.

   Payload

   {
     "sub": "1234567890",
     "name": "John Doe",
     "iat": 1516239022,
     "iss": "{your_issuer}",
     "audience": "{your_audience}",
     "roles": ["Everyone"],
     "preferred_username": "[email protected]"
   }

3. Send GQL query – Send your GraphQL query to the query endpoint with your JWT. See Get started with the GraphQL API for information on the GraphQL query endpoint.

   sh

   curl -XPOST  
     -H 'Authorization: Bearer {jwt_token}'  
     -d '{query}'  
     https://cg.optimizely.com/content/v2?tenant_id={your_tenant_id}

   📘

   Note

   The tenant_id must be passed as a query string. Contact Optimizely Support to request it.

Example configuration with Okta

The following steps configure Okta as an OIDC provider with Optimizely Graph.

Create an Okta OIDC application

1. Follow Okta's documentation to Create an OIDC SPA App in Okta Admin Console.
2. Go to Security > API to modify the default authorization server.
3. On the Access policies tab, click Add policy. Add a policy. See Okta's Create access policies documentation.
4. Click Add rule. Add a default rule to the policy. See Create rules for each access policy.

Preview the JWT

1. On the Token preview tab, enter the required information.
2. Click Preview token to check the decoded JWT. You should see the default claims (except roles and preferred_username) in the token.

Add the roles claim

1. On the Claims tab, click Add claim.
2. Enter roles for the Name.
3. Select Groups for the Value type drop-down list.
4. Select Matches regex for the Filter drop-down list.
5. Enter .* for Matches regex.
6. Click Create.

Add the preferred_username claim

1. On the Claims tab, click Add claim.
2. Enter preferred_username for the Name.
3. Enter user.email for theValue.
4. Click Create.

📘

Note

See Customize tokens returned from Okta with custom claims for more information.

Register Okta with Optimizely Graph

1. On the Token preview, enter the required information.
2. Click Preview token to check the decoded JWT. You should see the default claims (including the newly added roles and preferred_username) in the token.
3. Copy the JWT.
4. Follow the previous steps to register your Okta app as an OIDC provider in Optimizely Graph. Then, provide the issuer (authority) and audience from the Okta app.
5. Send a PUT request to the Upsert OIDC config REST API endpoint. Use the information found in the JWT.

📘

Note

You must use Basic or HMAC authorization with the Upsert OIDC config REST API endpoint.