SAML 2.0 SSO

ChainLaunch Pro is a SAML 2.0 Service Provider (SP) that integrates with any compliant Identity Provider (IdP). Use SAML when your organization standardizes on it (common with ADFS, legacy enterprise IdPs) or when OIDC isn't an option. Both protocols share the same role-mapping rules and first-login policies, so an admin only configures provisioning logic once.

This page walks through:

1. How the flow works (so you can debug it).
2. Generating SP credentials and registering ChainLaunch with your IdP.
3. Per-IdP setup (Okta, Microsoft Entra ID / Azure AD, Keycloak, ADFS, Auth0).
4. Mapping SAML attributes to ChainLaunch roles.
5. First-login policies.
6. Single Logout (SLO).
7. Troubleshooting and security checklist.

How the SAML flow works

ChainLaunch implements SP-initiated SAML with optional IdP-initiated support.

User → ChainLaunch login page
     → 302 redirect to IdP with signed AuthnRequest
     → User authenticates at IdP
     → IdP POSTs signed SAMLResponse to ChainLaunch ACS
     → ChainLaunch verifies signature, audience, conditions, replay
     → ChainLaunch maps assertion → user/role → session cookie
     → Redirect to original RelayState

Under the hood ChainLaunch uses the crewjam/saml library to handle XML signing, signature verification, audience checking, and replay prevention. ChainLaunch never rolls its own SAML crypto.

Step 1 — Generate SP credentials

