> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On (SSO) with SAML 2.0

> Configure SAML 2.0-based Single Sign-On and SCIM provisioning for secure, centralized authentication in Elementum

## Overview

Single Sign-On (SSO) via SAML 2.0 allows your organization to manage user authentication through your existing Identity Provider (IdP), such as Okta, Azure AD, Google Workspace, or OneLogin. This centralizes user access control, improves security, and streamlines the login experience.

Once configured, users can sign in to Elementum using their organization credentials, and you can enforce SSO-only authentication to ensure all access goes through your IdP. For organizations that need automated user and group provisioning, Elementum also supports [SCIM](#scim-provisioning) to keep accounts in sync with your IdP.

## How Users Are Provisioned

How users land in Elementum -- and how they leave -- depends on whether you use SSO alone or pair it with SCIM.

### SSO Only

When SSO is enabled without SCIM:

* **First-login creation** -- With [Auto Create Unknown Users](#step-4-configure-saml-in-elementum) enabled, Elementum creates the user account the first time someone authenticates via your IdP. No record exists in Elementum until that first login.
* **Manual pre-creation** -- If you need a user to exist in Elementum before their first SSO login -- for example, to @-mention them, assign them to a record, or add them to a group in advance -- create them manually from [Org Settings → Groups](/administration/users#invite-a-user-through-a-group) or [Org Settings → Users](/administration/users#invite-a-user-directly). On their first SSO login they are matched to the existing account by email.
* **Removal does not deactivate** -- If you remove a user from your IdP, they can no longer authenticate, but their Elementum account continues to display as **Active**. Manually [deactivate the user](/administration/users#user-status) to reflect the change in Elementum. Their history is preserved either way.

### SSO with SCIM

When SSO is paired with [SCIM provisioning](#scim-provisioning):

* **Pre-login creation** -- SCIM syncs users from your IdP into Elementum on a schedule, so accounts exist in Elementum before the user's first login. You can mention, assign, and add them to groups immediately.
* **Profile and group sync** -- Profile changes (name, job title) and group membership push from your IdP to Elementum without manual intervention.
* **Automatic deactivation** -- When a user is removed from your IdP -- or unassigned from the SCIM application -- SCIM deactivates them in Elementum, provided your IdP's SCIM application is configured to send deactivation events.

<Tip>
  If you need every user to exist in Elementum before they can log in -- and you want IdP changes to flow through automatically -- use SCIM. SSO alone is simpler to configure but leaves user lifecycle and deactivation as manual operations.
</Tip>

## Prerequisites

Before configuring SAML SSO, ensure you have:

* **Elementum permissions**: Organization Admin access
* **IdP access**: Administrator access to your Identity Provider (Okta, Azure AD, Google Workspace, OneLogin, etc.)
* **IdP configuration details**:
  * SSO URL from your IdP
  * Issuer/Entity ID from your IdP
  * X.509 signing certificate from your IdP
* **User attributes**: Ensure your IdP sends `firstName` and `lastName` attributes in SAML assertions (and optionally `jobTitle` for job title syncing)

<Tip>
  Elementum provides Service Provider (SP) metadata URLs that your IdP will need. These are displayed in the configuration interface and include the Assertion Consumer Service (ACS) URL and Audience URI.
</Tip>

## Configuration Steps

### Step 1: Navigate to SSO Settings

1. Log into Elementum as an Organization Admin
2. Navigate to **Organization Settings**
3. Select the **Single Sign-On** tab
4. Locate the **SAML Configuration** section

### Step 2: Gather Elementum SP Metadata

Before configuring your IdP, you'll need the Service Provider information from Elementum:

1. Copy the **Assertion Consumer Service URL**
   * Example: `https://se.elementum.io/api/v1/saml/callback`
   * This is where your IdP will send SAML responses

2. Copy the **Audience URI (SP Entity ID)**
   * Example: `https://se.elementum.io/api/v1/saml/metadata`
   * This uniquely identifies your Elementum instance to your IdP

<Info>
  Keep these URLs handy - you'll need to enter them into your Identity Provider configuration in the next step.
</Info>

### Step 3: Configure Your Identity Provider

Configure a new SAML application in your Identity Provider. While specific steps vary by provider, you'll typically need to:

<Tabs>
  <Tab title="Okta">
    1. In Okta Admin Console, go to **Applications** → **Create App Integration**
    2. Select **SAML 2.0** and click **Next**
    3. Enter application name (e.g., "Elementum")
    4. Configure SAML settings:
       * **Single sign on URL**: Paste your Elementum ACS URL
       * **Audience URI**: Paste your Elementum Audience URI
       * **Name ID format**: EmailAddress
       * **Application username**: Email
    5. Add attribute statements:
       * `firstName` → `user.firstName`
       * `lastName` → `user.lastName`
       * `jobTitle` → `user.title` (optional)
    6. Click **Next** and complete setup
    7. Navigate to **Sign On** tab and click **View SAML setup instructions**
    8. Copy the **Identity Provider Single Sign-On URL**, **Identity Provider Issuer**, and download the **X.509 Certificate**
  </Tab>

  <Tab title="Azure AD / Entra ID">
    1. In Azure Portal, go to **Azure Active Directory** → **Enterprise Applications**
    2. Click **New application** → **Create your own application**
    3. Enter name (e.g., "Elementum") and select **Integrate any other application you don't find in the gallery (Non-gallery)**
    4. Go to **Single sign-on** → Select **SAML**
    5. Edit **Basic SAML Configuration**:
       * **Identifier (Entity ID)**: Paste your Elementum Audience URI (SP Entity ID)
       * **Reply URL (Assertion Consumer Service URL)**: Paste your Elementum ACS URL
    6. Edit **Attributes & Claims**:
       * **Unique User Identifier (Name ID)**: Select `user.mail` (if using email for Identity Connection)
         * If not using email, select **Persistent** in the Name Identifier Format field
       * Add Additional Claims (ensure you **remove the NameSpace values** or the integration will fail):
         * `firstName` → `user.givenname`
         * `lastName` → `user.surname`
         * `jobTitle` → `user.jobtitle` (optional)
         * `Email` → `user.mail`
    7. In **SAML Certificates** section, download **Certificate (Base64)**
    8. In **Set up Elementum** section:
       * Copy the **Login URL**
       * Copy the **Azure AD Identifier**
  </Tab>

  <Tab title="Google Workspace">
    1. In Google Admin Console, go to **Apps** → **Web and mobile apps**
    2. Click **Add app** → **Add custom SAML app**
    3. Enter app name (e.g., "Elementum") and click **Continue**
    4. On the **Google Identity Provider details** page:
       * Copy the **SSO URL**
       * Copy the **Entity ID**
       * Download the **Certificate**
       * Click **Continue**
    5. Configure Service Provider Details:
       * **ACS URL**: Paste your Elementum ACS URL
       * **Entity ID**: Paste your Elementum Audience URI
       * **Name ID format**: EMAIL
       * Click **Continue**
    6. Add attribute mapping:
       * `firstName` → Basic Information → First Name
       * `lastName` → Basic Information → Last Name
       * `jobTitle` → Basic Information → Job Title (optional)
    7. Click **Finish**
  </Tab>

  <Tab title="OneLogin">
    1. In OneLogin portal, go to **Applications** → **Add App**
    2. Search for "SAML Custom Connector (Advanced)" and select it
    3. Enter display name (e.g., "Elementum") and save
    4. Go to **Configuration** tab:
       * **Audience (Entity ID)**: Paste your Elementum Audience URI
       * **ACS (Consumer) URL**: Paste your Elementum ACS URL
       * **ACS (Consumer) URL Validator**: `^https://se\.elementum\.io/api/v1/saml/callback$`
    5. Go to **Parameters** tab and add custom fields:
       * `firstName` → First Name
       * `lastName` → Last Name
       * `jobTitle` → Title (optional)
    6. Go to **SSO** tab:
       * Copy the **SAML 2.0 Endpoint (HTTP)**
       * Copy the **Issuer URL**
       * Click **View Details** under X.509 Certificate and copy the certificate
    7. Save and assign users
  </Tab>

  <Tab title="JumpCloud">
    1. In JumpCloud Admin Portal, go to **SSO** → **Applications**
    2. Click the **+** button to add a new application
    3. Select **Custom SAML App**
    4. Configure general info:
       * **Display Label**: Enter "Elementum"
    5. Click **Next** and configure **SSO** settings:
       * **IdP Entity ID**: Enter `JumpCloud`
       * **SP Entity ID**: Paste your Elementum Audience URI (SP Entity ID)
       * **ACS URL**: Paste your Elementum Assertion Consumer Service URL
       * **SAMLSubject NameID**: Select `email`
       * **SAMLSubject NameID Format**: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
    6. Configure **Attribute Mapping**:
       * Add attribute: `firstName` → `firstname`
       * Add attribute: `lastName` → `lastname`
       * (Optional) Add attribute: `jobTitle` → `jobTitle` if available in user profiles
    7. Click **Activate** to save the application
    8. On the SSO configuration page, copy the following:
       * **IdP URL** (e.g., `https://sso.jumpcloud.com/saml2/elementum`)
       * Download the **X.509 Certificate**
    9. Assign users or user groups to the application
  </Tab>
</Tabs>

<Note>
  The exact field names and navigation may vary depending on your IdP version. Consult your IdP's documentation if you need specific guidance.
</Note>

### Step 4: Configure SAML in Elementum

Return to Elementum's SSO configuration page and enter the information from your Identity Provider:

1. **Enable SAML Authentication**
   * Toggle the **Enable** switch to activate SAML

2. **Identity Provider SSO URL**
   * Paste the SSO/Login URL from your IdP
   * This is where Elementum redirects users for authentication

3. **Identity Provider Issuer**
   * Paste the Issuer/Entity ID from your IdP
   * This identifies your IdP in SAML exchanges

4. **Identity Connection**
   * Select **Email** from the dropdown
   * This maps IdP users to Elementum users via email address

5. **Identity Provider X.509 Certificate**
   * Paste the complete X.509 certificate from your IdP
   * Include the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` headers
   * Remove any extra whitespace or line breaks that may cause issues

6. **Configure Inactive User Logout** (optional but recommended)
   * **Desktop Users**: Set hours of inactivity before automatic logout (default: 24 hours)
   * **Mobile Users**: Set days of inactivity before automatic logout (default: 30 days)

7. **Auto Create Unknown Users** (optional)
   * Enable this toggle if you want Elementum to automatically create user accounts when someone authenticates via SSO for the first time
   * Requires `firstName` and `lastName` attributes in the SAML assertion
   * If enabled and `jobTitle` is provided, the user's job title will also sync

8. Click **Save** to apply the configuration

<Warning>
  **Do not enable "Enforce SSO-only authentication" yet.** Test SSO thoroughly first to ensure it works correctly before enforcing it organization-wide.
</Warning>

### Step 5: Test SSO Authentication

Before enforcing SSO, verify it works correctly:

1. **Open an incognito/private browser window**
   * This ensures you're testing a fresh login flow

2. **Navigate to your Elementum login page**
   * You should now see a **Sign in with SSO** button

3. **Click "Sign in with SSO"**
   * You'll be redirected to your IdP's login page

4. **Log in with your organization credentials**
   * Enter your IdP username and password

5. **Verify successful authentication**
   * You should be redirected back to Elementum and logged in
   * Confirm your user profile shows correct information (name, email, job title if configured)

6. **Test with multiple users**
   * Have several team members test the SSO flow
   * Verify different user roles authenticate correctly

<AccordionGroup>
  <Accordion title="Testing Auto Create Unknown Users">
    If you enabled **Auto Create Unknown Users**:

    1. Have a user who doesn't yet exist in Elementum attempt to log in via SSO
    2. Verify they can successfully authenticate
    3. Check that their user account was automatically created
    4. Confirm their profile contains:
       * Email address (from SAML NameID)
       * First and last name (from SAML attributes)
       * Job title (if configured in SAML attributes)
    5. Assign appropriate roles and permissions to the new user

    <Tip>
      Auto-created users will have minimal default permissions. Ensure you have a process to assign proper roles after their first login.
    </Tip>
  </Accordion>

  <Accordion title="Testing Identity Connection Mapping">
    The **Identity Connection** setting determines how Elementum matches IdP users to existing accounts:

    * **Email**: Matches users based on email address (recommended)
    * This means the email in your IdP must match the email in Elementum

    To verify:

    1. Check that the SAML NameID or email attribute matches existing Elementum user emails
    2. Test login with users who have accounts
    3. Verify they log into their existing accounts (not new ones)
  </Accordion>
</AccordionGroup>

### Step 6: Enforce SSO-Only Authentication (Optional)

Once you've thoroughly tested SSO and confirmed it works for all users:

1. Return to **Organization Settings** → **Single Sign-On**
2. Enable the **Enforce SSO-only authentication** toggle
3. Click **Save**

<Warning>
  **Critical**: Once enabled, users will **only** be able to log in via SSO. Standard username/password authentication will be disabled. Ensure all users can access SSO before enforcing this setting.
</Warning>

<Info>
  Even with SSO enforcement enabled, Organization Admins can access a backup login method in case of IdP issues. Contact Elementum support for emergency access procedures.
</Info>

## Local Password Policy

For users who are not on SSO or before SSO is enforced organization-wide, passwords must meet these requirements:

* **Minimum length**: 12 characters
* **Complexity** (must contain at least one of each):
  * Lowercase character (a-z)
  * Uppercase character (A-Z)
  * Number (0-9)
  * Symbol (e.g., `!@#$%^&*()_+-=[]{}|;:'",.<>?`)
* **Restrictions**:
  * May not contain the user's name
  * May not contain the user's email address

<Tip>
  Once SSO is enforced, these local password requirements no longer apply as all authentication goes through your Identity Provider.
</Tip>

## User Experience

### End User Login Experience

The login experience varies depending on your SSO configuration:

<Tabs>
  <Tab title="SSO Enabled (Not Enforced)">
    **What users see:**

    The login page displays a split interface giving users two options:

    1. **Top Section: "Log In With Email"**
       * Traditional username/password login
       * Available for users with local accounts
       * Subject to local password policy requirements

    2. **Bottom Section: "Log In With Single Sign On"**
       * Clickable button that redirects to your IdP
       * Users authenticate using their organization credentials
       * Recommended for all organization users

    **Use case**: This configuration is ideal during the SSO testing and migration period, allowing users to choose their authentication method while you verify SSO works correctly.
  </Tab>

  <Tab title="SSO Enforced">
    **What users see:**

    The traditional "Log In With Email" section is removed, and users see:

    1. **Single email input field**
       * Users enter their email address
       * No password field is shown

    2. **Automatic redirect on login**
       * Upon clicking "Log In", the system detects the user's domain
       * Users are immediately redirected to the IdP for authentication
       * No local password authentication available

    3. **Seamless experience**
       * If users are already authenticated with your IdP, they may be logged in automatically
       * Single sign-on across all applications

    **Use case**: This configuration is recommended once SSO testing is complete and you want to enforce centralized authentication for all users.
  </Tab>
</Tabs>

### Session Management

Session timeouts are configured in Step 4 under **Configure Inactive User Logout** and apply regardless of SSO enforcement. If users are already logged into your IdP, they may experience automatic single sign-on without re-entering credentials.

## Security Best Practices

* Enable SSO enforcement after successful testing
* Configure automatic logout for inactive sessions
* Regularly rotate your X.509 certificates
* Enable Multi-Factor Authentication (MFA) in your IdP
* Use Auto Create Unknown Users only if you have proper onboarding processes
* Regularly audit user access in both your IdP and Elementum
* Monitor failed SSO authentication attempts
* Document your SSO configuration for your IT team

### Certificate Management

* **Validity**: X.509 certificates typically expire after 1-3 years
* **Rotation**: When your IdP issues a new certificate:
  1. Download the new certificate from your IdP
  2. Update it in Elementum SSO settings before the old one expires
  3. Test authentication to confirm the update worked
* **Monitoring**: Set calendar reminders to check certificate expiration

### User Provisioning

<Tabs>
  <Tab title="With Auto Create Enabled">
    **Pros:**

    * New users can access Elementum immediately
    * No manual account creation required
    * Scales easily for large organizations

    **Cons:**

    * Users created with default minimal permissions
    * Requires post-login role assignment process
    * May create accounts for users who shouldn't have access

    **Best for:** Organizations with automated onboarding workflows and clear role assignment processes
  </Tab>

  <Tab title="Without Auto Create">
    **Pros:**

    * Full control over who has access
    * Pre-configured roles and permissions
    * No surprise account creation

    **Cons:**

    * Manual account setup required
    * User must be created before first SSO login
    * Doesn't scale as easily

    **Best for:** Organizations preferring explicit user provisioning and tighter access control
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="SSO button doesn't appear on login page">
    **Cause**: SAML may not be enabled or configuration hasn't been saved

    **Solution**:

    1. Verify the **Enable** toggle is turned on
    2. Ensure you clicked **Save** after configuration
    3. Try clearing your browser cache
    4. Try a different browser or incognito mode
  </Accordion>

  <Accordion title="Redirected to IdP but authentication fails">
    **Cause**: Incorrect IdP configuration or user not assigned to the application

    **Solution**:

    1. Verify the user is assigned to the Elementum app in your IdP
    2. Check that the IdP application is active/enabled
    3. Confirm the SSO URL and Issuer are correct in Elementum
    4. Verify required attributes (`firstName`, `lastName`) are configured in your IdP
  </Accordion>

  <Accordion title="Authentication succeeds but returns error in Elementum">
    **Cause**: Certificate mismatch, incorrect ACS URL, or missing required attributes

    **Solution**:

    1. Verify the X.509 certificate is correctly copied (including headers)
    2. Confirm the ACS URL in your IdP matches exactly what Elementum provided
    3. Check that your IdP sends required SAML attributes (`firstName`, `lastName`)
    4. Review browser developer console and network tab for specific error messages
    5. Contact Elementum support with error details
  </Accordion>

  <Accordion title="Existing users can't log in after enabling SSO">
    **Cause**: Email mismatch between IdP and Elementum, or Identity Connection misconfigured

    **Solution**:

    1. Verify **Identity Connection** is set to **Email**
    2. Confirm user emails in Elementum match emails in your IdP exactly
    3. Check that IdP sends email in SAML NameID or as an attribute
    4. Temporarily disable SSO enforcement to allow testing
  </Accordion>

  <Accordion title="New users aren't being created automatically">
    **Cause**: Auto Create Unknown Users is disabled, or required attributes are missing

    **Solution**:

    1. Verify **Auto Create Unknown Users** toggle is enabled
    2. Confirm your IdP sends `firstName` and `lastName` attributes in SAML assertions
    3. Check attribute name spelling matches exactly (case-sensitive)
    4. Review IdP logs to see what attributes are being sent
  </Accordion>

  <Accordion title="Certificate or configuration errors">
    **Cause**: Malformed certificate, expired certificate, or whitespace issues

    **Solution**:

    1. Verify certificate includes begin/end markers:
       ```
       -----BEGIN CERTIFICATE-----
       [certificate content]
       -----END CERTIFICATE-----
       ```
    2. Remove any extra spaces or line breaks
    3. Check certificate hasn't expired in your IdP
    4. Download a fresh certificate from your IdP
    5. Use a text editor (not Word) to copy/paste the certificate
  </Accordion>

  <Accordion title="User data isn't updating or looks incorrect">
    **Cause**: SAML claims from IdP are overwriting Elementum user data

    **Solution**:

    * Claims sent by the IdP take precedence and will overwrite user-defined parameters in Elementum (such as Name, Last Name, and Job Title)
    * Update the values in your IdP user profiles instead of in Elementum
    * Verify the correct attributes are being mapped in your IdP configuration
    * Check IdP logs to confirm what values are being sent
  </Accordion>

  <Accordion title="Infinite redirect loop or being sent back to login page">
    **Cause**: Configuration mismatch between IdP and Elementum

    **Solution**:
    Check these three common issues:

    1. **URL Configuration**: Ensure the ACS URL and Entity ID are not inverted or swapped
    2. **Unique Identifier**: Verify the unique identifier (Name ID) is set to the user's email address
    3. **Required Claims**: Ensure all required claims (`firstName`, `lastName`, `email`) are being sent and properly formatted
    4. Clear browser cookies and try in an incognito window
    5. Check browser developer console for specific error messages
  </Accordion>

  <Accordion title="Job title is not populating in user profiles">
    **Cause**: Missing or incorrectly named `jobTitle` attribute.

    **Solution**:

    1. Verify the `jobTitle` attribute is configured in your IdP
    2. Check that the attribute name is exactly `jobTitle` (case-sensitive) — sending `JobTitle` instead is a common mistake
    3. Verify the IdP user profile contains job title data to send
    4. Test with a user who has a job title populated in the IdP
  </Accordion>

  <Accordion title="Still having issues? Getting help">
    If you continue experiencing issues after reviewing the items above:

    1. **Gather diagnostic information**:
       * Browser console errors
       * Network tab showing SAML request/response
       * IdP logs (if available)
       * Exact error messages

    2. **Contact Elementum support** with:
       * Your organization name
       * Identity Provider being used
       * Steps to reproduce the issue
       * Diagnostic information collected above
  </Accordion>
</AccordionGroup>

## Advanced Configuration

### Attribute Mapping

Elementum supports these SAML attributes:

| Attribute         | Required | Purpose                          | Example Value       |
| ----------------- | -------- | -------------------------------- | ------------------- |
| `email` or NameID | Yes      | User identification and matching | `user@company.com`  |
| `firstName`       | Yes\*    | User's first name                | `John`              |
| `lastName`        | Yes\*    | User's last name                 | `Doe`               |
| `jobTitle`        | No       | User's job title                 | `Software Engineer` |
| `externalId`      | No\*\*   | External user identifier         | `EMP-12345`         |

\*Required when Auto Create Unknown Users is enabled.

\*\*Required only if you select "External Identifier" as the Identity Connection in Elementum.

<Warning>
  Attribute names are **case-sensitive**. Ensure they match the exact casing shown above (e.g., `jobTitle`, not `JobTitle`). For Azure AD / Entra ID, you must **remove the NameSpace values** from Additional Claims or the integration will fail.
</Warning>

### IdP-Initiated vs SP-Initiated Login

Both flows are supported. IdP-initiated login requires no additional configuration beyond the standard setup.

<Tabs>
  <Tab title="SP-Initiated (Default)">
    1. User starts at the Elementum login page
    2. Clicks "Sign in with SSO"
    3. Redirected to IdP for authentication
  </Tab>

  <Tab title="IdP-Initiated">
    1. User starts at the IdP dashboard
    2. Clicks the Elementum app tile
    3. Directly authenticated into Elementum
  </Tab>
</Tabs>

### SCIM Provisioning

SCIM (System for Cross-domain Identity Management) automates user and group provisioning between your Identity Provider and Elementum. Instead of manually creating users or relying on first-login auto-creation, SCIM keeps user accounts, group memberships, and profile data in sync automatically.

<Note>
  SCIM provisioning requires a working SAML SSO configuration. Complete the SAML setup steps above before configuring SCIM.
</Note>

**Elementum prerequisites:**

1. In **Organization Settings** > **Domains** > **Managed Domains**, confirm the desired domains are configured and SSO is enabled for each
2. In **Organization Settings** > **Single Sign-On**, verify that SAML authentication is enabled and configured (see Configuration Steps above)
3. In the **SCIM Instructions** section on the Single Sign-On page, copy the following values:
   * **SCIM URL** — the endpoint your IdP will use to provision users
   * **SCIM Secret** — the bearer token for authenticating SCIM requests

<Tabs>
  <Tab title="Okta">
    **Set up users:**

    1. In the Okta Admin Console, go to **Directory** > **People**
    2. Click **Add person** and fill in the required fields: **First Name**, **Last Name**, and **Username** (the user's email address)
    3. Click **Save** (or **Save and Add Another** for additional users)

    <Note>
      To support [Org Structure](/administration/org-structure) in Elementum — the hierarchy that drives dynamic manager-based approval routing — the Employee ID field must be populated via API from your identity system. Once SCIM provisioning runs, each user's Org Structure entry syncs automatically.
    </Note>

    **Set up groups:**

    1. Go to **Directory** > **Groups** and click **Add group**
    2. Enter a name (e.g., "Elementum") and click **Save**
    3. Open the new group, go to the **People** tab, and click **Assign people**
    4. Click **+** for each user to add, then click **Done**

    **Create and configure the application:**

    1. Go to **Applications** > **Applications** and click **Browse App Catalog**
    2. Search for **SCIM 2.0 Test App**, select **SCIM 2.0 Test App (OAuth Bearer Token)**, and click **Add Integration**
    3. Update the application label if desired, click **Next**, then **Done**
    4. Open the application and go to the **Provisioning** tab
    5. In **Settings** > **Integration**, click **Configure API Integration**
    6. Check **Enable API Integration** and enter:
       * **SCIM connector base URL**: Paste the SCIM URL from Elementum
       * **OAuth Bearer Token**: Paste the SCIM Secret from Elementum
    7. Click **Test API Credentials** to verify the connection, then click **Save**
    8. Go to **Provisioning** > **Settings** > **To App** and click **Edit**
    9. Enable the following, then click **Save**:
       * Create Users
       * Update User Attributes
       * Deactivate Users

    **Assign groups and provision:**

    1. In the **Assignments** tab, click **Assign** > **Assign to Groups**
    2. Click **Assign** next to the group you created, then click **Done**
    3. Go to the **Push Groups** tab, click **Push Groups** > **Find Groups by Name**
    4. Select the group, click **Create Group**, then **Save**
    5. On the Push Groups page, click **Active** on the group and select **Activate Push Group**

    <Tip>
      For subsequent syncs after the initial push, select **Push Now** instead of Activate Push Group.
    </Tip>
  </Tab>

  <Tab title="Microsoft Entra ID">
    **Set up users:**

    Ensure each user in Entra ID has the following fields populated:

    * **Identity**: First Name (required), Last Name (required)
    * **Job Information**: Job Title (optional)
    * **Contact Information**: Email — the domain must match the domain enabled for SSO in Elementum

    To populate [Org Structure](/administration/org-structure) in Elementum — the hierarchy that drives dynamic manager-based approval routing — include at least one of the following in **Job Information**: Department, Employee ID, or Manager. These fields sync to each user's Org Structure entry on the next provisioning run.

    **Set up groups:**

    Create a new security group (e.g., "Elementum") or use an existing security group.

    **Create and configure the enterprise application:**

    1. Go to **Enterprise Applications** > **Create your own application**
    2. Enter a name and select **Integrate any other application you don't find in the gallery (Non-gallery)**
    3. In the application, click **Users and Groups** > **Add user/group** and assign the security group (or individual users)
    4. Click **Provisioning** and configure:
       * **Provisioning Mode**: Select **Automatic**
       * **Tenant URL**: Paste the SCIM URL from Elementum
       * **Secret Token**: Paste the SCIM Secret from Elementum
    5. Click **Test Connection** to verify, then click **Save**

    **Provision users:**

    1. Click **Provisioning** in the left pane
    2. To test first, click **Provision on Demand**:
       * Select the group, choose **View Members only**, select desired members, and click **Provision**
       * Verify the group and users appear in Elementum
    3. To enable ongoing sync, click **Start Provisioning**

    **Auto-provisioning behavior:**

    Once automatic provisioning is enabled, actions in Entra ID trigger corresponding changes in Elementum:

    | Entra ID Action                                | Elementum Result                                                            |
    | ---------------------------------------------- | --------------------------------------------------------------------------- |
    | Add a user to a provisioned group              | User is created (if new), reactivated (if inactive), and added to the group |
    | Remove a user from a group                     | User is removed from the group and deactivated if not in any other groups   |
    | Remove a group assignment from the application | Group is removed; users deactivated if not in any other groups              |
    | Remove a user assignment from the application  | User is deactivated                                                         |
    | Delete a group                                 | Group is removed; users deactivated if not in any other groups              |
    | Delete a user                                  | User is removed from associated groups and deactivated                      |

    For more details, see [Microsoft's provisioning documentation](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works).
  </Tab>
</Tabs>
