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 JSON Web Token (JWT), and connect your application to Optimizely Graph.
Prerequisites
- A separate key to configure the OIDC endpoints. Contact Optimizely Support to request it.
Understand 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 OIDC provider with Optimizely Graph, register the provider with a valid issuer and audience so the system can validate the tokens.
- 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 the Upsert OIDC configUpsert OIDC config API reference for information.
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.
- Prepare the JWT payload – Ensure your JWT payload includes issuer, audience, roles, and preferred_username claims.
{
"sub": "1234567890",
"name": "John Doe",
"iat": 1516239022,
"iss": "{your_issuer}",
"audience": "{your_audience}",
"roles": ["Everyone"],
"preferred_username": "[email protected]"
}- Send GraphQL 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.
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
Create an Okta application and access policy so Okta issues tokens that Optimizely Graph can validate.
- Follow Okta's documentation to Create an OIDC SPA App in Okta Admin Console.
- Go to Security > API to modify the default authorization server.
- On the Access policies tab, click Add policy and add a policy. See Okta's Create access policies documentation.
- Click Add rule and add a default rule to the policy. See Create rules for each access policy.
Preview the JWT
Preview the token Okta issues so you can confirm the default claims are present before customizing the payload.
- On the Token preview tab, enter the required information.
- 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
Add a roles claim to the Okta token so Optimizely Graph can authorize requests against group membership.
- On the Claims tab, click Add claim.
- Enter roles for the Name.
- Select Groups for the Value type drop-down list.
- Select Matches regex for the Filter drop-down list.
- Enter .* for Matches regex.
- Click Create.
Add the preferred_username claim
Add a preferred_username claim to the Okta token so Optimizely Graph receives the user identifier it expects.
- On the Claims tab, click Add claim.
- Enter preferred_username for the Name.
- Enter user.email for the Value.
- Click Create.
📘 Note See Customize tokens returned from Okta with custom claims for information.
Register Okta with Optimizely Graph
Register the Okta application with Optimizely Graph so Graph accepts tokens issued by Okta and applies the configured claims.
- On the Token preview, enter the required information.
- Click Preview token to check the decoded JWT. You should see the default claims (including the added roles and preferred_username) in the token.
- Copy the JWT.
- Follow the previous steps to register your Okta app as an OIDC provider in Optimizely Graphregister your Okta app as an OIDC provider in Optimizely Graph. Then, provide the issuer (authority) and audience from the Okta app.
- Send a PUT request to the Upsert OIDC configUpsert OIDC config REST API endpoint. Use the information found in the JWT.
📘 Note You must use Basic or HMAC authorization with the Upsert OIDC configUpsert OIDC config REST API endpoint.