# Third-party identity providers

Although commercetools provides robust native Customer authentication, you might need to integrate a third-party IDP to support features such as social logins, single sign-on (SSO), and multi-factor authentication (MFA).

## What is an identity provider?

An identity provider (IDP) is an external service that manages user identities and handles the authentication process. The IDP stores and verifies passwords, instead of your application doing so. This approach is useful when you want to offer the sign in with Google feature, integrate with an existing employee directory, or leverage advanced security features that commercetools doesn't provide natively.

Here are a few commonly used third-party IDPs:

- Auth0
- Okta
- Azure AD B2C
- Firebase Authentication
- Social login providers such as Google, Facebook, and Apple.

## How IDPs work with commercetools

When integrating an IDP, your application's backend orchestrates two separate authorization flows that typically use OAuth 2.0 or OpenID Connect (OIDC) protocols. It's crucial to understand the distinct roles and participants in each flow.

### Flow 1: user authentication

This flow handles the user's sign-in or sign-up process.

- **Participants**: the user's browser (frontend), your backend for frontend (BFF), and the third-party IDP
- **Process**: the user authenticates via the IDP. The IDP issues a token (for example, a JWT) to the frontend, which is then passed to your BFF. The BFF validates this token to confirm the user's identity.
- **Roles**:
  - **IDP**: the authentication server
  - **BFF**: the resource server that protects its own endpoints and trusts the IDP.
  - **commercetools' role**: commercetools is not involved in this flow.

### Flow 2: service-to-service API access

This flow allows your backend to securely communicate with the Composable Commerce API.

- **Participants**: your BFF and the Composable Commerce API
- **Process**: the BFF uses its own confidential client credentials to obtain an access token from the commercetools authorization server. It then uses this token to make authenticated API calls to manage resources, such as Customers, Carts, and Orders.
- **Roles**:
  - **BFF**: the client
  - **commercetools**: the authorization server and resource server

These two flows are independent. Your BFF acts as a bridge, first verifying a user's identity with the IDP (Flow 1) and then using its own separate credentials to interact with commercetools on that user's behalf (Flow 2).

**A crucial point on implementation:** it's important to understand that these two flows are independent and not sequential. Flow 2 (service-to-service API access) does not happen as a direct result of Flow 1 (user authentication).

In a typical implementation, your BFF establishes its connection with commercetools (Flow 2) at application startup. It obtains a long-lived service token that it caches and reuses for all subsequent API calls.

Therefore, when a user initiates the sign-in process (Flow 1), the BFF already has a valid token to communicate with commercetools. No new service-to-service authentication is needed at that moment.

### High-level authentication flow

```mermaid
sequenceDiagram
  participant C as Customer (Alice)
  participant ZE_UI as Zen Electron UI (Frontend)
  participant ZE_BFF as Zen Electron BFF (Backend for Frontend)
  participant IDP as Identity Provider (e.g., Auth0)
  participant CT_API as Composable Commerce API

  C->>ZE_UI: 1. Clicks "Sign in/Sign up"
  ZE_UI->>IDP: 2. Redirects to IDP for authentication
  activate IDP
  IDP->>C: 3. Displays sign-in page / handles social login
  C->>IDP: 4. Enters credentials / authenticates
  IDP-->>ZE_UI: 5. Redirects back with token (e.g., JWT)
  deactivate IDP
  ZE_UI->>ZE_BFF: 6. Sends token to BFF
  ZE_BFF->>IDP: 7. (Optional) Introspects/validates token
  activate IDP
  IDP-->>ZE_BFF: 8. (Optional) Token validation result
  deactivate IDP
  ZE_BFF->>CT_API: 9. (If new) Query Customer by externalId or create Customer
  activate CT_API
  CT_API-->>ZE_BFF: 10. Returns customer record
  deactivate CT_API
  ZE_BFF-->>ZE_UI: 11. Establishes session for customer (containing customerId)
  ZE_UI-->>C: 12. Sign-in successful
```

Here's a breakdown of the steps:

