---
title: Okta
description: >-
  Configure Okta as a third-party identity provider for Shopify customer
  accounts and set up custom claims for customer data enrichment.
source_url:
  html: 'https://shopify.dev/docs/api/customer-authentication/provider-guides/okta'
  md: 'https://shopify.dev/docs/api/customer-authentication/provider-guides/okta.md'
---

# Okta

This guide covers how to configure [Okta](https://www.okta.com/) as a third-party identity provider for Shopify customer accounts, including how to add custom Shopify claims to your ID tokens for [customer data enrichment](https://shopify.dev/docs/api/customer-authentication/claim-import).

***

## Prerequisites

* A [Shopify Plus](https://www.shopify.com/plus) plan with [new customer accounts](https://help.shopify.com/en/manual/customers/customer-accounts/new-customer-accounts) enabled.
* An Okta org with an [OIDC Web Application](https://developer.okta.com/docs/guides/sign-into-web-app-redirect/main/) configured.
* A [Custom Authorization Server](https://developer.okta.com/docs/guides/customize-authz-server/-/main/) (required for custom claims; the default Org Authorization Server doesn't support them).

***

## Connect Okta to Shopify

To connect Okta as your store's identity provider, you'll add your Okta credentials to the Shopify admin, configure your Okta application to accept Shopify's callback URL, set the correct authentication method, and enable refresh tokens.

### Step 1: Add your Okta credentials in the Shopify admin

Add your Discovery URL, Client ID, and Client Secret in the Shopify admin under **Settings** > **Customer accounts** > **Third-party identity provider**.

You can find these values in your Okta admin dashboard:

* **Discovery URL:** `https://{your-okta-domain}/.well-known/openid-configuration` (or your Custom Authorization Server's discovery URL).
* **Client ID:** Found in your application's **General** tab.
* **Client Secret:** Found in your application's **General** tab.

For full setup instructions, refer to [Connect a third-party identity provider](https://help.shopify.com/en/manual/customers/customer-accounts/new-customer-accounts/identity-provider/connect).

### Step 2: Add your Shopify callback URL to Okta

To complete the connection, add your Shopify callback URL to the **Sign-in redirect URIs** field in your Okta application settings. This lets Okta redirect customers back to your store after they authenticate.

You can find your Shopify callback URL in the Shopify admin on the same **Third-party identity provider** settings page from Step 1.

### Step 3: Set the authentication method to client\_​secret\_​post

In your Okta application's **General** tab, under **Client Credentials**, select **Client secret** with `client_secret_post` as the token endpoint authentication method. Okta defaults to `client_secret_basic`, which isn't supported for this flow.

**Important:**

If you skip this step, the token exchange fails during login. Okta must use `client_secret_post` for Shopify's identity provider integration.

### Step 4: Enable refresh tokens

In the Shopify admin identity provider settings, add `offline_access` to the **Additional scopes** field. Without this scope, Okta doesn't issue a refresh token, so customer sessions can't be refreshed and expire prematurely.

Also enable the **Refresh Token** grant type on your Okta application, under **General settings > Grant type**. Okta issues a refresh token only when both the `offline_access` scope is requested and the Refresh Token grant type is enabled.

***

## Standard claims

To import a customer's name, phone number, or address, add the [required scope](https://shopify.dev/docs/api/customer-authentication/claim-import#request-the-required-scopes) for each claim to the **Additional scopes** field in the Shopify admin identity provider settings. Shopify requests only `openid` and `email` by default. For example, to request a refresh token and all three claims, set **Additional scopes** to `profile phone address offline_access`.

Okta might issue "skinny" ID tokens that omit these claims. You don't need to configure anything special for this: after you request the scope, Shopify imports the claim whether Okta returns it in the ID token or from its `/userinfo` endpoint. For details, refer to [Userinfo backfill for skinny ID tokens](https://shopify.dev/docs/api/customer-authentication/claim-import#userinfo-backfill-for-skinny-id-tokens).

***

## Add custom Shopify claims

To import tags and addresses, add custom claims to the ID token. The recommended approach is app-level claims.

### App-level claims (recommended)

You can add custom claims directly to your Okta application so they're included in every ID token it issues:

1. In the Okta admin, go to **Applications > your application > Sign On**.
2. In the **Token claims (OIDC)** section, click **Add expression**.
3. Add the Shopify custom claims:

| Name | Expression | Include in |
| - | - | - |
| `urn:shopify:customer:tags` | Source attribute or expression | ID Token — Always |
| `urn:shopify:customer:addresses` | Source attribute or expression | ID Token — Always |

The tags claim value must be a comma-separated string (for example, `"vip, loyalty-gold"`). The addresses claim value must be a JSON array matching the [Shopify address format](https://shopify.dev/docs/api/customer-authentication/claim-import#addresses).

### Authorization Server claims (alternative)

If you prefer server-level claims that apply across applications:

1. Go to **Security > API > Authorization Servers** and select your Custom Authorization Server.
2. On the **Claims** tab, click **Add Claim**.
3. Set **Include in token type** to **ID Token**.
4. Enter the claim name (for example, `urn:shopify:customer:tags`) and the value expression.

For more details, refer to [OAuth 2.0 and OpenID Connect claims](https://developer.okta.com/docs/concepts/oauth-claims/).

***

## Enable enrichment in Shopify

After configuring your identity provider to include custom claims, you need to tell Shopify to read and import them.

In the Shopify admin under your identity provider settings, enable **Sync customer data** and configure the update trigger and overwrite rules. For details on these options, refer to [claim import configuration](https://shopify.dev/docs/api/customer-authentication/claim-import#configuration).

***

## Verify

After enabling enrichment, verify that your claims are included in the ID token and that Shopify imports them correctly:

1. Use Okta's **Token Preview** (under **Security > API > Authorization Servers > your server > Token Preview**) to validate that your custom claims appear in the ID token before testing on Shopify.
2. Authenticate on your store through Okta.
3. In the Shopify admin, go to **Customers** and open the customer record to confirm the imported data.

***

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Token exchange fails during login | Authentication method set to `client_secret_basic` | Change to `client_secret_post` in your Okta application's General tab under Client Credentials |
| Session expires and customer can't refresh | Missing `offline_access` scope, or Refresh Token grant type not enabled | Add `offline_access` to **Additional scopes** in the Shopify admin, and enable the Refresh Token grant type on your Okta application |
| Name, phone, or address not imported | Required scope not requested, enrichment disabled, or the value is already set in the signed ID token | Confirm the claim's [scope](https://shopify.dev/docs/api/customer-authentication/claim-import#request-the-required-scopes) is in **Additional scopes**; that **Sync customer data** is enabled; that your Okta discovery document exposes a `userinfo_endpoint`; and that the claim isn't already populated in the signed ID token (only blank or absent claims are backfilled from `/userinfo`; a populated signed value is never overwritten). |
| Custom claims not appearing | Using the Org Authorization Server | Custom claims require a Custom Authorization Server. Create one under Security > API > Authorization Servers |
| Claim expression returns null | Invalid Okta Expression Language syntax | Test the expression in Token Preview before deploying |

***

## Resources

* [Okta: Customize tokens returned from Okta](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/)
* [Okta: Create an authorization server](https://developer.okta.com/docs/guides/customize-authz-server/-/main/)
* [Okta: OAuth 2.0 and OpenID Connect claims](https://developer.okta.com/docs/concepts/oauth-claims/)
* [Okta: Sign users in to your web app](https://developer.okta.com/docs/guides/sign-into-web-app-redirect/main/)
* [Okta: Refresh tokens](https://developer.okta.com/docs/guides/refresh-tokens/main/)
* [Shopify: Claim import reference](https://shopify.dev/docs/api/customer-authentication/claim-import)

***