SAML Integration

Field	Value
Document ID	ASCEND-ENT-004
Version	1.0.0
Last Updated	December 19, 2025
Author	Ascend Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 7 minutes | Skill Level: Advanced

Overview

ASCEND supports SAML 2.0 for enterprise Single Sign-On. SAML provides robust identity federation with enterprise identity providers.

Supported IdPs

Provider	Status	Notes
Okta	✅ Full support	SP and IdP initiated
Azure AD	✅ Full support	Microsoft Entra ID
OneLogin	✅ Full support
Ping Identity	✅ Full support
ADFS	✅ Full support	Windows Server
Google Workspace	✅ Full support
Custom SAML	✅ Full support	Any SAML 2.0 IdP

Service Provider Metadata

Get SP Metadata

curl "https://pilot.owkai.app/api/sso/saml/metadata" \
  -H "Authorization: Bearer <admin_jwt>"

SP Metadata:

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  entityID="https://pilot.owkai.app/sso/saml">
  <md:SPSSODescriptor
    AuthnRequestsSigned="true"
    WantAssertionsSigned="true"
    protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:NameIDFormat>
      urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    </md:NameIDFormat>
    <md:AssertionConsumerService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://pilot.owkai.app/sso/saml/callback"
      index="0"/>
    <md:SingleLogoutService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://pilot.owkai.app/sso/saml/logout"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

SP Configuration Values

Setting	Value
Entity ID	https://pilot.owkai.app/sso/saml/{domain}
ACS URL	https://pilot.owkai.app/sso/saml/callback
SLO URL	https://pilot.owkai.app/sso/saml/logout
NameID Format	emailAddress

Configuration

Configure via Metadata URL

curl -X POST "https://pilot.owkai.app/api/sso/saml/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "idp_metadata_url": "https://company.okta.com/app/exk123/sso/saml/metadata"
  }'

Configure via Metadata XML

curl -X POST "https://pilot.owkai.app/api/sso/saml/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "idp_metadata_xml": "<?xml version=\"1.0\"?>..."
  }'

Manual Configuration

curl -X POST "https://pilot.owkai.app/api/sso/saml/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "idp_entity_id": "https://idp.company.com",
    "idp_sso_url": "https://idp.company.com/sso",
    "idp_slo_url": "https://idp.company.com/slo",
    "idp_certificate": "-----BEGIN CERTIFICATE-----\n..."
  }'

Attribute Mapping

Required Attributes

ASCEND Attribute	Common SAML Names
email	email, emailAddress, mail, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
firstName	firstName, givenName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
lastName	lastName, surname, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
groups	groups, memberOf, http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

Configure Attribute Mapping

curl -X PUT "https://pilot.owkai.app/api/sso/saml/company.com/attributes" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "attribute_mapping": {
      "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
      "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
      "groups": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups",
      "role": "custom:ascend_role"
    }
  }'

Provider-Specific Setup

Okta

1. Create SAML 2.0 Application
2. Configure:
   • Single Sign On URL: https://pilot.owkai.app/sso/saml/callback
   • Audience URI: https://pilot.owkai.app/sso/saml/company.com
   • Name ID format: Email Address
3. Add attribute statements for groups

Azure AD

1. Create Enterprise Application
2. Configure SAML SSO
3. Basic SAML Configuration:
   • Identifier: https://pilot.owkai.app/sso/saml/company.com
   • Reply URL: https://pilot.owkai.app/sso/saml/callback
4. Configure claims

ADFS

# Add Relying Party Trust
Add-AdfsRelyingPartyTrust -Name "ASCEND" `
  -MetadataUrl "https://pilot.owkai.app/sso/saml/metadata/company.com"

Security Settings

Configure Signing & Encryption

curl -X PUT "https://pilot.owkai.app/api/sso/saml/company.com/security" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "sign_authn_requests": true,
    "require_signed_assertions": true,
    "require_encrypted_assertions": false,
    "signature_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
    "digest_algorithm": "http://www.w3.org/2001/04/xmlenc#sha256",
    "want_assertions_encrypted": true,
    "encryption_algorithm": "http://www.w3.org/2001/04/xmlenc#aes256-cbc"
  }'

Certificate Management

# Upload new certificate
curl -X POST "https://pilot.owkai.app/api/sso/saml/company.com/certificate" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "certificate": "-----BEGIN CERTIFICATE-----\n...",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...",
    "activate_immediately": false
  }'

# Activate certificate
curl -X PUT "https://pilot.owkai.app/api/sso/saml/company.com/certificate/activate" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "certificate_id": "cert_abc123"
  }'

Single Logout (SLO)

Configure SLO

curl -X PUT "https://pilot.owkai.app/api/sso/saml/company.com/slo" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "enabled": true,
    "idp_slo_url": "https://idp.company.com/slo",
    "binding": "HTTP-POST"
  }'

SLO Flow

User clicks logout
       │
       ▼
┌─────────────────┐
│ ASCEND sends    │
│ LogoutRequest   │───▶ IdP
└─────────────────┘
       │
       │◀─── LogoutResponse
       ▼
┌─────────────────┐
│ Session         │
│ terminated      │
└─────────────────┘

IdP-Initiated SSO

Enable IdP-Initiated

curl -X PUT "https://pilot.owkai.app/api/sso/saml/company.com/idp-initiated" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "enabled": true,
    "default_relay_state": "/dashboard",
    "allowed_relay_states": ["/dashboard", "/actions", "/agents"]
  }'

Testing

Test SAML Configuration

curl -X POST "https://pilot.owkai.app/api/sso/saml/company.com/test" \
  -H "Authorization: Bearer <admin_jwt>"

Decode SAML Response

curl -X POST "https://pilot.owkai.app/api/sso/saml/decode" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "saml_response": "base64-encoded-response"
  }'

Response:

{
  "issuer": "https://idp.company.com",
  "subject": "user@company.com",
  "session_index": "_abc123",
  "attributes": {
    "email": "user@company.com",
    "firstName": "John",
    "lastName": "Doe",
    "groups": ["ascend-admins", "engineering"]
  },
  "conditions": {
    "not_before": "2025-12-15T10:00:00Z",
    "not_on_or_after": "2025-12-15T10:05:00Z"
  },
  "signature_valid": true
}

Troubleshooting

Common Errors

Error	Cause	Solution
invalid_signature	Certificate mismatch	Update IdP certificate
assertion_expired	Clock skew	Sync server time, increase skew tolerance
unknown_issuer	Wrong entity ID	Verify IdP entity ID
no_valid_assertion	Assertion rejected	Check conditions, signature

Debug Logging

curl -X PUT "https://pilot.owkai.app/api/sso/saml/company.com/debug" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "enabled": true,
    "log_saml_requests": true,
    "log_saml_responses": true,
    "expires_in_hours": 24
  }'

View SAML Logs

curl "https://pilot.owkai.app/api/sso/saml/company.com/logs?hours=24" \
  -H "Authorization: Bearer <admin_jwt>"

Best Practices

1. Use SHA-256 - Avoid SHA-1 for signatures
2. Require signed assertions - Never accept unsigned
3. Short validity windows - 5 minutes or less
4. Regular certificate rotation - Annual minimum
5. Test before production - Use debug mode

Next Steps

• OIDC Integration - OIDC configuration
• SSO Configuration - General SSO setup
• Role Mapping - Configure roles

---

Document Version: 1.0.0 | Last Updated: December 2025