SAML 2.0

SAML (Security Assertion Markup Language) 2.0 is an XML-based framework for exchanging authentication and authorization data between parties. Authrim supports both Identity Provider (IdP) and Service Provider (SP) roles for enterprise SSO integrations.

Overview

Standard: SAML 2.0 Core Specification
Status: Fully Implemented
Roles: IdP (Identity Provider) and SP (Service Provider)

Use Cases

Enterprise SSO: Integrate with enterprise identity systems (AD FS, Okta, Azure AD)
Legacy Application Support: Connect with applications that only support SAML
Federation: Establish trust relationships between organizations
Regulatory Compliance: Meet requirements for standards-based authentication

Implementation Status

Fully Implemented

Feature	IdP	SP	Notes
SSO (Single Sign-On)	Yes	Yes	SP-initiated and IdP-initiated
SLO (Single Logout)	Yes	Yes	LogoutRequest/LogoutResponse
HTTP-POST Binding	Yes	Yes	Primary binding
HTTP-Redirect Binding	Yes	Yes	Deflate + Base64 encoding
Metadata Generation	Yes	Yes	XML metadata documents
XML Signature (RSA-SHA256)	Yes	Yes	Sign and verify
NameID Formats	Yes	Yes	Email, Persistent, Transient
Attribute Mapping	Yes	Yes	Configurable per provider
Session Integration	Yes	Yes	SessionStore DO
Replay Protection	Yes	Yes	SAMLRequestStore DO
JIT Provisioning	-	Yes	Auto user creation

Not Implemented

Feature	Reason
Assertion Encryption	Design decision: signing only
Artifact Binding	SOAP backchannel complexity
ECP Profile	Mobile-specific; out of scope

Endpoints

IdP Endpoints

Endpoint	Method	Description
`/saml/idp/metadata`	GET	IdP metadata document
`/saml/idp/sso`	GET/POST	Single Sign-On service
`/saml/idp/slo`	GET/POST	Single Logout service

SP Endpoints

Endpoint	Method	Description
`/saml/sp/metadata`	GET	SP metadata document
`/saml/sp/acs`	POST	Assertion Consumer Service
`/saml/sp/slo`	GET/POST	Single Logout service
`/saml/sp/init`	GET	SP-initiated SSO start

SSO Flow Diagrams

SP-Initiated SSO

User accesses protected resource at SP
SP redirects user to IdP with AuthnRequest
IdP authenticates user (if not already logged in)
IdP generates SAML Response with Assertion
IdP redirects user back to SP’s ACS URL
SP validates response and grants access

IdP-Initiated SSO

User logs into IdP portal
User selects SP application
IdP generates SAML Response with Assertion
IdP redirects user to SP’s ACS URL
SP validates response and grants access

Implementation Guide

1. Register SAML Provider (Admin API)

POST /api/admin/saml/providers
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "name": "Corporate SSO",
  "type": "sp",
  "entity_id": "https://sp.corp.example.com",
  "metadata_url": "https://sp.corp.example.com/saml/metadata",
  "acs_url": "https://sp.corp.example.com/saml/acs",
  "slo_url": "https://sp.corp.example.com/saml/slo",
  "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sign_assertions": true,
  "sign_authn_requests": true,
  "attribute_mappings": [
    { "saml_attribute": "email", "user_claim": "email" },
    { "saml_attribute": "displayName", "user_claim": "name" },
    { "saml_attribute": "groups", "user_claim": "groups" }
  ]
}

2. Retrieve IdP Metadata

For configuring external SPs, retrieve the IdP metadata:

GET /saml/idp/metadata

Returns XML metadata including:

Entity ID
SSO endpoints (POST and Redirect)
SLO endpoints
Signing certificate (X.509)

3. Configure External SP

Use the metadata to configure the external SP with:

IdP Entity ID
SSO URL
SLO URL (optional)
IdP Certificate for signature verification

SP-Initiated SSO Flow

For SP-initiated flows, redirect users to:

GET /saml/idp/sso?SAMLRequest=<base64_deflate_encoded>&RelayState=<optional>

Or POST to:

POST /saml/idp/sso
Content-Type: application/x-www-form-urlencoded

SAMLRequest=<base64_encoded>&RelayState=<optional>

Attribute Mapping

Authrim maps user claims to SAML attributes:

SAML Attribute	User Claim	Example Value
`email`	`email`	[email protected]
`displayName`	`name`	John Doe
`firstName`	`given_name`	John
`lastName`	`family_name`	Doe
`groups`	`groups`	[“admin”, “users”]

Custom attribute mappings can be configured per provider.

NameID Formats

Format	URI	Description
Email	`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`	Email address
Persistent	`urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`	Opaque persistent ID
Transient	`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`	One-time identifier
Unspecified	`urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`	Any format

Security Features

Signature Verification

All SAML assertions are cryptographically signed using RSA-SHA256:

Canonicalize XML
Create SignedInfo
Sign with RSA key
Add Signature element

Replay Attack Prevention

Request ID Tracking: Each AuthnRequest ID is stored
InResponseTo Validation: Response must reference stored request
Assertion ID Tracking: Assertion IDs stored to prevent replay
Time Validation: NotBefore/NotOnOrAfter conditions enforced
Clock Skew Tolerance: 60 seconds allowed for time drift

Configuration

Provider Configuration Options

Field	Type	Description
`name`	string	Display name
`type`	”sp” \| “idp”	Provider type
`entity_id`	string	SAML Entity ID
`metadata_url`	string	URL to fetch metadata
`acs_url`	string	Assertion Consumer Service URL
`slo_url`	string	Single Logout URL
`name_id_format`	string	NameID format
`sign_assertions`	boolean	Sign SAML assertions
`sign_authn_requests`	boolean	Require signed requests
`attribute_mappings`	array	Claim to attribute mappings

SAML Status Codes

Status Code	Description
`Success`	Authentication successful
`Requester`	Request error (invalid format)
`Responder`	IdP error (internal error)
`AuthnFailed`	Authentication failed
`RequestDenied`	Request denied by policy

Testing

Test with SAML Tracer

Install SAML Tracer browser extension
Initiate SSO flow
Inspect SAML Request/Response

Test with SimpleSAMLphp

docker run -p 8080:80 \
  -e SIMPLESAMLPHP_SP_ENTITY_ID=https://test-sp.example.com \
  cirrusid/simplesamlphp

Limitations

Encryption: Assertion encryption not supported (signing only)
Artifact Binding: Not implemented (HTTP-POST covers most use cases)
SOAP Binding: Not supported
ECP Profile: Not supported