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

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

Human users accessing the companion dashboard — authenticated via your corporate identity provider using SAML 2.0 or OIDC
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.

Microsoft Entra ID

Step-by-step OIDC and SAML setup for Microsoft Entra ID (Azure AD), including group claims configuration and multi-environment guidance.

Okta

Step-by-step OIDC and SAML setup for Okta, including group claims and application assignment configuration.

PingFederate

Step-by-step SAML 2.0 setup for PingFederate, including SP connection configuration and attribute contract mapping.

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. 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 — per-agent model

The dashboard enforces roles at the per-agent level. Each deployed workflow agent carries its own pair of roles: a submitter role and a reviewer role scoped exclusively to that agent’s cases. Role assignment is driven by IdP group membership claims — no manual user management is required in the dashboard itself. Role naming convention:

role type	IdP group name pattern	permissions
`{agent-slug}-admin`	`layerup-{agent-slug}-admins`	Full configuration access for the specified agent: manage AOP settings, configure thresholds and escalation rules, adjust confidence tier configuration, and administer agent-level settings. Includes all reviewer permissions.
`{agent-slug}-submitter`	`layerup-{agent-slug}-submitters`	Submit new cases, upload documents, and view own case outputs for the specified agent only
`{agent-slug}-reviewer`	`layerup-{agent-slug}-reviewers`	Read-only access to all case outputs, confidence scores, evidence citations, and requirement lists for the specified agent only

Examples across active agents:

IdP group	agent	access level
`layerup-contents-valuation-admins`	Contents Valuation	Configure + administer + read-only all
`layerup-contents-valuation-submitters`	Contents Valuation	Submit + view own
`layerup-contents-valuation-reviewers`	Contents Valuation	Read-only all
`layerup-dental-underwriting-admins`	Dental Underwriting	Configure + administer + read-only all
`layerup-dental-underwriting-submitters`	Dental Underwriting	Submit + view own
`layerup-dental-underwriting-reviewers`	Dental Underwriting	Read-only all
`layerup-group-disability-underwriting-admins`	Group STD/LTD Underwriting	Configure + administer + read-only all
`layerup-auto-fnol-submitters`	Auto FNOL	Submit + view own

A user may belong to multiple groups and will receive the combined permissions across all mapped agents. Users with no matching group membership are denied access at the ALB layer before reaching the dashboard application.

When a new agent is activated in your deployment, your Layerup implementation engineer provides the two new IdP group names for that agent ({agent - slug} -submitters and {agent - slug}-reviewers). Your IdP administrator creates those groups, assigns the appropriate users, and maps them in the Layerup application registration. No changes to the dashboard container or the agent container are required — permission expansion is purely an IdP configuration change.

Multi-environment group naming: For deployments with separate Development, UAT, and Production environments sharing a single IdP tenant, prefix the group name with the environment to maintain access isolation:

environment	example group
Development	`layerup-dev-contents-valuation-admins`
Development	`layerup-dev-contents-valuation-submitters`
UAT	`layerup-uat-contents-valuation-submitters`
Production	`layerup-prod-contents-valuation-admins`
Production	`layerup-prod-contents-valuation-submitters`

Layerup provisions a separate application registration per environment in your IdP, each mapped to its own set of environment-prefixed groups.

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.

Your Layerup implementation engineer provides the SP Entity ID and Assertion Consumer Service (ACS) URL for the dashboard
Your IdP administrator creates an application entry for the Layerup dashboard using these values
Your IdP administrator configures the group claims to map to layerup-submitters and layerup-reviewers (or your equivalent group names)
Your AWS team configures the ALB listener rule with your IdP’s OIDC discovery URL or SAML metadata URL
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:

Your IdP’s SAML metadata URL (for SAML 2.0) or OIDC discovery document URL (for OIDC)
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.

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.

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. 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.uselayerup.com/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.uselayerup.com/.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 a contents valuation workbench and a dental claims 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.uselayerup.com`
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

Foundations

Deployment Architecture

Security & Governance

Data & Integration

Observability & Resilience

Configuration & Lifecycle

Confidence & Scoring

Reference

SSO & API Authentication

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

Microsoft Entra ID

Okta

PingFederate

Part 1 — Human user authentication (dashboard SSO)

How it works

Supported protocols and identity providers

Required claims and attribute mapping

Role assignment — per-agent model

Configuration process

For Option 2 (your private cloud)

For Option 3 (Layerup’s Cloud)

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

Overview

Token request

API scopes

Credential management

Option 2 vs Option 3 — authentication comparison

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

Microsoft Entra ID

Okta

PingFederate

​Part 1 — Human user authentication (dashboard SSO)

​How it works

​Supported protocols and identity providers

​Required claims and attribute mapping

​Role assignment — per-agent model

​Configuration process

​For Option 2 (your private cloud)

​For Option 3 (Layerup’s Cloud)

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

​Overview

​Token request

​API scopes

​Credential management

​Option 2 vs Option 3 — authentication comparison

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

Part 1 — Human user authentication (dashboard SSO)

How it works

Supported protocols and identity providers

Required claims and attribute mapping

Role assignment — per-agent model

Configuration process

For Option 2 (your private cloud)

For Option 3 (Layerup’s Cloud)

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

Overview

Token request

API scopes

Credential management

Option 2 vs Option 3 — authentication comparison