SAML Integration Recipes

Configure and validate AuthOS SAML with representative Service Providers

AuthOS release 0.8.2 API v1 Latest-only documentation
Updated Jul 15, 2026 Edit this page
On this page

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)

  1. Provide metadata URL to Service Provider: 
    https://sso.example.com/saml/acme-corp/main-app/metadata
  2. Service Provider automatically imports IdP configuration

Option B: Manual Configuration

  1. Get certificate: 
    curl https://sso.example.com/api/organizations/acme-corp/services/main-app/saml/certificate \
  -H "Authorization: Bearer {jwt_token}"
  2. Configure SP with:
    • IdP Entity ID: https://sso.example.com/saml/acme-corp/main-app
    • SSO URL: https://sso.example.com/saml/acme-corp/main-app/sso
    • Signing Certificate: (from response)
    • NameID Format: emailAddress

Step 3: Test Authentication

SP-Initiated Flow:

  1. User navigates to Service Provider
  2. Clicks “Login with SSO” or similar
  3. SP redirects to IdP SSO endpoint with SAMLRequest
  4. User authenticates via OAuth or password
  5. IdP generates signed SAMLResponse
  6. User is automatically submitted back to SP
  7. User is logged into Service Provider

IdP-Initiated Flow:

  1. User logs into your platform/dashboard
  2. Clicks “Login to Salesforce” button
  3. Application calls IdP-initiated login endpoint
  4. IdP generates unsolicited SAMLResponse
  5. User is automatically submitted to SP
  6. User is logged into Service Provider

Step 4: Monitor and Maintain

# View SAML configuration
curl https://sso.example.com/api/organizations/acme-corp/services/main-app/saml \
  -H "Authorization: Bearer {jwt_token}"

# Check audit logs for a SAML certificate-generation event
curl 'https://sso.example.com/api/organizations/acme-corp/audit-log?action=saml.certificate_generated' \
  -H "Authorization: Bearer {jwt_token}"

# Rotate certificate (before expiration)
curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/saml/certificate \
  -H "Authorization: Bearer {jwt_token}"

# After every SP trusts the active certificate, optionally end overlap early
curl -X DELETE https://sso.example.com/api/organizations/acme-corp/services/main-app/saml/certificate/overlap \
  -H "Authorization: Bearer {jwt_token}"

Service Provider Integration Examples

Salesforce Integration

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",
    "attribute_mapping": {
      "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    },
    "sign_assertions": true,
    "sign_response": true
  }'

Salesforce Setup:

  1. Setup > Identity > Single Sign-On Settings
  2. Enable SAML
  3. New from Metadata File
  4. Enter: https://sso.example.com/saml/acme-corp/main-app/metadata
  5. Save

AWS IAM Integration

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": "urn:amazon:webservices",
    "acs_url": "https://signin.aws.amazon.com/saml",
    "name_id_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "attribute_mapping": {
      "email": "https://aws.amazon.com/SAML/Attributes/RoleSessionName"
    },
    "sign_assertions": true,
    "sign_response": true
  }'

AWS Setup:

  1. IAM > Identity Providers > Create Provider
  2. Provider Type: SAML
  3. Metadata: Upload metadata XML or use URL
  4. Create IAM roles and trust policies

Google Workspace Integration

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": "google.com",
    "acs_url": "https://www.google.com/a/acme.com/acs",
    "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "sign_assertions": true,
    "sign_response": false
  }'

Google Workspace Setup:

  1. Admin Console > Security > Authentication > SSO with third party IdP
  2. Enable SSO
  3. Upload IdP metadata or enter details manually