Each SAML provider in ChainLaunch needs an SP signing keypair (RSA, PKCS#8 or PKCS#1 PEM). The private key signs AuthnRequests and decrypts encrypted assertions. The certificate is published in the SP metadata so the IdP can verify your requests.

Generate one with OpenSSL:

openssl req -x509 -newkey rsa:2048 -keyout sp-key.pem -out sp-cert.pem \
  -days 1095 -nodes \
  -subj "/CN=chainlaunch-sp/O=YourCompany"

Or mint one from the ChainLaunch admin UI: Settings → SSO → Add Provider → SAML → Generate keypair. The private key is encrypted with the master encryption key (see Encryption at rest) before being written to the database — it is never stored in plaintext.

Step 2 — Configure the provider in ChainLaunch

Open Settings → SSO → Add Provider → SAML and fill in:

After saving, ChainLaunch publishes the SP metadata at:

GET https://chainlaunch.example.com/api/v1/sso/saml/{providerId}/metadata

Hand this URL (or download the XML) to your IdP admin.

Step 3 — Configure your IdP

Okta

1. Okta Admin → Applications → Create App Integration → SAML 2.0.
2. General Settings: name ChainLaunch.
3. Configure SAML:
   • Single sign-on URL: https://chainlaunch.example.com/api/v1/sso/saml/{providerId}/acs
   • Audience URI (SP Entity ID): same value you set in ChainLaunch.
   • Name ID format: EmailAddress
   • Application username: Email
4. Attribute Statements — add the attributes ChainLaunch reads:

   Name	Format	Value
   email	Basic	user.email
   displayName	Basic	user.displayName
   groups	Basic	filter: matches regex chainlaunch-.*

5. Finish, then on the app's Sign On tab copy the Identity Provider metadata URL and paste it into the ChainLaunch provider's IdP Metadata URL field.
6. Assign users/groups to the app.

Microsoft Entra ID (Azure AD)

1. Entra Admin Center → Enterprise applications → New application → Create your own application → "Non-gallery".
2. Single sign-on → SAML.
3. Basic SAML Configuration:
   • Identifier (Entity ID): same as ChainLaunch.
   • Reply URL (ACS): your ACS URL.
   • Sign-on URL: https://chainlaunch.example.com/login.
4. Attributes & Claims — confirm emailaddress is user.mail. Add a groups claim → "Groups assigned to the application" → "sAMAccountName" or "Group ID" depending on your tenant.
5. Download App Federation Metadata URL and paste into ChainLaunch.
6. Assign users/groups under Users and groups.

Keycloak

1. Keycloak Admin → realm → Clients → Create client → SAML.
2. Client ID: your ChainLaunch entity ID.
3. Settings:
   • Valid redirect URIs: https://chainlaunch.example.com/*
   • IDP-Initiated SSO URL name: chainlaunch (optional).
   • Master SAML Processing URL: your ACS URL.
   • Sign assertions: ON.
   • Client signature required: ON (matches the cert you generated).
4. Keys tab → import your SP cert.
5. Client scopes → role list → Add mapper → Group Membership → name groups, attribute groups, full path OFF.
6. Realm settings → SAML 2.0 Identity Provider Metadata — copy the URL into ChainLaunch.

ADFS

1. AD FS Management → Add Relying Party Trust → Claims aware → Import data about the relying party from a file (the SP metadata you downloaded from ChainLaunch).
2. Issuance Transform Rules — add a rule for each attribute ChainLaunch needs (email, displayName, groups). Use Send LDAP Attributes as Claims (or Send Group Membership as a Claim for groups).
3. Export your federation metadata: https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml and paste into ChainLaunch.

Auth0

1. Auth0 Dashboard → Applications → Create Application → Regular Web Application.
2. Addons → SAML2 Web App → enable.
3. Application Callback URL: your ACS URL.
4. Settings JSON — set nameIdentifierFormat, ensure mappings produces email, displayName, and groups claims.
5. Download metadata from the Usage tab → paste URL into ChainLaunch.

Step 4 — Attribute & role mapping

ChainLaunch reads the following SAML attributes (case-insensitive, and both Name and FriendlyName are matched):

Subject comes from <Subject><NameID>. ChainLaunch uses it as the stable identity key — even if the email changes later, the same NameID always resolves to the same user.

Role mapping rules

Role mapping uses the same sso_role_mappings table as OIDC. From Settings → SSO → (your provider) → Role Mappings, define ordered rules:

Rules are evaluated in order, first match wins. Use * as a catch-all if you want every authenticated user to receive at least VIEWER access.

If no rule matches, ChainLaunch:

1. Tries the optional RoleAttribute (a single SAML attribute holding a literal role name like ADMIN/OPERATOR/VIEWER).
2. Falls back to the provider's DefaultRole.
3. Falls back to VIEWER.

Step 5 — First-login policy

When a user authenticates for the first time and no existing local user matches their NameID or email, the configured FirstLoginPolicy decides what happens:

For high-trust environments paired with SCIM provisioning, set policy to reject so users must be created via SCIM before they can log in.

Single Logout (SLO)

When a SAML provider's metadata advertises a SingleLogoutService endpoint, the ChainLaunch logout button redirects the browser there after invalidating the local session. ChainLaunch does not currently produce a signed LogoutRequest — the browser hits the IdP's SLO URL and the IdP terminates its own session. For most IdPs this is sufficient.

Endpoint:

GET /api/v1/sso/saml/{providerId}/slo

Verifying the integration

# Fetch SP metadata
curl -s https://chainlaunch.example.com/api/v1/sso/saml/1/metadata | xmllint --format -
 
# Trigger SP-initiated login (open in a browser)
open "https://chainlaunch.example.com/api/v1/sso/saml/1/login"
 
# Inspect the audit log for SAML events
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://chainlaunch.example.com/api/v1/audit/sso?provider=saml&limit=20" | jq

Successful flows append login_success and (for new users) user_provisioned events to the SSO audit log — see Audit Logging.

Troubleshooting

Use Settings → SSO → (your provider) → Reload metadata to bust ChainLaunch's metadata cache after rotating IdP keys.

Security checklist

• SP private key is never committed to source control. ChainLaunch encrypts it at rest with the master key.
• IdP metadata URL is HTTPS only. Self-signed metadata endpoints are rejected.
• Disable local auth once SAML is verified working: CHAINLAUNCH_LOCAL_AUTH_DISABLED=true. Always keep one local admin for break-glass.
• Rotate SP cert before its NotAfter date. Coordinate with the IdP admin so they re-trust the new cert in the same change window.
• Set FirstLoginPolicy=reject and pair with SCIM when you want full lifecycle control (deprovisioning included).
• All SAML login attempts are recorded in the audit log — review periodically.

Next steps

• SCIM Provisioning — automate user/group lifecycle from your IdP.
• SSO / OIDC Integration — alternative protocol with the same role-mapping rules.
• RBAC & Permissions — what each role can actually do.
• Audit Logging — review SSO and admin activity.