> ## 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.

# Azure AD SSO

> Step-by-step instructions for configuring Azure AD as a SAML 2.0 identity provider for Empuls, including SP metadata exchange and connection testing.

Empuls integrates with Azure Active Directory (Azure AD) through SAML 2.0, allowing employees to sign in to Empuls using their existing Microsoft corporate credentials. Once connected, access is managed entirely through Azure AD — you provision and deprovision users centrally, and no passwords are stored in Empuls.

<Note>
  The built-in **Microsoft SSO** toggle in Empuls User Authentication settings uses Microsoft's OAuth flow and is a different integration path from Azure AD SAML 2.0. Use this guide when you need SAML-based federation with Azure AD, which gives you more control over attribute mappings, conditional access policies, and enterprise app assignments.
</Note>

## Prerequisites

Before you begin, make sure you have:

* Admin access to the [Azure portal](https://portal.azure.com)
* Super Admin access to Empuls
* Your Empuls tenant URL (for example, `https://yourcompany.empuls.com`)

## Part 1: Add Empuls as an enterprise application in Azure

<Steps>
  <Step title="Open Azure Active Directory">
    In the Azure portal, select **Azure Active Directory** from the left navigation panel, then select **Enterprise Applications**.
  </Step>

  <Step title="Create a new application">
    In the Enterprise Applications pane, click **+ New application**. Switch to the legacy app gallery experience if prompted.
  </Step>

  <Step title="Select non-gallery application">
    Click **Non-gallery application** (the third card in the gallery view). This option lets you configure a custom SAML application.
  </Step>

  <Step title="Name the application">
    Enter a display name such as **Xoxoday Empuls**, then click **Add**.
  </Step>

  <Step title="Assign users">
    Go to **Users and groups** and map the users or groups that should have access to Empuls. To grant all users access automatically, set the **User Assignment Required** property to **No** in the application properties.
  </Step>

  <Step title="Configure SAML">
    From the application overview, select **Set up single sign-on**, then choose **SAML**.
  </Step>

  <Step title="Edit basic SAML configuration">
    Click the **Edit** (pencil) icon on the **Basic SAML Configuration** card.
  </Step>
</Steps>

## Part 2: Enter Empuls SP values in Azure

You need to copy several values from your Empuls account into the Azure SAML configuration.

<Steps>
  <Step title="Open Empuls authentication settings">
    In Empuls, navigate to **Admin > User Access Settings > User Authentication**. Select **Custom Login Methods** and click **Configure Now** to open the SAML 2.0 configuration page. You can also navigate directly to `/home/integrations/saml_sso`.
  </Step>

  <Step title="Copy or download SP metadata">
    From the Empuls SAML page, either:

    * Copy the individual SP values listed below, or
    * Click **Download SP Metadata** to get `empuls-sp-metadata.xml` and upload it directly into Azure (this auto-fills most fields).
  </Step>

  <Step title="Fill in Azure basic SAML configuration">
    Enter the following values from your Empuls SAML page into the Azure Basic SAML Configuration fields:

    | Azure field                | Value from Empuls                                                              |
    | -------------------------- | ------------------------------------------------------------------------------ |
    | **Identifier (Entity ID)** | Entity ID (format: `https://yourcompany.xoxoday.com/chef/sso/metadata-sp/...`) |
    | **Reply URL (ACS URL)**    | Assertion Consumer Service URL                                                 |
    | **Sign on URL**            | SSO redirect URL                                                               |
    | **Relay State**            | Your Empuls login URL                                                          |
    | **Logout URL**             | IDP logout URL                                                                 |
  </Step>

  <Step title="Save the configuration">
    Click **Save** at the top of the Basic SAML Configuration panel.
  </Step>
</Steps>

<Note>
  In the **User Attributes & Claims** section, Azure maps `emailaddress` to `user.mail` by default. Empuls validates users by Email ID or Employee ID — make sure the Name ID value in the SAML response corresponds to the email address or employee ID stored in Empuls.
</Note>

## Part 3: Download Azure metadata and upload to Empuls

<Steps>
  <Step title="Download the Federation Metadata XML">
    On the Azure SAML configuration page, locate the **SAML Signing Certificate** card (card 3). Click **Download** next to **Federation Metadata XML** to save the file to your computer.
  </Step>

  <Step title="Upload the metadata to Empuls">
    Return to the Empuls SAML 2.0 configuration page (`/home/integrations/saml_sso`). In the **Identity Provider metadata** section, upload the Federation Metadata XML file you downloaded from Azure.
  </Step>

  <Step title="Save">
    Save your changes in Empuls.
  </Step>
</Steps>

## Part 4: Test the connection

<Steps>
  <Step title="Click Test Connection">
    On the Empuls SAML 2.0 configuration page, click **Test Connection**. A pop-up window opens and redirects you to the Azure sign-in page.
  </Step>

  <Step title="Sign in with Azure credentials">
    Enter your Microsoft credentials in the pop-up. Azure authenticates you and redirects back to Empuls.
  </Step>

  <Step title="Confirm success">
    Empuls displays an "SSO verification is successful" message to confirm the integration is working.
  </Step>
</Steps>

<Warning>
  If the test pop-up does not open, your browser may be blocking pop-ups. Allow pop-ups for your Empuls domain and try again.
</Warning>

## Data flow architecture

When a user logs in after Azure AD SSO is configured, the authentication flow works as follows:

1. User enters their email on the Empuls login page and clicks **Proceed**.
2. Empuls identifies the SAML configuration and redirects the user to Azure AD.
3. Azure AD authenticates the user and issues a signed SAML assertion.
4. The assertion is sent back to Empuls via the ACS URL.
5. Empuls validates the assertion and grants the user access.

## FAQs

<AccordionGroup>
  <Accordion title="Can I enable two custom SSO options at the same time?">
    Yes, this is possible with additional configuration. Contact [cs@xoxoday.com](mailto:cs@xoxoday.com) to enable multiple custom SSO options for your organization.
  </Accordion>

  <Accordion title="What user attribute does Empuls use to match identities?">
    Empuls matches users by Email ID or Employee ID. The value in the SAML Name ID field must match the corresponding field in your Empuls user records exactly.
  </Accordion>

  <Accordion title="Can I upload the SP metadata file instead of copying values manually?">
    Yes. Download `empuls-sp-metadata.xml` from the Empuls SAML page and upload it in Azure during the SAML app configuration. Azure auto-populates the Entity ID, ACS URL, and other fields from the file.
  </Accordion>
</AccordionGroup>