SAML 2.0 SSO Guide

Overview

Rakomi acts as a SAML 2.0 Service Provider (SP). Your enterprise IdP (Okta, Azure AD, Google Workspace, OneLogin) authenticates users and sends signed SAML Assertions to Rakomi’s ACS endpoint. Rakomi validates the assertion, provisions the user via JIT (Just-in-Time) if needed, and creates a Rakomi session.

End-User Browser
      │
      │  1. GET /saml/init/:connectionId
      ▼
  Rakomi (SP)
      │  2. Signs AuthnRequest → 302 redirect
      ▼
  Enterprise IdP (Okta / Azure AD / etc.)
      │  3. User authenticates
      │  4. POST /saml/acs  (SAMLResponse + RelayState)
      ▼
  Rakomi (SP)
      │  5. Validates signature, audience, replay protection
      │  6. JIT-provisions user if new
      │  7. Creates session → 302 to dashboard
      ▼
  End-User Browser (authenticated)

SP Endpoints

Endpoint	Purpose
GET /saml/metadata	SP metadata XML — give this URL to IdP admin
GET /saml/init/:connectionId	Initiates SP-initiated SSO flow
POST /saml/acs	Assertion Consumer Service — receives SAML Response from IdP

Note

The ACS URL must be configured in your IdP exactly as shown in the SP metadata. A trailing-slash mismatch will cause signature verification failure.

SP Metadata

Every IdP requires your SP metadata to set up the trust relationship. Provide the IdP admin with:

• Metadata URL: {SAML_SP_ENTITY_ID}/saml/metadata
• ACS URL (from metadata): matches SAML_ACS_URL in your Rakomi deployment config
• Entity ID: matches SAML_SP_ENTITY_ID in your Rakomi deployment config
• NameID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (preferred)

The metadata URL is static and permanent — safe to whitelist in your IdP.

Okta Setup

1. In Okta Admin Console, go to Applications → Create App Integration → SAML 2.0.

2. General Settings: Enter your app name.

3. Configure SAML:

   • Single sign-on URL (ACS URL): paste from SP metadata
   • Audience URI (SP Entity ID): paste from SP metadata
   • NameID format: EmailAddress
   • Application username: Email

4. Attribute Statements — add these mappings:

   Name	Value
   email	user.email
   givenName	user.firstName
   sn	user.lastName

5. Finish and download the IdP metadata XML. Use it to create a SAML connection in the Rakomi dashboard.

6. Enable Sign AuthnRequest if your Okta policy requires signed requests.

Azure AD (Entra ID) Setup

1. In Entra ID, go to Enterprise Applications → New application → Create your own application.

2. Select Integrate any other application you don’t find in the gallery (Non-gallery).

3. Go to Single sign-on → SAML:

   • Basic SAML Configuration:
     • Identifier (Entity ID): paste from SP metadata
     • Reply URL (ACS URL): paste from SP metadata

4. Attributes & Claims — the following are sent by default:

   Claim name	Value
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	user.mail
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	user.givenname
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	user.surname

5. Download the Certificate (Base64) and the App Federation Metadata URL.

6. Create a SAML connection in Rakomi using the IdP metadata URL or the downloaded certificate.

Caution

Azure AD group memberships are sent as object GUIDs (e.g. d4e91b93-7df5-4a3c-...), not human-readable names. Store them as-is; resolve to display names via Graph API when needed.

Attribute Mapping

Rakomi supports custom attribute mapping per connection. Default attribute names are tried in order:

Field	Default attribute names tried
email	email, mail, http://schemas.xmlsoap.org/.../emailaddress
firstName	givenName, firstName, http://schemas.xmlsoap.org/.../givenname
lastName	sn, surname, lastName, http://schemas.xmlsoap.org/.../surname
groups	groups, memberOf, http://schemas.microsoft.com/.../groups

Email is normalized to lowercase and trimmed. A missing email attribute causes a saml/missing_email 400 error.

IdP-Initiated SSO

By default, IdP-initiated SSO (unsolicited SAML Response with no prior AuthnRequest) is disabled per OWASP recommendation. Enable it per connection via settings.idp_initiated_sso: true.

Caution

IdP-initiated SSO bypasses the AuthnRequest/InResponseTo binding. Only enable it for IdPs that cannot support SP-initiated flow.

IdP Certificate Rotation

To rotate the IdP signing certificate without downtime:

1. Add the new certificate to idp_config.certificates array (keep the old one too).

2. Verify the SAML flow works with the new certificate (ask IdP admin to sign with new key).

3. Remove the old certificate from idp_config.certificates.

Rakomi validates the SAML Response against all certificates in the array — this allows zero-downtime rotation.

Email Trust

Setting	Behavior
provider_verified (default)	Email from IdP is trusted as verified. Enables email-based account linking.
never_trust	Email is used only for display. No cross-flow account linking by email.

Caution

Using provider_verified means you trust the IdP to verify user emails. Use never_trust if the IdP is not under your control or may send unverified emails.

SHA-1 Legacy Support

RSA-SHA1 signatures are rejected by default (CVE-2025-54419 mitigation). Per-connection opt-in:

{
  "settings": {
    "algorithm_policy": { "legacy_sha1": true }
  }
}

Caution

SHA-1 is cryptographically broken. Only enable for legacy IdPs that cannot upgrade to SHA-256. Log a warning is emitted automatically when SHA-1 is used.

Encrypted Assertions (NIST SP 800-63C FAL2)

Rakomi supports <EncryptedAssertion> using the SP private key (SAML_SP_PRIVATE_KEY). When your IdP is configured to encrypt assertions:

• AES-256-GCM is preferred
• AES-128-GCM is accepted
• AES-CBC is accepted with a warning log (configure your IdP to use AES-GCM)
• 3DES-CBC and RSA-PKCS#1 v1.5 are rejected

Encrypted assertions achieve NIST SP 800-63C FAL2 (signed + encrypted).

Common Errors

Error code	Cause	Fix
saml/connection_not_found	Entity ID mismatch or connection not active	Verify idp_config.entity_id matches the Issuer in IdP’s SAML Response
saml/missing_email	IdP is not sending the email attribute	Add email attribute mapping in IdP
saml/replay_detected	Same assertion submitted twice	Normal for retry attacks — investigate if seen in legitimate flows
saml/invalid_relay_state	RelayState HMAC mismatch	Relay state was tampered with or expired (>10 min)
saml/invalid_audience	AudienceRestriction ≠ SP Entity ID	Verify the SP Entity ID in IdP matches SAML_SP_ENTITY_ID
saml/invalid_issuer	Issuer element ≠ idp_config.entity_id	Check that the connection’s entity_id matches the IdP’s entity ID exactly
saml/idp_initiated_not_allowed	IdP sent unsolicited Response but idp_initiated_sso: false	Enable idp_initiated_sso in connection settings or use SP-initiated flow