# 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](/learning-implement-carts-and-shopping-lists/manage-signups-and-signins/third-party-identity-providers.md#what-is-an-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](/commerce-integration-layer/hosts-and-authorization.md#idpsessionrequest).

## Sign-in workflow

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.

```mermaid title="Identity provider sign-in flow"
sequenceDiagram
	participant S as Shopper
	participant SF as Storefront
	participant IL as Commerce Integration Layer
	participant IDP as Identity provider
	participant CT as commercetools

	S->>SF: Start sign-in
	SF->>IDP: Authenticate (authorization endpoint)
	IDP-->>SF: Authorization code or ID token
	SF->>IL: POST /session (grant_type: idp)
	IL->>IDP: Exchange code for tokens, if a code was sent
	IL->>IL: Verify the ID token against the identity provider's JWKS
	IL->>CT: Create or update the matching Customer
	CT-->>IL: Customer
	IL-->>SF: Session token
```

1. 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.
2. The identity provider redirects back with an authorization code or an ID token.
3. The storefront sends that result to `POST /session` with `grant_type: "idp"`, as described in [IdpSessionRequest](/commerce-integration-layer/hosts-and-authorization.md#idpsessionrequest).
4. If the storefront sent a code, the Commerce Integration Layer exchanges it at the identity provider's token endpoint to get an ID token.
5. The Commerce Integration Layer verifies the ID token's signature against the identity provider's JWKS and checks its issuer and audience.
6. The Commerce Integration Layer maps the verified token claims to Customer fields using the Project's [claim mapping](/commerce-integration-layer/development/identity-providers.md#claim-mapping), then creates or updates the matching commercetools Customer. A Customer created this way has `authenticationMode` set to `ExternalAuth` (see [AuthenticationMode](/search.md?urn=ctp:api:type:AuthenticationMode)), so it has no commercetools password.
7. The Commerce Integration Layer returns a session token, exactly as it does for any other [session grant](/commerce-integration-layer/hosts-and-authorization.md#sessiongranttype).

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](/commerce-integration-layer/hosts-and-authorization.md#sessiongranttype) 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](/commerce-integration-layer/development/extension-authentication.md).

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](/commerce-integration-layer/development/monitoring-and-alerting.md#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](/commerce-integration-layer/development/identity-providers.md#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 **IdP Login** tab in the Commerce Integration Layer configuration panel.

See the [identity provider errors](/commerce-integration-layer/development/monitoring-and-alerting.md#identity-provider-errors) for IdP-related signals and recommended alerts.

## Configure an identity provider

You configure a Project's identity provider from the **IdP Login** tab of the Commerce Integration Layer configuration panel in 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. |

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.

## Related pages

- [Area overview page with navigation](/commerce-integration-layer.md)
- [Previous page: Checkout](/commerce-integration-layer/development/checkout-integration.md)
- [Next page: Extension authentication](/commerce-integration-layer/development/extension-authentication.md)
- [Search documentation and API specs](/search.md)