--- title: Okta description: >- Configure Okta as a third-party identity provider for Shopify customer accounts and set up custom claims for customer data enrichment. api_name: customer-authentication 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, and set the correct authentication method. ### 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. *** ## Standard claims Okta may issue "skinny" ID tokens that omit standard profile claims like `given_name`, `family_name`, and `email_verified`. When you select **Okta** as the provider type in the Shopify admin, Shopify automatically makes an additional userinfo call to retrieve these claims. No extra scope or claim configuration is needed for standard profile data to be imported. *** ## 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 | | Standard claims (name, phone) not imported | Provider type not set to Okta in Shopify | Select **Okta** as the provider type in the Shopify admin so Shopify makes the additional userinfo call to retrieve standard claims from skinny ID tokens | | 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/) * [Shopify: Claim import reference](https://shopify.dev/docs/api/customer-authentication/claim-import) ***