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
Metadata Import/Refresh	Yes	Yes	Admin preview, import, and refresh endpoints
Signing Rollover	Yes	Yes	Publish/promote/retire signing keys

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

Admin Endpoints

Endpoint	Method	Description
/api/admin/saml-settings	GET/PUT	Tenant SAML settings
/api/admin/saml-settings/local-signing	POST	Local signing key settings
/api/admin/saml-settings/local-signing/dr-bundle	POST	Export local signing disaster-recovery bundle
/api/admin/saml-settings/local-signing/dr-bundle/import	POST	Import local signing disaster-recovery bundle
/api/admin/saml-providers	GET/POST	List or create SAML providers
/api/admin/saml-providers/:id	GET/PUT/DELETE	Read, update, or delete a provider
/api/admin/saml-attribute-presets	GET/POST	List or create attribute presets
/api/admin/saml-metadata/preview	POST	Preview metadata before import
/api/admin/saml-metadata/previews/:previewId/entities	GET	List entities from an aggregate metadata preview
/api/admin/saml-metadata/previews/:previewId/batch-create	POST	Start batch provider creation from aggregate metadata
/api/admin/saml-metadata/batches/:batchId	GET	Get aggregate metadata batch status
/api/admin/saml-metadata/certificate-preview	POST	Preview federation trust certificate metadata
/api/admin/saml-providers/:id/import-metadata	POST	Import metadata into a provider
/api/admin/saml-providers/:id/refresh-metadata	POST	Refresh remote metadata
/api/admin/saml-providers/:id/signing-rollover/*	POST	Publish, promote, or retire signing keys

SSO Flow Diagrams

SP-Initiated SSO

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

IdP-Initiated SSO

1. User logs into IdP portal
2. User selects SP application
3. IdP generates SAML Response with Assertion
4. IdP redirects user to SP’s ACS URL
5. 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	user@example.com
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:

1. Canonicalize XML
2. Create SignedInfo
3. Sign with RSA key
4. Add Signature element

Replay Attack Prevention

1. Request ID Tracking: Each AuthnRequest ID is stored
2. InResponseTo Validation: Response must reference stored request
3. Assertion ID Tracking: Assertion IDs stored to prevent replay
4. Time Validation: NotBefore/NotOnOrAfter conditions enforced
5. 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_responses	boolean	Sign SAML responses
sign_authn_requests	boolean	Require signed requests
allowed_bindings	array	Allowed SSO/SLO bindings
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

1. Install SAML Tracer browser extension
2. Initiate SSO flow
3. 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

References

• SAML 2.0 Core Specification
• SAML 2.0 Bindings
• SAML 2.0 Profiles
• SAML 2.0 Metadata