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.
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
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 |
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.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"
}
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) |
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 |
