Generic OIDC provider

Prerequisites

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

Authorization flow

The following diagram shows the configuration of an OIDC provider in Optimizely:

JSON web token (JWT)

The JSON web token (JWT) must include specific claims such as roles and preferred_username for proper authentication and authorization.

The following is an example of JWT. It establishes a secure connection between your application and Optimizely. It ensures that only authenticated users can access specific resources and perform actions based on their assigned roles and permissions.

{
  "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]"
} 

Configuration steps

To integrate an 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.

Configure the example

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.

Create 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.

Create 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 the OIDC configuration

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 (including the newly added roles and preferred_username) in the token.
3. Copy the JWT for later use.
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.