SSO + SAML setup (Okta, Azure AD, Keycloak)

Overview

DarkCoders CISO ships with a Keycloak SAML IdP federation already configured per tenant.

The realm customers/ accepts inbound SAML 2.0 assertions from Okta, Azure AD,

ADFS, Auth0, and PingFederate.

Prerequisites

• Tenant Enterprise plan (Pro and below use embedded Keycloak only)
• IdP admin access on your side
• Tenant ID (visible in /api/v1/v26/auth/whoami response)

Step 1 - Download SP metadata

Open: https://sso.darkcoders.com/realms/customers//protocol/saml/descriptor

This XML file contains:

• SP Entity ID
• ACS URL (POST binding)
• SLO URL
• X.509 signing cert

Step 2 - Configure IdP

Okta

1. Applications -> Create App Integration -> SAML 2.0
2. Single sign on URL: ACS URL from metadata
3. Audience URI: SP Entity ID

4. Default RelayState: blank

5. Name ID format: EmailAddress

6. Group attribute statements: groups -> Filter -> Matches regex -> .*

Azure AD

1. Enterprise applications -> New application -> Non-gallery
2. SAML basic configuration:

- Identifier: SP Entity ID

- Reply URL: ACS URL

1. Claim mapping: user.mail -> NameID, user.groups -> groups

Keycloak (federated)

1. Identity providers -> Add provider -> SAML v2.0
2. Service Provider entity ID: SP Entity ID from above
3. Single sign-on service URL: paste IdP SSO URL

4. Validate signatures: ON

Step 3 - Map roles

POST /api/v1/v26/auth/role-map:

{
  "tenant_id": "your-tid",
  "idp_group": "ciso-admins",
  "platform_role": "tenant-admin"
}

Step 4 - Test

Sign in via the customer login wizard at https://portal.darkcoders.io/login?tid=.

You should land on /dash/admin with your IdP attributes visible at /api/v1/v26/auth/whoami.

Troubleshooting

Symptom	Likely cause
401 after IdP login	Audience mismatch - check Entity ID
Empty groups[]	Claim filter too narrow
InvalidSignature	Cert rotation - re-pull SP metadata