SSO Configuration

Field	Value
Document ID	ASCEND-ENT-007
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: 8 minutes | Skill Level: Advanced

Overview

ASCEND supports enterprise Single Sign-On (SSO) via SAML 2.0 and OpenID Connect (OIDC). SSO enables users to authenticate using their corporate identity provider.

Supported Protocols

Protocol	Version	Use Case
SAML 2.0	Full support	Enterprise IdPs (Okta, Azure AD, OneLogin)
OIDC	1.0	Modern IdPs, OAuth 2.0 integration

Prerequisites

Before configuring SSO:

1. Admin Access - Organization admin or super_admin role
2. IdP Access - Administrator access to your identity provider
3. Domain Verification - Verify ownership of your email domain
4. SSL Certificate - HTTPS required for all SSO endpoints

Configuration Steps

Step 1: Verify Domain

curl -X POST "https://pilot.owkai.app/api/sso/domains/verify" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "verification_method": "dns_txt"
  }'

Response:

{
  "domain": "company.com",
  "verification_record": "ascend-verify=abc123xyz",
  "record_type": "TXT",
  "instructions": "Add this TXT record to your DNS configuration"
}

Step 2: Create SSO Configuration

curl -X POST "https://pilot.owkai.app/api/sso/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "protocol": "saml",
    "domain": "company.com",
    "idp_metadata_url": "https://idp.company.com/metadata.xml",
    "default_role": "viewer",
    "auto_provision_users": true,
    "jit_provisioning": true
  }'

Step 3: Get Service Provider Metadata

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

Response:

{
  "entity_id": "https://pilot.owkai.app/sso/saml/company.com",
  "acs_url": "https://pilot.owkai.app/sso/saml/callback",
  "slo_url": "https://pilot.owkai.app/sso/saml/logout",
  "certificate": "-----BEGIN CERTIFICATE-----\n...",
  "metadata_url": "https://pilot.owkai.app/sso/saml/metadata/company.com"
}

Step 4: Test SSO

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

Step 5: Enable SSO

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

SAML Configuration

IdP Configuration Requirements

Configure your IdP with these ASCEND settings:

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	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Signature Algorithm	RSA-SHA256

Required SAML Attributes

Attribute	Description	Required
email	User email address	Yes
firstName	User first name	No
lastName	User last name	No
groups	Group memberships	No
role	ASCEND role	No

Attribute Mapping

curl -X PUT "https://pilot.owkai.app/api/sso/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"
    }
  }'

OIDC Configuration

Configure OIDC

curl -X POST "https://pilot.owkai.app/api/sso/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "protocol": "oidc",
    "domain": "company.com",
    "issuer": "https://idp.company.com",
    "client_id": "ascend-client-id",
    "client_secret": "client-secret-here",
    "authorization_endpoint": "https://idp.company.com/oauth2/authorize",
    "token_endpoint": "https://idp.company.com/oauth2/token",
    "userinfo_endpoint": "https://idp.company.com/oauth2/userinfo",
    "jwks_uri": "https://idp.company.com/.well-known/jwks.json",
    "scopes": ["openid", "email", "profile", "groups"]
  }'

OIDC Redirect URIs

Configure these redirect URIs in your IdP:

https://pilot.owkai.app/sso/oidc/callback
https://dashboard.owkai.app/auth/callback

Role Mapping

Configure Group-to-Role Mapping

curl -X PUT "https://pilot.owkai.app/api/sso/company.com/role-mapping" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "role_mapping": {
      "ascend-admins": "admin",
      "ascend-managers": "manager",
      "ascend-analysts": "analyst",
      "ascend-viewers": "viewer"
    },
    "default_role": "viewer",
    "require_group_membership": true
  }'

Role Hierarchy

Role	Permissions
super_admin	Full system access
admin	Organization admin
manager	Approve actions, manage agents
analyst	View and analyze
viewer	Read-only access

Just-In-Time Provisioning

Configure JIT

curl -X PUT "https://pilot.owkai.app/api/sso/company.com/jit" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "enabled": true,
    "auto_create_users": true,
    "auto_update_attributes": true,
    "auto_deactivate_on_removal": true,
    "default_role": "viewer",
    "allowed_domains": ["company.com", "subsidiary.company.com"]
  }'

Session Management

Configure Session Settings

curl -X PUT "https://pilot.owkai.app/api/sso/company.com/session" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "session_duration_minutes": 480,
    "idle_timeout_minutes": 30,
    "require_reauthentication": true,
    "reauthentication_interval_hours": 24,
    "single_logout_enabled": true
  }'

Multi-IdP Support

Configure Multiple IdPs

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

Troubleshooting

View SSO Logs

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

Common Issues

Issue	Cause	Solution
Invalid signature	Certificate mismatch	Re-download SP metadata
User not found	JIT disabled	Enable JIT provisioning
Role not assigned	Missing group claim	Check attribute mapping
Session expired	Short IdP timeout	Align session durations

Test SAML Response

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

Security Best Practices

1. Certificate Management

• Use certificates with at least 2048-bit RSA keys
• Rotate certificates annually
• Configure certificate rollover before expiration

2. Encryption

curl -X PUT "https://pilot.owkai.app/api/sso/company.com/security" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "require_signed_assertions": true,
    "require_encrypted_assertions": true,
    "signature_algorithm": "RSA-SHA256",
    "digest_algorithm": "SHA256"
  }'

3. Access Controls

• Require group membership for access
• Use specific groups rather than "all users"
• Regular access reviews

Next Steps

• SAML Configuration - Detailed SAML setup
• OIDC Configuration - Detailed OIDC setup
• User Management - Role-based access

---

Document Version: 1.0.0 | Last Updated: December 2025