Skip to main content

SAML 2.0 SSO

SAML 2.0 (Security Assertion Markup Language) is an XML-based open standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). When an enterprise uses Okta, Azure AD, or any SAML-capable IdP to manage employee identities, SAML lets those employees sign into your application without creating a separate password — the IdP vouches for them.

Ithbat IAM acts as a service provider. Your corporate IdP authenticates the user and sends a signed XML assertion to Ithbat. Ithbat validates that assertion, looks up or creates the corresponding user account, and issues a session token.

How SAML flows work​

SP-initiated flow (most common)​

The user attempts to access your application, which redirects them to Ithbat, which in turn redirects to the IdP for authentication.

sequenceDiagram
    participant User
    participant App as Your Application
    participant Ithbat as Ithbat IAM (SP)
    participant IdP as Corporate IdP

    User->>App: Access protected resource
    App->>Ithbat: Redirect to /auth/saml/{tenant_id}/login
    Ithbat->>Ithbat: Generate AuthnRequest + RelayState
    Ithbat->>IdP: HTTP redirect with SAMLRequest
    IdP->>User: Prompt for credentials
    User->>IdP: Submit credentials
    IdP->>IdP: Authenticate user, sign assertion
    IdP->>Ithbat: POST SAMLResponse to ACS URL
    Ithbat->>Ithbat: Validate signature, extract attributes
    Ithbat->>Ithbat: Create or update user, issue tokens
    Ithbat->>App: Return access_token + refresh_token
    App->>User: Session established

IdP-initiated flow​

The user starts from the IdP portal (e.g., the Okta app tile) and is sent directly to Ithbat's ACS endpoint without a prior AuthnRequest.

note

IdP-initiated flows carry a higher risk of replay attacks. Ithbat validates the assertion signature and NotOnOrAfter condition in both flows. RelayState is required for SP-initiated flows and validated against a server-side cache with a 10-minute TTL.

SP endpoints for your IdP​

When configuring your IdP, you need three values from Ithbat. Replace {tenant_id} with your tenant's UUID.

FieldValue
SP Entity ID (Audience URI)https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata
ACS URL (Assertion Consumer Service)https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/acs
SP Metadata URLhttps://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata
BindingHTTP-POST
NameID Formaturn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Download your tenant's SP metadata XML directly:

curl https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata

Configuring SAML in the admin console​

Option 1 — Import IdP metadata (recommended)​

  1. Go to Settings → Authentication → SAML.
  2. Click Add Connection.
  3. Paste your IdP metadata URL or upload the metadata XML file.
  4. Give the connection a name (e.g., Okta Corporate, Azure AD).
  5. Click Save. Ithbat parses the XML and extracts EntityID, SSO URL, and the signing certificate automatically.

Option 2 — Manual configuration​

If your IdP does not publish a metadata URL, configure values manually:

FieldDescription
NameA display label for this connection
Entity IDYour IdP's entity ID (issuer)
SSO URLThe IdP's SingleSignOnService endpoint
SLO URLOptional. The IdP's SingleLogoutService endpoint
CertificateThe IdP's X.509 signing certificate (PEM format, without -----BEGIN CERTIFICATE----- wrapper or with — both accepted)
NameID FormatLeave empty to use IdP default
Signing MethodLeave empty to use IdP default
EnabledToggle to activate the connection

Attribute mapping​

SAML assertions carry user attributes. Ithbat maps these to the user profile using configurable attribute names. The default mapping uses the Microsoft WS-Federation URI scheme, which works out of the box with Azure AD, Okta (when configured with Microsoft-style claims), and ADFS.

Ithbat fieldDefault SAML attribute
emailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
firstNamehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
lastNamehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
groupshttp://schemas.xmlsoap.org/claims/Group

To override the defaults, set attributeMapping when creating the config via API (see API reference below).

Provider-specific guides​

Okta​

Step 1 — Create a SAML app​

  1. In the Okta admin console, go to Applications → Applications → Create App Integration.
  2. Select SAML 2.0 and click Next.
  3. Name the app (e.g., Ithbat IAM) and click Next.

Step 2 — Configure SAML settings​

Fill in these values:

Okta fieldValue
Single sign-on URLhttps://api.ithbat.io/api/v1/auth/saml/{tenant_id}/acs
Audience URI (SP Entity ID)https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata
Name ID formatEmailAddress
Application usernameEmail

Step 3 — Add attribute statements​

Click Add Another in the Attribute Statements section and add:

NameName formatValue
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressURI Referenceuser.email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameURI Referenceuser.firstName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameURI Referenceuser.lastName

Step 4 — Retrieve metadata​

  1. Complete the wizard and go to the app's Sign On tab.
  2. Click View SAML setup instructions or copy the Metadata URL.
  3. In the Ithbat admin console, paste this URL into the Import from URL field.

Step 5 — Assign users​

Go to the app's Assignments tab and assign the users or groups who should have access.

Azure AD (Entra ID)​

Step 1 — Create an Enterprise Application​

  1. In the Azure portal, go to Entra ID → Enterprise applications → New application.
  2. Click Create your own application, name it (e.g., Ithbat IAM), and select Integrate any other application you don't find in the gallery.
  3. Click Create.

Step 2 — Configure single sign-on​

  1. Open the app, go to Single sign-on, and select SAML.
  2. Click Edit in the Basic SAML Configuration section:
