> ## Documentation Index
> Fetch the complete documentation index at: https://help-empuls.xoxoday.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom SAML 2.0

> Set up SSO in Empuls with any SAML 2.0-compatible identity provider, including ADFS, Oracle IAM, and others not listed as built-in options.

Empuls can be integrated with any identity provider that supports the SAML 2.0 standard. If your organization uses a provider not listed in the standard Empuls authentication options — such as Microsoft ADFS, Oracle IAM, or an in-house identity system — you can configure it using the Custom Login Methods path. The setup follows the same trust exchange pattern: Empuls shares Service Provider (SP) metadata with your IdP, and your IdP shares its metadata back.

## What SAML 2.0 requires

SAML (Security Assertion Markup Language) is an open XML-based standard for exchanging authentication data between an identity provider and a service provider. For the integration to work, your identity provider must:

* Support SAML 2.0 as an authentication protocol
* Accept a Service Provider metadata XML file or manually entered SP configuration values
* Issue a digitally signed XML assertion containing the user's identity
* Send the Name ID value as either **Email ID** or **Employee ID** matching the user records in Empuls

Empuls validates user identity using the Name ID value in the SAML assertion. The value must exactly match the Email ID or Employee ID stored in Empuls for the user.

## Prerequisites

* Super Admin access to Empuls
* Administrator access to your identity provider
* Involvement of your IT/security team for DNS, certificates, and IdP configuration

## Step 1: Access the SAML configuration in Empuls

Navigate to **Admin > User Access Settings > User Authentication**. Select **Custom Login Methods** and click **Configure Now**.

You can also navigate directly to `/home/integrations/saml_sso` in your Empuls tenant.

## Step 2: Obtain Empuls SP metadata

Empuls displays your organization's Service Provider details on the SAML configuration page. You need to provide these values to your identity provider.

| Configuration value                          | Description                                                                            |
| -------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Entity ID**                                | Uniquely identifies Empuls as the SAML service provider                                |
| **ACS URL (Assertion Consumer Service URL)** | The endpoint where your IdP sends the SAML response after authentication               |
| **Sign-On URL**                              | The URL Empuls uses to initiate SSO redirects                                          |
| **Relay State**                              | The URL users land on after successful authentication (usually your Empuls login page) |
| **Logout URL**                               | Called by Empuls when a user signs out                                                 |

Click **Download SP Metadata** to download `empuls-sp-metadata.xml`. Most SAML identity providers accept this file to auto-populate all SP configuration fields, which reduces manual entry errors.

## Step 3: Configure your identity provider

The exact steps vary by provider, but the general process is:

<Steps>
  <Step title="Create a new SAML application or relying party">
    In your identity provider's admin console, create a new SAML 2.0 application. Name it something recognizable, such as **Empuls**.
  </Step>

  <Step title="Import or enter SP metadata">
    Upload `empuls-sp-metadata.xml` if your IdP supports metadata import. Otherwise, manually enter the Entity ID, ACS URL, and other SP values from Empuls.
  </Step>

  <Step title="Configure attribute mapping">
    Map the user's email address or employee ID to the SAML **NameID** field. The format should be set to **Email** or **Unspecified** depending on which identifier you use.
  </Step>

  <Step title="Download IdP metadata">
    After saving your IdP configuration, download the Identity Provider metadata XML file. This file contains your IdP's Entity ID, SSO URL, and signing certificate.
  </Step>
</Steps>

## Step 4: Upload IdP metadata to Empuls

Return to the Empuls SAML configuration page (`/home/integrations/saml_sso`). In the **Identity Provider metadata** section, upload the metadata XML file downloaded from your IdP. Empuls uses this to validate the signed assertions from your identity provider.

## Step 5: Test the connection

Click **Test Connection** on the Empuls SAML page. A pop-up window opens and redirects you to your IdP login page. Enter your credentials, and if the configuration is correct, you are redirected back to Empuls with a success confirmation.

<Warning>
  Ensure your browser allows pop-ups for your Empuls domain. The test connection uses a pop-up window that most browsers block by default.
</Warning>

