Identity providers

Let shoppers sign in through an external OpenID Connect identity provider.

The Commerce Integration Layer can authenticate shoppers through an external OpenID Connect (OIDC) identity provider instead of, or alongside, native commercetools Customer sign-in. This lets shoppers sign in with credentials they already have, such as an enterprise workforce identity or a platform-managed account, without your storefront or the Commerce Integration Layer ever handling their password.

A Project has at most one identity provider configured at a time. Once configured, shoppers sign in through the idp session grant.

Sign-in has two parts: the shopper authenticates directly with the identity provider, then your storefront exchanges the result for a Commerce Integration Layer session.

The storefront sends the shopper to the identity provider's authorization endpoint. This step happens entirely between the storefront and the identity provider; the Commerce Integration Layer isn't involved yet.
The identity provider redirects back with an authorization code or an ID token.
The storefront sends that result to POST /session with grant_type: "idp", as described in IdpSessionRequest.
If the storefront sent a code, the Commerce Integration Layer exchanges it at the identity provider's token endpoint to get an ID token.
The Commerce Integration Layer verifies the ID token's signature against the identity provider's JWKS and checks its issuer and audience.
The Commerce Integration Layer maps the verified token claims to Customer fields using the Project's claim mapping, then creates or updates the matching commercetools Customer. A Customer created this way has authenticationMode set to ExternalAuth (see AuthenticationMode), so it has no commercetools password.
The Commerce Integration Layer returns a session token, exactly as it does for any other session grant.

The Commerce Integration Layer doesn't introspect the identity provider's token on every GraphQL request. Instead, it checks back with the identity provider only when it needs to: at sign-in, when the session is refreshed with the refresh grant, and at sign-out. Refreshing a session whose identity provider account was deactivated fails at that point, rather than immediately.

Signing out with DELETE /session also revokes the underlying token at the identity provider's revocation endpoint, on a best-effort basis.

IdP Failures and Latency

The Commerce Integration Layer uses three session types, determined by the grant used to sign in:

IdP-anchored sessions: created with the idp grant, which signs a shopper in through your identity provider. The Commerce Integration Layer calls your IdP only during sign-in (code exchange), token refresh, and sign-out (revocation), never on routine API requests. IdP slowness or outages therefore affect sign-in and refresh, not requests made with a valid session. If refreshing fails, the shopper is signed out once the session token expires.
commercetools-anchored sessions: created with the anonymous, password, or register grants. These requests don't call an external identity provider.
Extension-anchored sessions: created with the extension grant. Your extension can return an opaque anchorToken, which is sealed into the session and passed back to its revalidation hook. The Commerce Integration Layer does not introspect that value; liveness and refresh are delegated to your extension's hooks. See Extension authentication.

Because the Commerce Integration Layer does not alert on external IdP errors or latency automatically, you must set up your own monitoring.

Signals to Monitor

IdP call log line: see the identity provider errors. Each call to your IdP writes a line with upstream: "idp" and the IdP's HTTP status; check it when investigating a sign-in, refresh, or sign-out issue.

Use the upstream field ("idp" vs "commercetools") to tell which service a call went to. It doesn't tell you the cause of a failure. For example, an IdP that rejects a call because of incorrect credentials in your configuration still logs upstream: "idp". Use the status code and the common causes below to find the cause.

Common Causes

Incorrect IdP credentials or endpoints (client ID, secret, or URL).
A claim mapping referencing a claim missing from the IdP token.
Delayed propagation of rotated JWKS keys.
Rate limiting by your IdP.
Elevated response times from a slow IdP.

To verify your settings, check the identity provider configuration in the Merchant Center.

See the identity provider errors for IdP-related signals and recommended alerts.

Configure an identity provider

You configure a Project's identity provider in the Merchant Center.

Field	Description
Issuer	The identity provider's issuer URL.
Authorization endpoint	The URL the storefront redirects shoppers to for authentication. Optional if your storefront starts the authorization step itself.
Token endpoint	The identity provider's endpoint for exchanging an authorization code for tokens.
Revocation endpoint	The identity provider's endpoint for revoking a token on sign-out.
JWKS URI	The identity provider's JSON Web Key Set endpoint, used to verify ID token signatures.
Client ID	The client ID the Commerce Integration Layer uses when it talks to the identity provider.
Client secret	The client secret the Commerce Integration Layer uses when it talks to the identity provider. The client secret is stored securely and never shown again after you save it.
Redirect URI	The URI the identity provider redirects back to after authentication.

Alternatively, use the commercetools integration-layer idp-login commands in the commercetools CLI. They set the same fields as the IdP Login tab.

The first set must include the issuer, token endpoint, revocation endpoint, JWKS URI, client ID, redirect URI, and client secret. Pass the client secret in the IDP_CLIENT_SECRET environment variable instead of the --client-secret flag, so it stays out of the process list and your shell history.

read -r -s -p 'IdP client secret: ' IDP_CLIENT_SECRET
printf '\n'
IDP_CLIENT_SECRET="$IDP_CLIENT_SECRET" \
commercetools integration-layer idp-login set \
  --issuer https://idp.example.com \
  --authorization-endpoint https://idp.example.com/authorize \
  --token-endpoint https://idp.example.com/token \
  --revocation-endpoint https://idp.example.com/revoke \
  --jwks-uri https://idp.example.com/jwks \
  --client-id <your-client-id> \
  --redirect-uri https://shop.example.com/callback

The token endpoint, revocation endpoint, and JWKS URI must be absolute http or https URLs without embedded credentials. The --authorization-endpoint flag is optional.

After the first set, the command changes only the flags you pass. If you leave out the client secret, the stored one is kept. For example, to override a claim and match Customers by email:

commercetools integration-layer idp-login set \
  --claim-external-id user_id \
  --match-strategy email

To review or remove the configuration:

commercetools integration-layer idp-login get
commercetools integration-layer idp-login delete

The get command doesn't show the client secret; it only reports whether one is set. The delete command asks for confirmation. Pass --force to skip the prompt, which is required in non-interactive environments such as CI.

Removing the configuration disables idp sign-in for the Project until it's configured again.

Claim mapping

Claim mapping tells the Commerce Integration Layer which ID token claim to read for each Customer field. The defaults follow standard OIDC claim names.

Customer field	Default claim
External ID	`sub`
Email	`email`
First name	`given_name`
Last name	`family_name`
Phone	`phone_number`

Override a claim name if your identity provider uses a different one, for example a custom claim for the external ID.

Customer matching

The external ID claim is required and is used by default to find or create the matching commercetools Customer, stored in the Customer's externalId field. Set the match strategy to email instead if your identity provider doesn't issue a stable external ID but does issue a stable, verified email address.

Sign-in workflow.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

IdP Failures and Latency.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Signals to Monitor.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Common Causes.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Configure an identity provider.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Claim mapping.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Customer matching.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}