FieldValue
Identifier (Entity ID)https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata
Reply URL (ACS URL)https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/acs
Sign on URLhttps://api.ithbat.io/api/v1/auth/saml/{tenant_id}/login
  1. Save.

Step 3 — Configure attribute claims​

In the Attributes & Claims section, click Edit and add:

Claim nameSource attribute
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressuser.mail
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameuser.givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameuser.surname

The Unique User Identifier (Name ID) should map to user.mail with format Email address.

Step 4 — Download metadata​

In the SAML Signing Certificate section, copy the App Federation Metadata Url. Paste it into the Ithbat admin console's metadata URL field.

Step 5 — Assign users and groups​

Under Users and groups, add the users or security groups who should have access.

Google Workspace​

Step 1 — Create a SAML app​

  1. In the Google Admin console, go to Apps → Web and mobile apps → Add App → Add custom SAML app.
  2. Name the app and click Continue.
  3. On the Google IdP Information screen, download the metadata or note the SSO URL, Entity ID, and Certificate.

Step 2 — Configure service provider details​

FieldValue
ACS URLhttps://api.ithbat.io/api/v1/auth/saml/{tenant_id}/acs
Entity IDhttps://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata
Name IDPrimary email
Name ID FormatEMAIL

Step 3 — Add attribute mapping​

In the Attribute mapping section:

Google Directory attributeApp attribute
First namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Primary emailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Step 4 — Configure in Ithbat​

In the Ithbat admin console, create a SAML connection manually using the values from Step 1: SSO URL, Entity ID, and the certificate content (Base64, PEM format).

Step 5 — Turn on for users​

In Google Admin, go to the app and click User access → ON for everyone (or specific OUs).

Testing the connection​

After saving your SAML configuration:

  1. Open a private/incognito window.
  2. Navigate to https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/login.
  3. You should be redirected to your IdP login page.
  4. Authenticate with a test account.
  5. On success, Ithbat returns an access_token and refresh_token as JSON.

If the login fails, check the Audit Logs in the admin console for the specific error reason.

Just-in-time (JIT) provisioning​

When a user authenticates via SAML for the first time, Ithbat automatically:

  1. Checks if the user's email already exists in the tenant.
  2. If yes — links the SAML identity to the existing account.
  3. If no — creates a new user account with emailVerified: true and activates it immediately.

The new user's first and last name are populated from the SAML assertion. If the assertion contains no name attributes, the email address is used as a fallback.

New JIT-provisioned users are subject to your tenant's user seat limit. If the limit is reached, the SAML login returns an error.

Troubleshooting​

"SAML not configured for this tenant"​

No active SAML configuration exists for the tenant ID in the URL. Create a configuration in Settings → Authentication → SAML and ensure Enabled is toggled on.

"Invalid or expired relay state"​

The RelayState token has expired (TTL is 10 minutes) or was already consumed. This usually means the user left the browser window open too long before completing authentication. Ask them to start the login flow again.

"Invalid SAML response: signature verification failed"​

The assertion signature does not match the configured certificate. Common causes:

  • The certificate in Ithbat is out of date — your IdP may have rotated its signing certificate. Download fresh metadata and update the configuration.
  • The IdP is signing the response rather than the assertion (or both). Check IdP signing settings.
  • The ACS URL in the assertion does not match the ACS URL in Ithbat. Both must be identical, including trailing slash.

"Email not found in SAML assertion"​

The assertion does not contain an email attribute at the configured mapping path. Verify the attribute statement names in your IdP match the attributeMapping.email value in your Ithbat configuration.

Clock skew errors​

SAML assertions include NotBefore and NotOnOrAfter timestamps. If your server clock differs from the IdP's clock by more than a few minutes, assertions will be rejected. Ensure both servers are syncing from an NTP source.

"Tenant is not active"​

The tenant has been suspended. Contact your Ithbat platform administrator.

API reference​

All SAML management endpoints require a valid bearer token with settings:read or settings:write permission, plus the X-Tenant-ID header.

List SAML configurations​

GET /api/v1/tenant/saml/configs
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

Get a SAML configuration​

GET /api/v1/tenant/saml/configs/{id}
Authorization: Bearer {token}

Create a SAML configuration​

POST /api/v1/tenant/saml/configs
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "name": "Okta Corporate",
  "entityId": "http://www.okta.com/exkABC123",
  "ssoUrl": "https://company.okta.com/app/saml/exkABC123/sso/saml",
  "sloUrl": "https://company.okta.com/app/saml/exkABC123/slo/saml",
  "certificate": "MIIC...base64...==",
  "nameIdFormat": "",
  "signingMethod": "",
  "attributeMapping": {
    "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.xmlsoap.org/claims/Group"
  },
  "enabled": true
}

Import from metadata URL or XML​

POST /api/v1/tenant/saml/configs/import-metadata
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "name": "Azure AD",
  "metadataUrl": "https://login.microsoftonline.com/{directory_id}/federationmetadata/2007-06/federationmetadata.xml"
}

Or import raw XML:

POST /api/v1/tenant/saml/configs/import-metadata
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "name": "Google Workspace",
  "metadataXml": "<?xml version=\"1.0\"?>..."
}

Update a SAML configuration​

PUT /api/v1/tenant/saml/configs/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Okta Corporate",
  "enabled": false
}

Delete a SAML configuration​

DELETE /api/v1/tenant/saml/configs/{id}
Authorization: Bearer {token}

Get SP metadata (public, no auth required)​

GET /api/v1/auth/saml/{tenant_id}/metadata

Returns XML.

Next steps​