> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-documentation/quickstart/authentication-and-authorization/customer-authentication/sso-authentication.md).

# SSO Authentication

Implement SSO solution to authenticate your customers on the storefront.

Emporix supports a Single Sign-On (SSO) mechanism based on the OAuth 2.0 authorization code flow that provides a holistic approach to customer authentication on the storefront.

{% hint style="info" %}
If you do not use an external IDP, the customers' data is stored in the Emporix database.
{% endhint %}

You can use the Emporix solution alone or integrate a chosen Identity Provider (IDP), such as Keycloak, Auth0, or any other OpenID Connect–compliant provider.

### How the SSO flow works

The following steps describe the end-to-end SSO authentication flow in the Emporix implementation.

{% stepper %}
{% step %}

#### Initiation

The storefront (frontend) initiates the SSO flow by redirecting the customer to your configured Identity Provider. The customer authenticates with the IDP using its native login (for example, corporate credentials or social login).
{% endstep %}

{% step %}

#### Callback with authentication code

After successful authentication, the Identity Provider redirects the customer back to a designated Emporix callback endpoint, including a one-time authentication code in the request. This code is short-lived and must not be used directly by the customer.
{% endstep %}

{% step %}

#### Token exchange (backend)

The Emporix Authentication Service receives the callback and exchanges the authentication code with the OpenID Provider for an access token (and optionally a refresh token). This exchange happens server-side.
{% endstep %}

{% step %}

#### Emporix token generation

Emporix then issues the Emporix-specific OAuth token and returns it to the client (application/system). All subsequent API calls are authenticated using this Emporix token, not the IDP token.
{% endstep %}

{% step %}

#### API access

The client uses the Emporix token to call Emporix APIs. Authentication and session management are handled by Emporix based on this token.
{% endstep %}
{% endstepper %}

**SSO flow**

```mermaid
---
config:
  layout: fixed
  theme: base
  themeVariables:
    primaryColor: '#DDE6EE'
    primaryBorderColor: '#4C5359'
    actorBkg: '#DDE6EE'
    actorBorder: '#4C5359'
    actorLineColor: '#4C5359'
    signalColor: '#E86C07'
    signalTextColor: '#7B8B99'
    background: transparent 
---
sequenceDiagram
User->>Frontend: Start SSO login
Frontend->>OpenID Provider: Redirect user (authorization request)
OpenID Provider-->>OpenID Provider: Authenticate user
OpenID Provider-->>Emporix Authentication Service: Redirect back with authorization code
Emporix Authentication Service->>Emporix Customer Service: Forward authorization code
Emporix Customer Service->>OpenID Provider: Exchange code for access token
OpenID Provider->>Emporix Authentication Service: Access token (OIDC)
Emporix Authentication Service-->>Frontend: Emporix-specific OAuth token
Frontend->>API: Call APIs with Emporix token
API-->>Frontend: API response
```

This design keeps Emporix as the sole authority for the authentication-code exchange and token generation in the SSO flow. The Identity Provider is responsible for authenticating the customer. Emporix is responsible for issuing and validating tokens used to access Emporix APIs.

{% hint style="success" %}
See the example flows that incorporate an external Identity Provider into the process:

* [Identity Providers](/api-documentation/integrations/integrations/identity-providers.md)
  * [Auth0](/api-documentation/integrations/integrations/identity-providers/auth0.md)
  * [Keycloak](/api-documentation/integrations/integrations/identity-providers/keycloak.md)
    {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/api-documentation/quickstart/authentication-and-authorization/customer-authentication/sso-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.