1. **The IDP handles user authentication**: the IDP manages the username and password logic, social logins, and advanced features such as MFA.
2. **The IDP issues tokens upon successful authentication**: these are often JSON web tokens (JWTs) that contain information about the authenticated user.
3. **Your application backend validates the token**: your backend receives the token and either validates it locally or makes an introspection call to the IDP to verify its authenticity.
4. **You link the external identity to a commercetools Customer**:
   - If a Customer record doesn't exist for the user, then your backend creates a new Customer in commercetools.
   - You store the IDP's user ID in the `externalId` field of the commercetools Customer. This `externalId` links the IDP user to the commercetools Customer.
   - If the Customer already exists, then your backend retrieves their record by using the `externalId` field.
5. **commercetools manages all e-commerce data**: the IDP is used only for authentication. All Customer-specific data such as addresses, Carts, and Orders reside within commercetools, linked by the `customerId` and `externalId` fields.

### Role of backend for frontend (BFF)

The Composable Commerce API doesn't directly introspect external IDP tokens. Your backend for frontend (BFF) must perform this validation before it can use the IDP-authenticated identity to interact with commercetools.

```mermaid
sequenceDiagram
  participant ZE_UI as Zen Electron UI (Frontend)
  participant ZE_BFF as Zen Electron BFF (Backend for Frontend)
  participant IDP as Identity Provider
  participant CT_API as Composable Commerce API

  ZE_UI->>ZE_BFF: 1. User authenticated by IDP, sends IDP token
  ZE_BFF->>IDP: 2. Introspection request (e.g., token, client_id, client_secret)
  activate IDP
  IDP-->>ZE_BFF: 3. Introspection response (e.g., { "active": true, "sub": "idp_user_id", ... })
  deactivate IDP
  alt If user not found in CT
	  ZE_BFF->>CT_API: 4. POST /{projectKey}/customers (create new CT Customer with externalId: "idp_user_id")
	  activate CT_API
	  CT_API-->>ZE_BFF: 5. Returns new CT Customer (customerId)
	  deactivate CT_API
  else If user found in CT
	  ZE_BFF->>CT_API: 4. GET /{projectKey}/customers?where=externalId="idp_user_id"
	  activate CT_API
	  CT_API-->>ZE_BFF: 5. Returns existing CT Customer (customerId)
	  deactivate CT_API
  end
  ZE_BFF->>ZE_UI: 6. Establishes Zen Electron session (linked to customerId)
```

## When to use an IDP

You should consider using an IDP in the following scenarios:

- **Single sign-on (SSO)**: if users need to access multiple applications with a single login, then an IDP simplifies this by allowing them to use existing credentials.
- **Existing user base**: if you've a large Customer base in an external system (such as a legacy platform or CRM), then an IDP can help migrate and manage these users without forcing them to re-register.
- **Advanced authentication features**: for features such as MFA, password-less login, and social logins, IDPs offer out-of-the-box solutions that save significant development effort.
- **Compliance and security**: IDPs specialize in security and compliance; for example, GDPR and CCPA. Offloading these concerns to a dedicated provider can reduce risk.

Although integrating an external IDP can provide advanced authentication capabilities to your applications, this learning module focuses on the native customer authentication features of commercetools. IDP integration is an advanced architectural decision that builds on a solid understanding of how commercetools manages Customer data.

## Key takeaways

- Third-party IDPs manage user authentication, letting you support features such as SSO, MFA, and social logins.
- Your application's backend is responsible for validating the IDP token and linking the external user identity to a commercetools Customer by using the `externalId` field.
- From the frontend’s perspective, your BFF acts as the resource server, whereas the IDP acts as the authentication authority.
- commercetools acts both as an authorization server and a resource server for the backend, managing commerce data (Carts, Orders, profiles) in a different flow.
- Consider using an IDP if you need to integrate with existing user systems, require advanced security features, or want to simplify compliance.

## Related pages

- [Area overview page with navigation](/learning-implement-carts-and-shopping-lists.md)
- [Previous page: Cart merge strategies](/learning-implement-carts-and-shopping-lists/manage-signups-and-signins/cart-merge-strategies.md)
- [Next page: Best practices](/learning-implement-carts-and-shopping-lists/manage-signups-and-signins/best-practices.md)
- [Search documentation and API specs](/search.md)