SAML 2.0 Identity Provider API on AuthOS Docs | Auth Operating System API and SDK Guides

SAML Configuration

Mon, 01 Jan 0001 00:00:00 +0000

SAML Configuration Management

POST /api/organizations/:org_slug/services/:service_slug/saml

Configure SAML Identity Provider settings for a service. This endpoint sets up the SAML integration parameters required for the service to function as an IdP.

Authentication: Required (Organization Management JWT)

Permissions: Service-management capability or explicit service-manager relation

Path Parameters:

Parameter	Type	Description
`org_slug`	string	Organization slug
`service_slug`	string	Service slug

Request Body:

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable or disable SAML IdP functionality
`entity_id`	string	Yes (if enabled)	Service Provider’s entity ID (unique identifier)
`acs_url`	string	Yes (if enabled)	Assertion Consumer Service URL (where SAMLResponse is sent)
`slo_url`	string	No	Single Logout URL (optional)
`name_id_format`	string	No	NameID format (default: emailAddress)
`attribute_mapping`	object	No	Custom attribute mappings (source field to SAML attribute name)
`sign_assertions`	boolean	No	Sign SAML assertions (default: true)
`sign_response`	boolean	No	Sign SAML response (default: true)

Request Headers:

SAML Certificate Rotation

Mon, 01 Jan 0001 00:00:00 +0000

Certificate Management

POST /api/organizations/:org_slug/services/:service_slug/saml/certificate

Generate a new self-signed X.509 certificate and RSA key pair for signing SAML assertions. The private key is encrypted before storage.

Authentication: Required (Organization Management JWT)

Permissions: Service-management capability or explicit service-manager relation

Path Parameters:

Parameter	Type	Description
`org_slug`	string	Organization slug
`service_slug`	string	Service slug

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/saml/certificate \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

{
  "public_key": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKZ...\n-----END CERTIFICATE-----",
  "valid_from": "2025-01-15T10:30:00Z",
  "valid_until": "2028-01-15T10:30:00Z",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "lifecycle_status": "healthy",
  "expires_in_seconds": 94608000,
  "published_previous_certificates": []
}

Response Fields:

SAML Metadata and SSO

Mon, 01 Jan 0001 00:00:00 +0000

SAML SSO Endpoints

GET /saml/:org_slug/:service_slug/metadata

Retrieve the implemented SAML Identity Provider metadata in XML format. Service Provider requirements vary; validate that the returned metadata contains the fields required by the exact product and version being integrated.

Authentication: None required (public endpoint)

Path Parameters:

Parameter	Type	Description
`org_slug`	string	Organization slug
`service_slug`	string	Service slug

Example Request:

curl https://sso.example.com/saml/acme-corp/main-app/metadata

Response (200 OK):

Content-Type: application/samlmetadata+xml

Response Body (XML):

<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://sso.example.com/saml/acme-corp/main-app">
  <IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
        <X509Data>
          <X509Certificate>MIIDXTCCAkWgAwIBAgIJAKZ...</X509Certificate>
        </X509Data>
      </KeyInfo>
    </KeyDescriptor>
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sso.example.com/saml/acme-corp/main-app/sso"/>
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://sso.example.com/saml/acme-corp/main-app/sso"/>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sso.example.com/saml/acme-corp/main-app/slo"/>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://sso.example.com/saml/acme-corp/main-app/slo"/>
  </IDPSSODescriptor>
  <Organization>
    <OrganizationName xml:lang="en">Acme Corporation</OrganizationName>
    <OrganizationDisplayName xml:lang="en">Acme Corporation</OrganizationDisplayName>
    <OrganizationURL xml:lang="en">https://sso.example.com</OrganizationURL>
  </Organization>
</EntityDescriptor>

Metadata Fields:

SAML Single Logout

Mon, 01 Jan 0001 00:00:00 +0000

GET/POST /saml/:org_slug/:service_slug/slo

SAML Single Logout (SLO) endpoint. Receives a LogoutRequest from the Service Provider, invalidates the user’s sessions, and returns a signed LogoutResponse. This endpoint enables global session termination across federated services.

Authentication: None required (public endpoint)

Path Parameters:

Parameter	Type	Description
`org_slug`	string	Organization slug
`service_slug`	string	Service slug

Query/Form Parameters:

Parameter	Type	Required	Description
`SAMLRequest`	string	Yes	Base64-encoded (optionally deflated) SAML LogoutRequest
`RelayState`	string	No	Opaque value to be returned to SP after logout

Example Request (HTTP-Redirect binding):

SAML Integration Recipes

Mon, 01 Jan 0001 00:00:00 +0000

These recipes are starting points, not published interoperability certification. Validate the exact provider, product version, attributes, and failure behavior before deployment.

Complete SAML Integration Workflow

Step 1: Configure SAML IdP

# 1. Create SAML configuration
curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/saml \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "entity_id": "https://acme.my.salesforce.com",
    "acs_url": "https://acme.my.salesforce.com/services/auth/saml/AssertionConsumerService",
    "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "sign_assertions": true,
    "sign_response": true
  }'

# 2. Generate signing certificate
curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/saml/certificate \
  -H "Authorization: Bearer {jwt_token}"

Step 2: Configure Service Provider

Option A: Metadata URL (Recommended)

SAML Security and Limitations

Mon, 01 Jan 0001 00:00:00 +0000

Limitations

AuthOS SAML is Beta. The documented endpoints are implemented, but AuthOS does not claim SAML conformance or certification and does not yet publish complete product-specific interoperability, abuse-case, external certificate-rotation, or emergency-compromise evidence. Validate the exact Service Provider and both success and failure paths before production.

Single Logout invalidates sessions only for the configured service, not every Service Provider or the AuthOS platform session. IdP-initiated responses are unsolicited and may be rejected by some Service Providers. Certificate rollover publishes one active signer and at most two verification-only previous certificates for a maximum seven-day overlap.

SAML Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting

Common Issues

“No active SAML certificate found”

Cause: Certificate not generated or expired
Solution: Generate new certificate using POST /saml/certificate endpoint

“SAML is not enabled for this service”

Cause: SAML configuration not created or disabled
Solution: Create/enable SAML configuration using POST /saml endpoint

“Invalid or expired SAML state”

Cause: SAML state expired (15 minute timeout) or already used
Solution: User should restart login flow from Service Provider

Service Provider rejects SAMLResponse