> 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-agents.md).

# SSO — Agents

Configure SAML 2.0 SSO for agent access to Reach Central.

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

### Overview

Agent SSO lets agents sign in to Reach Central 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 **agent SSO** only. For end-customer SSO, use [SSO — End Customers](/technical/bolt-on-setup/sso-end-customers.md).
{% endhint %}

### Why brands enable agent SSO

* Remove duplicate Reach Central credentials.
* Keep MFA, lockouts, and password policy in your IdP.
* Improve agent productivity with fewer login resets.
* Increase auditability for agent actions.

### Who it applies to

* Customer support agents
* Sales agents
* Brand operational users

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

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

{% stepper %}
{% step %}

#### Agent initiates login

Agent starts login from Reach Central.
{% endstep %}

{% step %}

#### Redirect to your IdP

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

{% step %}

#### Authentication happens on your systems

Agent 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 Reach Central.
{% endstep %}
{% endstepper %}

### Required identity attributes (agent assertion)

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

| Attribute           | Required | What Reach uses it for                                                  |
| ------------------- | -------- | ----------------------------------------------------------------------- |
| Agent email         | Yes      | Primary identifier to map the agent to a Reach Central user.            |
| Agent name          | Yes      | Display name in Reach Central. Also used in audit logs and reporting.   |
| Agent ID            | No       | Reporting attribution and operational analytics.                        |
| Agent role / groups | No       | Optional input to role mapping if you enable role-based access via SSO. |

### 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.

#### Agent SSO (Reach Central) – role parameters

```json
{
  "role": "CARE_AGENT",
  "agent_id": "AGT-4567"
}
```

#### Example (Agent login)

```json
{
  "email": "agent@brand.com",
  "username": "agent123",
  "full_name": "John Doe",
  "role": "CARE_AGENT",
  "agent_id": "AGT-4567"
}
```

### Authorization and attribution

SSO covers **authentication** only. It does not automatically grant permissions.

* **Authentication**: proven by the IdP via SAML.
* **Authorization**: controlled by Reach Central roles and permissions.

Agent actions (customer changes, purchases, support operations) are attributed to the authenticated agent. This supports agent-level auditability in reporting.

### Session behavior

* Reach Central access is granted via a session token created after SAML validation.
* If the session token expires or is invalid, Reach Central requires re-authentication via your IdP.

### 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 agent passwords.

### Responsibilities

#### Your brand provides

* IdP-side SAML configuration.
* SSO login endpoint (IdP URL).
* X.509 certificate for assertion signing.
* Attribute mappings for agent assertions.
* Agent lifecycle management (joiners/movers/leavers).
* MFA, lockouts, and access policy enforcement.

#### Reach provides

* SP metadata for IdP configuration.
* Assertion Consumer Service (ACS) endpoints.
* Secure session handling post-authentication.
* Platform-level authorization and role management.
* Audit logging for authenticated sessions and actions.
* 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.

#### Scope options (for contracting)

| Scope                | Who it covers                   | When to choose this                                                      |
| -------------------- | ------------------------------- | ------------------------------------------------------------------------ |
| Agent SSO only       | Agents in Reach Central         | When agent productivity and centralized access control are the priority. |
| Customer SSO only    | End customers on web/mobile/app | When you want a seamless self-care experience.                           |
| Customer + Agent SSO | Both customers and agents       | When you want consistent identity across all touchpoints.                |

### 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 your IdP metadata and signing certificate details.
{% endstep %}

{% step %}

#### Map required attributes

Map agent email and agent name at minimum. Add agent ID and role/groups if you want richer reporting or automated role mapping.
{% endstep %}

{% step %}

#### Test with real agent accounts

Validate login, session expiry, and access revocation. Confirm audit attribution shows the right agent identity.
{% 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-agents.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.