> For the complete documentation index, see [llms.txt](https://docs.reachplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reachplatform.com/technical/bolt-on-setup/sso-end-customers.md).

# SSO — End Customers

Configure SAML 2.0 SSO for end-customer login on Reach experiences.

Set up SAML-based SSO so customers sign in with your IdP.

### Overview

Customer SSO lets end customers access Reach-powered experiences using brand-managed credentials. Reach supports **SAML 2.0** and integrates with your Identity Provider (IdP).

Reach never stores passwords. Authentication always happens on your systems.

{% hint style="info" %}
This page covers **end-customer SSO** only. For agent SSO into Reach Central, use [SSO — Agents](/technical/bolt-on-setup/sso-agents.md).
{% endhint %}

### Why brands enable customer SSO

* Remove duplicate customer credentials.
* Reduce login friction and password resets.
* Keep MFA and security policy in your IdP.
* Ensure a consistent identity across brand and Reach experiences.

### Where it’s used

Customer SSO can be enabled for Reach-powered self-care and checkout experiences, including:

* Reach-managed brand websites
* Reach-managed mobile web
* Reach-managed mobile apps

### How authentication works (SP-initiated SAML 2.0)

Reach uses a **Service Provider (SP)-initiated** SAML flow.

{% stepper %}
{% step %}

#### Customer initiates login

Customer clicks **Log in** from a Reach-powered experience.
{% endstep %}

{% step %}

#### Redirect to your IdP

Reach redirects the customer to your IdP login page.
{% endstep %}

{% step %}

#### Authentication happens on your systems

Customer enters credentials in your IdP. Reach is not involved in credential validation.
{% endstep %}

{% step %}

#### IdP sends a signed SAML assertion to Reach

Your IdP sends a digitally signed SAML response to Reach.
{% endstep %}

{% step %}

#### Reach validates and establishes a session

Reach validates the signature and required attributes. Reach then creates a session for the customer.
{% endstep %}
{% endstepper %}

### Required identity attributes (customer assertion)

The SAML assertion must include the fields Reach uses to identify and link the customer. You define the exact attribute names during mapping.

| Attribute           | Required | What Reach uses it for                                              |
| ------------------- | -------- | ------------------------------------------------------------------- |
| Username            | Yes      | Identifies the customer in the Reach session.                       |
| Email address       | Yes      | Communications and account matching.                                |
| Customer account ID | Yes      | Your internal identifier used to link to the correct Reach account. |

{% hint style="warning" %}
Customer account ID should be stable. Avoid values that change during account migrations or billing moves.
{% endhint %}

### Sample SAML SSO Attribute Payload (Reach)

These examples show the **attributes Reach expects after mapping**.

Your IdP attribute names can differ. Reach maps them during setup.

#### Customer SSO – Additional parameters

```json
{
  "account_id": "ACC-987654321"
}
```

#### Example (Customer login)

```json
{
  "email": "customer@brand.com",
  "username": "cust789",
  "full_name": "Jane Smith",
  "account_id": "ACC-123456789"
}
```

### Session behavior

* Reach establishes a session token after SAML validation.
* Backend API calls during the session are validated against the token.
* If the token expires or is invalid, the customer is redirected back to your IdP to re-authenticate.

### Security model

Your brand remains the system of record for identity.

* Your brand controls password policies, MFA requirements, lockouts, and access revocation.
* Reach trusts only **digitally signed** SAML assertions.
* Unsigned or tampered assertions are rejected.
* Reach does not store or expose customer passwords.

### Responsibilities

#### Your brand provides

* IdP-side SAML configuration.
* SSO login endpoint (IdP URL).
* X.509 certificate for assertion signing.
* Attribute mappings for customer assertions.
* Customer identity lifecycle management.
* MFA, lockouts, and access policy enforcement.

#### Reach provides

* SP metadata for IdP configuration.
* Assertion Consumer Service (ACS) endpoints.
* Secure session handling post-authentication.
* Support during setup and testing.

### Commercial and onboarding considerations

SSO is a paid add-on. It must be contracted explicitly.

* Selecting SSO adds build time during onboarding.
* Enabling SSO post-launch typically requires a formal change order.

### Setup checklist

{% stepper %}
{% step %}

#### Confirm IdP readiness

Confirm your IdP supports SAML 2.0 SP-initiated flows.
{% endstep %}

{% step %}

#### Exchange metadata

Reach provides SP metadata and ACS details. You provide IdP metadata and signing certificate details.
{% endstep %}

{% step %}

#### Map required attributes

Map `Username`, `Email address`, and `Customer account ID`.
{% endstep %}

{% step %}

#### Test login and logout behavior

Validate:

* login redirect and return to the correct page
* token expiry and re-authentication
* expected behavior after logout / session invalidation
  {% endstep %}

{% step %}

#### Sign off for production

Complete non-production testing before requesting production enablement.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Questions or clarification? Reach out to your respective account manager or email at <accounts@reachmobile.com> for help and support.
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.reachplatform.com/technical/bolt-on-setup/sso-end-customers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.