---
title: Generic OIDC provider
slug: graph/docs/generic-oidc-provider
docTags: 
createdAt: 2026-07-30T20:30:20.147Z
---

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

- An OpenID Connect compliant identity provider, for example, [Okta](https://www.okta.com), [Keycloak](https://www.keycloak.org), or [Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id).
- A separate key to configure the OIDC endpoints. Contact [Optimizely Support](https://support.optimizely.com/hc/en-us/requests/new) 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

```json
{
  "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": "user@company.com",
  "roles": [
    "Everyone"
  ],
  "preferred_username": "user@company.com"
} 
```

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

1. **Configure OIDC endpoints** – Send a `PUT` request to the OIDC REST API endpoint, `https://cg.optimizely.com/api/config/oidc`, with a [Basic](docId\:EwCMYfUVvlDXDaBvo6SAq) or [HMAC](docId\:VD--Nh6ILi9_9YoB1_Ux3) authorization header. See the [Upsert OIDC config](docId\:OS9StLD5GccO3vLVpMzPv) API reference for information.

```shell
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. **Prepare the JWT payload** – Ensure your JWT payload includes `issuer`, `audience`, `roles`, and `preferred_username` claims.

```json
{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "iss": "{your_issuer}",
  "audience": "{your_audience}",
  "roles": ["Everyone"],
  "preferred_username": "john.doe@example.com"
}
```

3. **Send GraphQL query** – Send your GraphQL query to the query endpoint with your JWT. See [Get started with the GraphQL API](docId\:BAQ8iOmLWQlntKNNvkQ0F) for information on the GraphQL query endpoint.

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

:::hint{type="info"}
**Note**
The `tenant_id` must be passed as a query string. Contact [Optimizely Support](https://support.optimizely.com/hc/en-us/requests/new) 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.

1. Follow Okta's documentation to [Create an OIDC SPA App in Okta Admin Console](https://support.okta.com/help/s/article/create-an-oidc-spa-app-in-okta-admin-console?language=en_US).
2. Go to **Security > API** to modify the default authorization server.
3. On the **Access policies** tab, click **Add policy** and add a policy. See Okta's [Create access policies](https://help.okta.com/en-us/content/topics/security/api-config-access-policies.htm) documentation.
4. Click **Add rule** and add a default rule to the policy. See [Create rules for each access policy](https://help.okta.com/en-us/content/topics/security/api-config-access-policies.htm).

### Preview the JWT

Preview the token Okta issues so you can confirm the default claims are present before customizing the payload.

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

Add a `roles` claim to the Okta token so Optimizely Graph can authorize requests against group membership.

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

Add a `preferred_username` claim to the Okta token so Optimizely Graph receives the user identifier it expects.

1. On the **Claims** tab, click **Add claim**.
2. Enter *preferred\_username* for the **Name**.
3. Enter *user.email* for the **Value**.
4. Click **Create**.

:::hint{type="info"}
**Note**
See [Customize tokens returned from Okta with custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/) 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.

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 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](docId\:sNcLLcLYgWv_QVb0Mtqus). Then, provide the issuer (authority) and audience from the Okta app.
5. Send a `PUT` request to the [Upsert OIDC config](docId\:OS9StLD5GccO3vLVpMzPv) REST API endpoint. Use the information found in the JWT.

:::hint{type="info"}
**Note**
You must use [Basic](docId\:EwCMYfUVvlDXDaBvo6SAq) or [HMAC](docId\:VD--Nh6ILi9_9YoB1_Ux3) authorization with the [Upsert OIDC config](docId\:OS9StLD5GccO3vLVpMzPv) REST API endpoint.
:::