Skip to main content

Documentation Index

Fetch the complete documentation index at: https://empuls.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Empuls can be integrated with any identity provider that supports the SAML 2.0 standard. Open the SAML metadata page in your tenant at https://<your-empuls-url>/home/saml-metadata. 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 valueDescription
Entity IDUniquely 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 URLThe URL Empuls uses to initiate SSO redirects
Relay StateThe URL users land on after successful authentication (usually your Empuls login page)
Logout URLCalled 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:
1

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

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

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

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 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.
Ensure your browser allows pop-ups for your Empuls domain. The test connection uses a pop-up window that most browsers block by default.

​
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

1

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

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.

​
Relying party trust configuration

1

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

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

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

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.

​
Claim rules configuration

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

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

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

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

​
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
  • Okta — see dedicated guide
  • 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.