> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayerup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO & API Authentication

> Single Sign-On configuration for the companion dashboard and OAuth 2.0 client credentials for system-to-system API authentication — covering both Option 2 (private cloud) and Option 3 (Layerup's Cloud).

# SSO & API authentication — dashboard federation and system-to-system credentials.

Authentication for Layerup AI Agent deployments covers two distinct access patterns with different mechanisms:

1. **Human users** accessing the [companion dashboard](/agents/deployment/dashboard) — authenticated via your corporate identity provider using SAML 2.0 or OIDC
2. **Systems** (your workflow platform, policy admin system) making API calls to submit cases and retrieve output — authenticated via OAuth 2.0 client credentials

Both patterns apply to Option 3 (Layerup's Cloud). For Option 2 (your private cloud), the dashboard authentication is configured entirely by your team against your own ALB listener; system-to-system authentication is handled by your own API Gateway or IAM-signed requests.

***

## Part 1 — Human user authentication (dashboard SSO)

### How it works

The companion dashboard delegates authentication entirely to your corporate identity provider. The dashboard never stores credentials or passwords. On first access, users are redirected to your IdP login page; after authentication, a signed assertion is returned to the dashboard which establishes the user's session and role.

```mermaid theme={null}
flowchart LR
  subgraph user ["User"]
    UW[Underwriter Browser]
  end

  subgraph dashboard ["Layerup Dashboard\nor Internal ALB"]
    SP[Service Provider\nSAML SP or OIDC Client]
  end

  subgraph idp ["Your Identity Provider\nOkta · Azure AD · PingFederate"]
    IDP[Identity Provider\nSSO Portal]
  end

  UW -->|"access dashboard"| SP
  SP -->|"redirect to IdP login"| IDP
  IDP -->|"authenticate user"| UW
  UW -->|"SAML assertion or OIDC token"| SP
  SP -->|"validate + establish session"| UW

  classDef boundary fill:#fafafa,stroke:#111,stroke-width:1.5px,color:#111;
  class user,dashboard,idp boundary;
```

*Fig. A8.1 — SSO authentication flow. The dashboard acts as SAML Service Provider or OIDC Relying Party. Credentials never leave your identity provider.*

***

### Supported protocols and identity providers

| protocol                  | support         | notes                                               |
| ------------------------- | --------------- | --------------------------------------------------- |
| **SAML 2.0**              | Fully supported | SP-initiated and IdP-initiated flows both supported |
| **OIDC (OpenID Connect)** | Fully supported | Authorization code flow with PKCE                   |

| identity provider             | protocol        | status                                         |
| ----------------------------- | --------------- | ---------------------------------------------- |
| Okta                          | SAML 2.0 / OIDC | Certified                                      |
| Microsoft Azure AD / Entra ID | SAML 2.0 / OIDC | Certified                                      |
| PingFederate                  | SAML 2.0        | Certified                                      |
| Google Workspace              | SAML 2.0 / OIDC | Certified                                      |
| CyberArk Identity             | SAML 2.0        | Certified                                      |
| Any SAML 2.0-compliant IdP    | SAML 2.0        | Supported — configuration assistance available |

***

### Required claims and attribute mapping

Your IdP must include the following attributes in the SAML assertion or OIDC ID token:

| claim            | SAML attribute name                                  | OIDC claim              | required                  | purpose                   |
| ---------------- | ---------------------------------------------------- | ----------------------- | ------------------------- | ------------------------- |
| Email address    | `urn:oid:0.9.2342.19200300.100.1.3` or `email`       | `email`                 | Yes                       | Unique user identity      |
| Display name     | `urn:oid:2.16.840.1.113730.3.1.241` or `displayName` | `name`                  | Recommended               | Display in dashboard UI   |
| Group membership | `memberOf` (configurable)                            | `groups` (configurable) | Yes — for role assignment | Determines dashboard role |

#### Role assignment

The dashboard enforces two roles. Role assignment is driven by the group membership claim from your IdP — no manual user management is required in the dashboard itself.

| role        | group membership                                                        | permissions                                                                                                    |
| ----------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `submitter` | Mapped to your designated submission group (e.g., `layerup-submitters`) | Submit new cases, upload documents, view own submissions and their outputs                                     |
| `reviewer`  | Mapped to your designated review group (e.g., `layerup-reviewers`)      | View all case outputs, confidence scores, evidence citations, and requirement lists — read-only, no submission |

A user may belong to both groups, receiving combined permissions. Users with neither group membership are denied access at the ALB layer before reaching the dashboard application.

***

### Configuration process

#### For Option 2 (your private cloud)

Your team configures SSO directly on the ALB listener in your AWS account. The ALB's built-in OIDC and SAML authentication features handle the SSO redirect and assertion validation natively — no additional software is required.

1. Your Layerup implementation engineer provides the **SP Entity ID** and **Assertion Consumer Service (ACS) URL** for the dashboard
2. Your IdP administrator creates an application entry for the Layerup dashboard using these values
3. Your IdP administrator configures the group claims to map to `layerup-submitters` and `layerup-reviewers` (or your equivalent group names)
4. Your AWS team configures the ALB listener rule with your IdP's OIDC discovery URL or SAML metadata URL
5. Layerup validates the SSO flow in the staging environment before go-live

#### For Option 3 (Layerup's Cloud)

Layerup configures SSO on the ALB in Layerup's dedicated cluster. Your team provides:

1. Your IdP's **SAML metadata URL** (for SAML 2.0) or **OIDC discovery document URL** (for OIDC)
2. The group names or OIDs that map to `submitter` and `reviewer` roles in your directory

Layerup provisions the trust configuration and provides the SP metadata for your IdP administrator to complete the registration. The full configuration is validated during the deployment engagement before go-live.

<Note>
  The dashboard session token (issued after successful SSO) has a configurable TTL, defaulting to 8 hours. Sessions are invalidated immediately when a user is removed from the IdP group — no manual session revocation is required.
</Note>

***

## Part 2 — System-to-system authentication (API)

### Overview

Machine-to-machine integration — your workflow system submitting cases and consuming output — uses OAuth 2.0 client credentials. No user is involved in this flow. Your system authenticates directly with a client ID and client secret to obtain a short-lived access token, then presents that token on every API call.

```mermaid theme={null}
flowchart LR
  subgraph system ["Your Integration System"]
    APP[Workflow System\nor Integration Service]
  end

  subgraph auth ["Layerup Auth Server\nor Your API Gateway"]
    TOKEN[Token Endpoint\nOAuth 2.0 Client Credentials]
  end

  subgraph api ["Layerup Agent API\nor Your VPC Endpoint"]
    CASES[Cases API\nSubmit · Status · Output]
  end

  APP -->|"POST /oauth/token\nclient_id + client_secret"| TOKEN
  TOKEN -->|"access_token\nTTL: 1 hour"| APP
  APP -->|"Bearer access_token"| CASES
  CASES -->|"202 Accepted\ncase_id"| APP

  classDef boundary fill:#fafafa,stroke:#111,stroke-width:1.5px,color:#111;
  class system,auth,api boundary;
```

*Fig. A8.2 — OAuth 2.0 client credentials flow. Your system exchanges a client ID and secret for a short-lived access token, then uses that token to authenticate every API call. Tokens expire after 1 hour and are automatically renewed.*

***

### Token request

```
POST https://your-org.auth.layerup.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=lrup_ci_abc123xyz
&client_secret=<secret>
&scope=cases:submit cases:read

Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "cases:submit cases:read"
}
```

Tokens are signed RS256 JWTs. Your system validates the token signature using Layerup's published JWKS endpoint (`https://your-org.auth.layerup.ai/.well-known/jwks.json`) before trusting any token for internal routing decisions.

***

### API scopes

| scope                     | grants                                                             |
| ------------------------- | ------------------------------------------------------------------ |
| `cases:submit`            | Submit new cases, upload documents                                 |
| `cases:read`              | Retrieve case status and output; subscribe to completion webhooks  |
| `cases:submit cases:read` | Full integration access (standard for workflow system credentials) |

Credentials are issued per integration. If your organization has multiple systems that should have independent access — for example, separate credentials for an IDI workbench and a Life submission system — Layerup issues separate client ID/secret pairs with independent scope assignments.

***

### Credential management

| concern                 | how it is handled                                                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Secret storage**      | Store in AWS Secrets Manager or HashiCorp Vault — never in plaintext config files or environment variables                            |
| **Secret rotation**     | Rotate at least every 90 days; Layerup issues the new credential before the old one expires, allowing a zero-downtime rotation window |
| **Compromise response** | Contact your Layerup implementation engineer — the credential is revoked within 15 minutes of a confirmed compromise report           |
| **Credential scoping**  | One client credential per integration system — do not share credentials between multiple systems                                      |

***

## Option 2 vs Option 3 — authentication comparison

| concern                   | Option 2: Your Private Cloud                                            | Option 3: Layerup's Cloud                                                        |
| ------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Dashboard SSO**         | Configured by your team on your ALB listener                            | Configured by Layerup on dedicated cluster ALB — your team provides IdP metadata |
| **IdP federation**        | Direct — your ALB trusts your IdP                                       | Layerup's ALB trusts your IdP via SAML / OIDC trust configured during deployment |
| **System-to-system auth** | Your API Gateway or IAM-signed requests — no Layerup-managed auth layer | OAuth 2.0 client credentials issued by Layerup's auth server                     |
| **Token issuer**          | Your API Gateway / IAM                                                  | `your-org.auth.layerup.ai`                                                       |
| **Secret storage**        | Your AWS Secrets Manager                                                | Your AWS Secrets Manager (credentials provided by Layerup)                       |
| **Credential rotation**   | Your team controls rotation                                             | Coordinated with Layerup — zero-downtime window provided                         |