## ADFS-specific configuration

If your organization uses Microsoft Active Directory Federation Services (ADFS 2.0), follow these additional steps alongside the general process above.

### ADFS configuration

<Steps>
  <Step title="Locate the ADFS metadata file">
    Open the ADFS 2.0 Management console from **Start → Administrative Tools → ADFS 2.0 Management**. Expand **Service** and select the **Endpoints** node. The `FederationMetadata.xml` file is located at `/FederationMetadata/2007-06/FederationMetadata.xml` on your ADFS server — this location is the same for all ADFS deployments.
  </Step>

  <Step title="Download FederationMetadata.xml">
    Navigate to `https://your-adfs-server/FederationMetadata/2007-06/FederationMetadata.xml` in a browser. Save the file — you will upload this to Empuls in a later step.
  </Step>
</Steps>

### Relying party trust configuration

<Steps>
  <Step title="Add a relying party trust">
    In ADFS Management, navigate to **Trust Relationships → Relying Party Trusts**. Right-click and choose **Add Relying Party Trust** to launch the wizard.
  </Step>

  <Step title="Import Empuls SP metadata">
    Select **Import data about the relying party from a file**. Browse to the `empuls-sp-metadata.xml` file you downloaded from Empuls. Click **Next**.
  </Step>

  <Step title="Set display name and access policy">
    Dismiss any informational pop-up. Enter a display name such as **Empuls** or **Xoxoday** and click **Next**. Select **Permit all users to access the relying party** and click **Next** to finish.
  </Step>

  <Step title="Set secure hash algorithm">
    Right-click the relying party you just created and select **Properties**. On the **Advanced** tab, set **Secure hash algorithm** to **SHA-256** and click **OK**.
  </Step>
</Steps>

### Claim rules configuration

ADFS requires claim rules to pass the correct user attributes to Empuls.

<Steps>
  <Step title="Open claim rules editor">
    Right-click the Empuls relying party trust and select **Edit Claim Rules**. On the **Issuance Transform Rules** tab, click **Add Rule**.
  </Step>

  <Step title="Add LDAP attribute rule">
    Select **Send LDAP Attributes as Claims** and click **Next**. Name the rule (for example, **Get LDAP Attributes**). Select **Active Directory** as the attribute store and add these mappings:

    * LDAP Attribute: **E-Mail-Addresses** → Outgoing Claim Type: **E-Mail Address**
    * LDAP Attribute: **Employee ID** → Outgoing Claim Type: **Employee ID**

    Click **Finish**.
  </Step>

  <Step title="Add Name ID transform rule">
    Add a second rule. Select **Transform an Incoming Claim** and click **Next**. Name it (for example, **Email to Name ID**). Set:

    * Incoming claim type: **E-Mail Address**
    * Outgoing claim type: **Name ID**
    * Outgoing name ID format: **Email**

    Click **Finish**.
  </Step>
</Steps>

<Note>
  The email address must be defined for all users in Active Directory. ADFS cannot issue a valid Name ID assertion for users without an email attribute.
</Note>

### Upload ADFS metadata to Empuls

Upload the `FederationMetadata.xml` file from your ADFS server to the Identity Provider metadata section in Empuls (`/home/integrations/saml_sso`). Click **Test Connection** to verify the integration.

## Supported identity providers

The following SAML 2.0 providers are known to work with Empuls:

* Azure Active Directory — [see dedicated guide](/admin/user-authentication/azure-ad)
* Okta — [see dedicated guide](/admin/user-authentication/okta-sso)
* OneLogin
* Ping Identity (PingOne)
* Microsoft ADFS 2.0
* G Suite / Google Workspace
* Oracle IAM
* Any other IdP supporting SAML 2.0

## Next steps

After enabling SAML 2.0 SSO, monitor login success rates for the first week. Share documentation with users explaining that they should now use their identity provider credentials to log in. Coordinate with your IT team on any future identity provider changes (certificate renewals, URL changes) that require updating the metadata in Empuls.

For questions or support, contact [cs@xoxoday.com](mailto:cs@xoxoday.com).