OIDC Integration

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

Overview

ASCEND supports OpenID Connect (OIDC) for enterprise authentication. OIDC provides a modern, standards-based approach to identity federation.

Supported Providers

Provider	Status	Notes
Okta	✅ Full support	Recommended
Azure AD	✅ Full support	Microsoft Entra ID
Auth0	✅ Full support
Google Workspace	✅ Full support
Ping Identity	✅ Full support
Custom OIDC	✅ Full support	Any OIDC-compliant IdP

Configuration

Basic OIDC Setup

curl -X POST "https://pilot.owkai.app/api/sso/oidc/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "company.com",
    "issuer": "https://company.okta.com",
    "client_id": "0oa1234567890abcdef",
    "client_secret": "your-client-secret",
    "scopes": ["openid", "email", "profile", "groups"],
    "response_type": "code",
    "redirect_uri": "https://pilot.owkai.app/sso/oidc/callback"
  }'

Discovery Configuration

Use OIDC Discovery to auto-configure endpoints:

curl -X POST "https://pilot.owkai.app/api/sso/oidc/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "discovery_url": "https://company.okta.com/.well-known/openid-configuration",
    "client_id": "0oa1234567890abcdef",
    "client_secret": "your-client-secret",
    "scopes": ["openid", "email", "profile", "groups"]
  }'

Manual Endpoint Configuration

curl -X POST "https://pilot.owkai.app/api/sso/oidc/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "issuer": "https://idp.company.com",
    "client_id": "ascend-client",
    "client_secret": "secret",
    "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",
    "end_session_endpoint": "https://idp.company.com/oauth2/logout"
  }'

IdP Configuration

Required Settings in Your IdP

Setting	Value
Application Type	Web Application
Grant Types	Authorization Code
Redirect URIs	https://pilot.owkai.app/sso/oidc/callback
Post Logout URI	https://dashboard.owkai.app/logout
Token Endpoint Auth	Client Secret (Basic or Post)

Required Scopes

Scope	Purpose	Required
openid	OIDC identity	Yes
email	User email	Yes
profile	Name, picture	Recommended
groups	Group memberships	For role mapping

Claims Mapping

Configure Claims

curl -X PUT "https://pilot.owkai.app/api/sso/oidc/company.com/claims" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "claims_mapping": {
      "email": "email",
      "firstName": "given_name",
      "lastName": "family_name",
      "groups": "groups",
      "role": "custom:ascend_role"
    }
  }'

Custom Claims

Add custom claims to your IdP's token:

Okta Example:

// Add to ID token claims
{
  "ascend_role": "admin",
  "ascend_org": "company-corp"
}

Provider-Specific Setup

Okta

1. Create new OIDC Web Application
2. Set redirect URI: https://pilot.owkai.app/sso/oidc/callback
3. Enable Authorization Code grant
4. Add groups claim to ID token

curl -X POST "https://pilot.owkai.app/api/sso/oidc/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "provider": "okta",
    "discovery_url": "https://company.okta.com/.well-known/openid-configuration",
    "client_id": "0oa...",
    "client_secret": "...",
    "scopes": ["openid", "email", "profile", "groups"]
  }'

Azure AD (Entra ID)

1. Register application in Azure AD
2. Configure redirect URI
3. Add API permissions for OpenID

curl -X POST "https://pilot.owkai.app/api/sso/oidc/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "provider": "azure",
    "tenant_id": "your-tenant-id",
    "client_id": "your-client-id",
    "client_secret": "your-secret",
    "scopes": ["openid", "email", "profile"]
  }'

Google Workspace

curl -X POST "https://pilot.owkai.app/api/sso/oidc/configure" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "domain": "company.com",
    "provider": "google",
    "client_id": "your-client-id.apps.googleusercontent.com",
    "client_secret": "your-secret",
    "hosted_domain": "company.com"
  }'

Token Validation

JWKS Configuration

ASCEND validates tokens using JWKS:

curl "https://pilot.owkai.app/api/sso/oidc/company.com/jwks-status" \
  -H "Authorization: Bearer <admin_jwt>"

Response:

{
  "jwks_uri": "https://company.okta.com/oauth2/v1/keys",
  "last_fetched": "2025-12-15T10:00:00Z",
  "keys_count": 2,
  "next_refresh": "2025-12-15T22:00:00Z"
}

Token Settings

curl -X PUT "https://pilot.owkai.app/api/sso/oidc/company.com/token-settings" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "validate_nonce": true,
    "validate_at_hash": true,
    "allowed_clock_skew_seconds": 60,
    "required_acr_values": ["urn:okta:loa:2fa:any"]
  }'

PKCE Support

Enable PKCE for enhanced security:

curl -X PUT "https://pilot.owkai.app/api/sso/oidc/company.com/pkce" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "enabled": true,
    "code_challenge_method": "S256"
  }'

Session Management

Configure Sessions

curl -X PUT "https://pilot.owkai.app/api/sso/oidc/company.com/session" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "session_duration_minutes": 480,
    "refresh_token_enabled": true,
    "refresh_token_rotation": true,
    "silent_refresh_enabled": true,
    "front_channel_logout": true
  }'

Back-Channel Logout

curl -X PUT "https://pilot.owkai.app/api/sso/oidc/company.com/logout" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "back_channel_logout_enabled": true,
    "back_channel_logout_uri": "https://pilot.owkai.app/sso/oidc/logout/company.com"
  }'

Testing

Test OIDC Flow

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

Validate Token

curl -X POST "https://pilot.owkai.app/api/sso/oidc/validate-token" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "id_token": "eyJhbGciOiJSUzI1NiI..."
  }'

Troubleshooting

Common Errors

Error	Cause	Solution
invalid_client	Wrong client credentials	Verify client ID/secret
access_denied	User not authorized	Check group assignments
invalid_scope	Scope not configured	Add scope in IdP
login_required	Session expired	Re-authenticate

Debug Mode

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

Next Steps

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

---

Document Version: 1.0.0 | Last Updated: December 2025