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

# Okta SSO

> Set up Okta as a SAML 2.0 identity provider for Empuls — covering app creation in Okta, attribute mapping, metadata exchange, and connection testing.

Empuls supports SAML 2.0-based Single Sign-On through Okta, enabling employees to authenticate using their corporate Okta credentials. Once configured, Okta controls who can access Empuls — users gain or lose access automatically based on their Okta assignments, and no passwords are stored in Empuls.

## How it works

With SAML 2.0, Okta acts as the Identity Provider (IdP) and Empuls acts as the Service Provider (SP). The authentication sequence is:

1. The user enters their email on the Empuls login page and clicks **Proceed**.
2. Empuls redirects the user to Okta.
3. Okta verifies the user's credentials.
4. Okta sends a signed SAML response back to Empuls.
5. Empuls grants the user access.

## Prerequisites

* Admin access to the Okta Admin Console
* Super Admin access to Empuls
* Your Empuls tenant URL

## Step A: Get Empuls SP metadata from Empuls

<Steps>
  <Step title="Open Empuls authentication settings">
    Log in to Empuls. Navigate to **Reports & Settings → Admin Dashboard → User Authentication → Custom Login SAML 2.0 SSO**.
  </Step>

  <Step title="Copy or download SP details">
    From the SAML 2.0 configuration page, copy the following values — you will enter them in Okta:

    * **ACS URL** (Assertion Consumer Service URL)
    * **Entity ID** (Audience URI)
    * **Name ID format**

    Alternatively, click **Download SP Metadata** to save `empuls-sp-metadata.xml`. You can upload this file directly in Okta.
  </Step>
</Steps>

## Step B: Create the Empuls app in Okta

<Steps>
  <Step title="Open Okta Admin Console">
    Log in to the Okta Admin Console. Go to **Applications → Create App Integration**.
  </Step>

  <Step title="Choose SAML 2.0">
    Select **SAML 2.0** as the sign-in method and click **Next**.
  </Step>

  <Step title="Name the application">
    Enter **Empuls** as the app name and click **Next**.
  </Step>

  <Step title="Configure SAML settings">
    In the SAML Settings screen, enter the following:

    | Okta field                   | Value                                                    |
    | ---------------------------- | -------------------------------------------------------- |
    | **Single Sign-On URL**       | Empuls ACS URL                                           |
    | **Audience URI (Entity ID)** | Empuls Entity ID                                         |
    | **Name ID Format**           | EmailAddress                                             |
    | **Name ID Value**            | Email or Employee ID (must match user records in Empuls) |
  </Step>

  <Step title="Save the application">
    Click **Next**, review your settings, and click **Finish** to save the application.
  </Step>
</Steps>

## Step C: Assign users in Okta

<Steps>
  <Step title="Open the Empuls app in Okta">
    From the Applications list, click on the Empuls app you just created.
  </Step>

  <Step title="Assign users or groups">
    Go to the **Assignments** tab. Assign individual **Users** or **Groups** who should be able to log in to Empuls via SSO. Only assigned users can authenticate through Okta SSO.
  </Step>
</Steps>

## Step D: Export Okta metadata and upload to Empuls

<Steps>
  <Step title="Download Okta IdP metadata">
    In the Okta Admin Console, go to **Applications → Empuls → Sign On** tab. Click **View SAML setup instructions** and download the **IdP Metadata XML** file.
  </Step>

  <Step title="Upload to Empuls">
    Return to Empuls. Go to **User Authentication → SAML 2.0** (at `/home/integrations/saml_sso`). In the Identity Provider metadata section, upload the Okta IdP metadata XML file.
  </Step>

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

## Step E: Test the connection

<Steps>
  <Step title="Click Test Connection">
    On the Empuls SAML 2.0 page, click **Test Connection**. A pop-up window opens.
  </Step>

  <Step title="Sign in with Okta">
    You are redirected to Okta. Log in with your Okta credentials.
  </Step>

  <Step title="Confirm success">
    If the connection is working, you are redirected back to Empuls with a success confirmation. SSO is now active.
  </Step>
</Steps>

<Warning>
  If the test pop-up does not open, your browser is likely blocking pop-ups. Allow pop-ups for your Empuls domain and retry the test.
</Warning>

## Step F: Set Okta SSO as the default login method

To make Okta SSO the default for all users, go to **Admin Dashboard → User Authentication → Custom Login Method → SAML 2.0 (Okta)** and set it as the default login method.

## Other SAML 2.0 providers

The same general process applies to other SAML 2.0-compatible identity providers. The key steps are always: obtain Empuls SP metadata → configure the IdP app → download IdP metadata → upload to Empuls → test the connection.

### OneLogin

In OneLogin, create a **SAML Test Connector (Advanced)** application. In the **Configuration** tab, enter the Empuls ACS URL and Entity ID (or upload `empuls-sp-metadata.xml` for auto-mapping). Set the **NameID Format** to **Email** or **Unspecified** with Employee ID. Download the OneLogin IdP metadata XML from **Applications → Your App → SSO → Download Metadata** and upload it to Empuls at `/home/integrations/saml_sso`. Click **Test Connection** to verify.

### Ping Identity

In the PingOne console, go to **Connections → Applications** and add a new **Web App** with **SAML** as the connection type. Name the app **Empuls**. Either upload `empuls-sp-metadata.xml` (recommended) or manually enter the ACS URL and Entity ID. In **Attribute Mapping**, map **SAML\_SUBJECT** to the user's **Email Address**. Toggle the app to **ON** to enable access. Download the IdP Metadata XML from the **Configuration** tab and upload it to Empuls. Click **Test Connection** to verify.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test connection fails">
    * Confirm the **Name ID** in Okta is set to Email or Employee ID.
    * Verify the ACS URL and Entity ID in Okta exactly match the values from Empuls — extra spaces or trailing slashes can cause failures.
    * If you recently updated your Okta configuration, re-download and re-upload the Okta IdP metadata in Empuls.
  </Accordion>

  <Accordion title="User is assigned in Okta but cannot log in to Empuls">
    * Confirm the user exists in Empuls (check **Admin → Manage Employees**).
    * Verify the email address or employee ID in the user's Okta profile exactly matches their record in Empuls.
  </Accordion>

  <Accordion title="Pop-up is blocked during testing">
    Allow pop-ups for your Empuls domain in your browser settings and retry.
  </Accordion>

  <Accordion title="Can I enable two custom SSO options simultaneously?">
    Contact [cs@xoxoday.com](mailto:cs@xoxoday.com) to enable multiple custom SSO providers for your organization.
  </Accordion>
</AccordionGroup>