This guide walks you through configuring SAML 2.0 Single Sign-On (SSO) between Keycloak and Atatus.

What You Will Need

Before you begin, verify that you have:
  • An Atatus account with the Owner or Admin role.
  • Administrative access to your Keycloak Admin Console.

Step 1: Get Service Provider Values from Atatus

  1. Log in to your Atatus dashboard.
  2. Navigate to Settings » Account Settings » Single Sign-on.
  3. Keep this tab open. Copy and record the following parameters:
    • Atatus SAML ACS URL: https://app.atatus.com/login/saml/<ACCOUNT_ID>/acs
    • Atatus Account Id: Your unique 24-character alphanumeric identifier.

Step 2: Configure a Realm in Keycloak

  1. Sign in to your Keycloak Admin Console.
  2. In the top-left realm dropdown, select your existing realm or click Create Realm (for example, atatus-realm).
Keycloak Realm Selection
  1. If creating a new realm, enter a realm name and click Create.
Create Keycloak Realm

Step 3: Create and Configure a SAML Client

  1. In the left navigation pane of your realm, select Clients.
  2. Click Create client.
Create Keycloak Client
  1. On the General configuration page:
    • Client type: Select SAML.
    • Client ID: Paste your Atatus Account Id (this acts as the SAML Entity ID / Issuer).
    • Name: Enter Atatus.
  2. Click Next.
  3. On the Capability config screen, keep default settings and click Next.
  4. On the Login settings screen, configure the exact redirect URIs:
    • Home URL: Enter https://app.atatus.com.
    • Valid redirect URIs: Enter your exact Atatus SAML ACS URL (https://app.atatus.com/login/saml/<ACCOUNT_ID>/acs).
    • Master SAML Processing URL: Paste your Atatus SAML ACS URL.
Security Notice: Never configure a wildcard (*) in Valid redirect URIs. Using wildcards exposes your authentication flow to open-redirect and assertion-interception vulnerabilities. Always enter your exact Atatus ACS URL.
  1. Click Save.
Client Configuration

Step 4: Configure SAML Attribute Mappers

Atatus requires user email and name attributes in the SAML assertion. Configure client mappers in Keycloak:
  1. Within your Atatus client in Keycloak, select the Client scopes tab (or Mappers tab in older Keycloak versions).
  2. Click the dedicated scope (for example, atatus-dedicated) to manage mappers.
  3. Click Add mapper » By configuration (or Add built-in).
  4. Configure three User Attribute mappers:
  1. Click Save for each mapper.

Step 6: Assign Users in Keycloak

Ensure users requiring access to Atatus exist and are enabled in your Keycloak realm:
  1. In the left navigation, select Users.
  2. Click on a user or click Add user to create one.
  3. Verify that the user has an Email, First name, and Last name defined and Email verified set to Yes.
  4. Set credentials for the user under the Credentials tab.

Step 7: Retrieve Keycloak Metadata and Configure Atatus

  1. In the Keycloak left navigation, click Realm settings.
  2. In the General tab under Endpoints, locate SAML 2.0 Identity Provider Metadata.
  3. Right-click the link and copy the URL (the format is: https://<keycloak-host>/realms/<realm-name>/protocol/saml/descriptor). Alternatively, click the link to download the XML descriptor.
Keycloak Realm Settings Metadata
  1. Return to the Atatus dashboard under Settings » Account Settings » Single Sign-on.
  2. Under SAML Metadata from your SSO provider:
    • Choose SAML Metadata URL and paste the descriptor URL, or
    • Choose SAML Metadata XML and upload the downloaded descriptor XML file.
Atatus SSO Keycloak Configuration
  1. Click Save SSO.
  2. Confirm that the Enabled toggle switch displays active.