UltiPro SSO: Complete Configuration, SAML Integration, and Troubleshooting Guide

UltiPro Single Sign-On (SSO) enables organizations to authenticate users into the UKG Pro platform—formerly known as UltiPro—using centralized identity providers such as Microsoft Entra ID, Okta, or PingFederate. Operating on SAML 2.0 standards, UltiPro SSO eliminates repetitive password entries, streamlines employee onboarding, strengthens corporate credential governance, and supports secure desktop and mobile access.

Understanding UltiPro SSO: Architecture and Identity Federation

Following the merger of Ultimate Software and Kronos to create UKG (Ultimate Kronos Group), UltiPro was rebranded as UKG Pro. Despite this product rebranding, legacy infrastructure configurations, existing single sign-on endpoints, and corporate IT documentation frequently designate the service as UltiPro SSO. Within modern enterprise environments, the underlying authentication architecture remains anchored to Security Assertion Markup Language (SAML) 2.0, an open standard for exchanging authentication and authorization data between distinct security domains.

In an UltiPro SSO deployment, the architecture divides responsibilities between two principal entities:

1. The Identity Provider (IdP): This is your organization's centralized identity directory—such as Microsoft Entra ID (formerly Azure Active Directory), Okta, PingIdentity, or Active Directory Federation Services (ADFS). The IdP maintains user credentials, enforces Multi-Factor Authentication (MFA), evaluates conditional access policies, and issues cryptographically signed SAML assertions.

2. The Service Provider (SP): UltiPro (UKG Pro) acts as the Service Provider. It does not store or validate employee passwords directly when SSO is enforced. Instead, it relies on the authenticity of the SAML token transmitted by the IdP to grant entry.

3. Request Access: Employee Client Browser requests access from UltiPro (UKG Pro) (Service Provider).

4. SAML Auth Challenge: UltiPro (UKG Pro) sends a SAML authentication challenge to the Employee Client Browser.

5. Submit Credentials: Employee Client Browser submits credentials to the Identity Provider (Entra ID, Okta) via the Identity Verification Flow.

6. Issue Signed Token: Identity Provider (Entra ID, Okta) issues a signed token to the Employee Client Browser.

7. Post SAML Assertion: Employee Client Browser posts the SAML assertion to UltiPro (UKG Pro) (Service Provider).

8. Session Established: UltiPro (UKG Pro) establishes the session with the Employee Client Browser.

UltiPro supports both major federation workflows:

• Identity Provider-Initiated (IdP-Initiated) SSO: The employee signs into their corporate dashboard (e.g., myapps.microsoft.com or your company's Okta portal) and selects the UltiPro/UKG Pro application tile. The IdP generates an unsolicited SAML response and redirects the browser directly into the UltiPro session.
• Service Provider-Initiated (SP-Initiated) SSO: The employee navigates directly to the company-specific UltiPro URL (typically formatted as https://[customername].ultipro.com or through the UKG tenant domain). UltiPro intercepts the request, recognizes that federated authentication is required, generates a SAML authentication request (AuthnRequest), and redirects the user's browser to the enterprise IdP login portal before returning them to the destination page.

Technical Prerequisites for Setting Up UltiPro SSO

Establishing federation between your corporate identity directory and UltiPro requires administrative coordination across both systems. Before modifying authentication pipelines, ensure the following prerequisites are met:

• UKG Pro Administrative Rights: Direct access to a system administrator account within UltiPro with privileges to modify System Configuration, Security Roles, and Single Sign-On parameters.
• IdP Administrative Rights: Sufficient privileges within your enterprise identity management tool (such as Global Administrator or Cloud Application Administrator in Microsoft Entra ID, or Super Admin in Okta) to create enterprise application registrations, define attribute claims, and issue signing certificates.
• X.509 Signing Certificate: A valid certificate generated by the IdP utilizing SHA-256 signature algorithms. SAML transactions secured with deprecated SHA-1 algorithms should not be implemented due to cryptographic vulnerabilities.
• Normalized User Identifiers: A universally shared attribute that exists identically in both the enterprise identity directory and the UltiPro personnel database. The most common mapping fields are the corporate User Principal Name (UPN) / Email Address, or the corporate Employee ID Number. Inconsistencies between these values will result in authentication rejection.

Step-by-Step Configuration Workflow

Configuring federated single sign-on requires an accurate exchange of metadata between the identity provider and the service provider. The following workflow outlines the technical progression necessary to deploy and activate the connection.

Step 1: Obtain Service Provider (UltiPro) Metadata

UltiPro requires specific connection identifiers that your identity provider must recognize to route assertions securely:

1. Log into your UltiPro environment as an administrator and navigate to System Configuration > Security > Single Sign-On.
2. Locate the Service Provider Metadata section. Depending on your platform hosting pod, your Assertion Consumer Service (ACS) URL and Entity ID will follow designated regional templates.
3. Note your unique Entity ID (e.g., https://[tenant].ultipro.com or a persistent URI provided by UKG) and the Assertion Consumer Service (ACS) URL (such as https://[tenant].ultipro.com/pages/saml/acs.aspx or regional equivalent).
4. Download the UltiPro SP metadata XML file if your IdP supports direct metadata upload.

Step 2: Configure the Enterprise Identity Provider

Using the metadata retrieved from UltiPro, configure the enterprise application within your identity management system:

1. Create a new custom SAML 2.0 application or deploy the pre-built UKG Pro / UltiPro template from your IdP's application gallery.
2. In the basic SAML settings, input the UltiPro ACS URL into the Single Sign-On URL / Reply URL field.
3. Input the UltiPro Entity ID into the Identifier / Audience URI field.
4. Set the SAML NameID Format to EmailAddress or Unspecified, aligning precisely with the format UltiPro expects based on your directory design.
5. Ensure the signing option is configured to sign the SAML Assertion or SAML Response and Assertion using SHA-256.

Step 3: Define Attribute Claims and Assertion Mapping

The identity provider must send user identification details within the SAML token so UltiPro can associate the incoming session with a specific employee record:

1. Access the Attributes & Claims configuration area of your identity provider.
2. Set the primary claim value. If UltiPro matches users by email address, verify that nameidentifier passes the user's primary corporate email or UPN.
3. If your UltiPro deployment relies on employee identification numbers, configure a specific claim attribute (e.g., EmployeeNumber or federatedID) mapped directly to the corresponding attribute in your internal directory (such as employeeId in on-premises Active Directory or Entra ID).
4. Save the claim mappings and export the IdP SAML signing certificate (Base64-encoded X.509 format) and the IdP Federation Metadata XML.

Step 4: Import IdP Metadata into UltiPro

Once the IdP side is configured, apply the identity provider's parameters within UltiPro:

1. Return to UltiPro System Configuration > Single Sign-On.
2. Enter the Identity Provider Entity ID (Issuer URL).
3. Enter the Single Sign-On Service URL (the IdP login redirect endpoint).
4. Upload the Base64 X.509 signing certificate obtained from your IdP.
5. Specify the attribute mapping criteria within UltiPro that matches your claim structure (e.g., map the inbound identifier to the UltiPro "User Name", "Email Address", or "Employee ID" field).
6. Save the configuration. Do not immediately enforce SSO across all security roles until verification testing succeeds.

Step 5: Validation and Fallback Governance

Before enforcing SSO globally, conduct controlled testing to avoid operational lockouts:

1. Open an isolated incognito or private browser window.
2. Navigate to your UltiPro SP-initiated login URL. Confirm that the system redirects appropriately to your enterprise IdP authentication screen.
3. Authenticate with a standard test user account, complete any designated MFA challenges, and verify that the browser is successfully returned to the UltiPro dashboard with the proper permissions.
4. Establish a Break-Glass Account: Keep at least one native, break-glass administrator account exempted from mandatory SSO redirection. If an IdP certificate expires unexpectedly or network federation fails, native password authentication ensures your organization retains administrative access to update settings.

Identity Provider Comparison & Configuration Matrix

Different identity providers manage SAML metadata, claim structures, and certificate rotations with varying operational defaults. The table below outlines key integration differences when connecting these systems to UltiPro:

Troubleshooting Common UltiPro SSO Errors

When SAML authentication fails, the resulting browser screen often displays vague errors such as "Authentication Failed," "SAML Response Invalid," or continuous redirect loops. Resolving these issues requires checking assertion logs in both the IdP and the UltiPro platform.

1. Authentication Request Initiated
2. Identity Provider Validation
   • Fails Policy/MFA:
     • IdP Access Denied
       • Check Conditional Access
       • Check Group Assignments
   • Passes MFA & Auth:
     • Generate SAML Token
     • Post to UltiPro ACS
       • Certificate Valid? (No):
         • Error: Expired/Mismatch
           • Re-upload Base64 Cert
           • Confirm SHA-256
       • Timestamp Skew? (Yes):
         • Error: Skew/Time Expired
           • Resync NTP Servers
           • Verify Host Clocks
       • Claim Matches? (No):
         • Error: User Not Found
           • Check NameID vs. Field
           • Validate Case-Sensitivity

1. SAML Response Signature Verification Failed

• Symptom: The user authenticates at the IdP, but UltiPro displays an error indicating that the security token could not be verified or accepted.
• Root Cause: The public certificate uploaded to UltiPro does not match the private key used by the IdP to sign the SAML response, or the signing certificate has expired.
• Resolution: Download the latest Base64-encoded .cer or .pem file from your IdP. In UltiPro System Configuration, replace the existing certificate. Verify that the IdP is configured to sign the Assertion or Response and Assertion, as UltiPro rejects unsigned assertions.

2. User Not Found / Account Mismatch

• Symptom: The SAML handshake succeeds, but UltiPro reports that the user profile cannot be located.
• Root Cause: The value passed in the SAML NameID claim does not match the corresponding identity field in UltiPro. For instance, the IdP may be passing john.doe@domain.com, while UltiPro holds the employee's username as jdoe or indexes the record exclusively by Employee ID.
• Resolution: Intercept the SAML token using a browser-based SAML tracer extension. Inspect the and nodes. Cross-reference the value inside the tag with the targeted user profile in UltiPro. Correct the IdP claim rule so the transmitted value precisely matches the active UltiPro employee identifier.

3. Clock Skew and Timestamp Rejections

• Symptom: UltiPro displays an "Assertion expired" or "Invalid timestamp" fault immediately after authentication.
• Root Cause: SAML tokens contain timestamps. If the system clock on your internal identity servers (such as local ADFS servers) drifts more than a few minutes from the cloud-synchronized clocks powering UltiPro, the token will be declared invalid.
• Resolution: Ensure all identity federation servers synchronize reliably via Network Time Protocol (NTP). If your IdP provides an allowed clock skew setting, adjust it to tolerate an offset of up to 120–180 seconds to accommodate transient network latency.

4. Continuous Redirect Loops

• Symptom: The browser rapidly cycles between the UltiPro URL and the IdP authentication endpoint until halting with an HTTP 400, 404, or browser limit warning.
• Root Cause: This typically occurs when an SP-initiated connection reaches the ACS endpoint, but session cookie validation fails, or the target RelayState parameter is stripped or malformed.
• Resolution: Clear client browser cookies and cache. Verify that your IdP configuration does not alter or strip the RelayState payload returned during an SP-initiated transaction. Ensure cross-site tracking protections or browser privacy plugins are not blocking domain cookies between your IdP and ultipro.com.

5. UKG Pro Mobile App Authentication Failures

• Symptom: Desktop browser SSO works without disruption, but the UKG Pro mobile application fails to authenticate users through corporate credentials.
• Root Cause: The mobile client relies on an embedded web view or modern OAuth/SAML redirection. If your enterprise IdP enforces Conditional Access policies requiring specific managed desktop device states or blocks mobile user agents, the mobile authentication workflow fails.
• Resolution: In your IdP (e.g., Entra ID Conditional Access), audit the failed mobile login attempts. Exempt the UKG Pro mobile client application or adjust device-compliance policies to permit corporate-enrolled mobile devices access to the application endpoint.

Security Governance, Lifecycle, and Certificate Operations

An enterprise SSO implementation requires continuous maintenance to prevent unexpected service outages and credential vulnerabilities:

Proactive Certificate Rollover

SAML signing certificates expire periodically (typically every one to three years). If a certificate lapses, the federated authentication pipeline stops processing logins immediately across the organization. Implement a documented schedule to rotate certificates at least 30 days before expiration. Because UltiPro may only support a single active signing certificate at a time in specific legacy configurations, schedule certificate updates during planned maintenance windows, and ensure fallback administrative accounts remain available.

Enforcing Multi-Factor Authentication (MFA)

Because UltiPro handles sensitive human resources, compensation, tax, and direct deposit data, access should never rely on single-factor passwords alone. By offloading authentication to an enterprise IdP, you can enforce centralized MFA policies (such as FIDO2 security keys, authenticator push notifications, or biometric verification) alongside risk-based conditional access rules that detect anomalous sign-in locations.

Deprovisioning and Offboarding

Single sign-on simplifies user offboarding. When an employee leaves the company, disabling their primary enterprise account in the IdP immediately blocks their ability to sign into UltiPro via SSO, even if their HR record processing takes time to complete. However, ensure that HR administrators understand that terminating an account in the IdP does not automatically terminate or delete the employee record in UltiPro. User lifecycle synchronization requires either automated SCIM (System for Cross-domain Identity Management) connectors, UKG Pro integration APIs, or manual record updates.

Frequently Asked Questions About UltiPro SSO

What is the difference between UltiPro SSO and UKG Pro SSO?

UltiPro SSO and UKG Pro SSO refer to the same functional authentication framework. After Ultimate Software merged with Kronos to form UKG, the UltiPro software suite was rebranded as UKG Pro. While modern administrative portals and documentation refer to UKG Pro, underlying SAML configurations, legacy ACS URLs, and third-party IdP application galleries frequently retain the UltiPro name.

Can we enforce SSO for employees while allowing direct password logins for administrators?

Yes. UltiPro allows administrators to configure mixed-mode authentication rules. Organizations can configure specific security roles—such as HR System Administrators—to retain standard username and password access alongside enterprise SSO. This setup provides a reliable administrative fallback method should the third-party identity provider experience downtime or misconfiguration.

How does UltiPro handle user provisioning via Single Sign-On?

SAML 2.0 handles authentication, not continuous account provisioning. While some environments support Just-In-Time (JIT) provisioning to create baseline user shells upon their first successful SAML login, comprehensive HR and payroll management requires rich demographic, tax, and compensation data. Consequently, new employee profiles in UltiPro should be created through your primary HR workflow, automated API pipelines, or standard scheduled import jobs, rather than relying solely on SSO assertions.

Why do users encounter an error after changing their primary email address?

If your SSO configuration uses the user's corporate email address as the primary SAML NameID identifier, changing an employee's email address in your internal directory without simultaneously updating the email field within UltiPro breaks the mapping link. The IdP sends the new email address, which UltiPro fails to match against existing records, resulting in an account mismatch error. Coordinate enterprise email renames to update the UltiPro employee record at the same time.

Does UltiPro SSO support Deep Linking through RelayState?

Yes. UltiPro supports deep linking using the standard SAML RelayState parameter. This allows automated notifications—such as direct links to pay statements, performance reviews, or benefits enrollment forms—to route users directly to the targeted internal page after completing authentication at the IdP, rather than dropping them on the standard home dashboard.

Next Steps for Enterprise Administrators

If you are planning an UltiPro SSO implementation or upgrading an existing federation setup, proceed with these operational priorities:

1. Audit Directory Attribute Alignment: Run a diagnostic cross-check between your active identity directory (e.g., Entra ID, Okta) and the UltiPro employee master database. Identify and clean up any discrepancies in email addresses or Employee IDs before enabling SAML enforcement.
2. Review Certificate Expiration Calendars: Check the expiration date of your current identity provider signing certificate inside the UltiPro Single Sign-On administration screen. Add calendar alerts 60 and 30 days ahead of that date to ensure managed certificate rotation.
3. Verify Break-Glass Procedures: Confirm that your organization maintains at least one monitored, native administrative credential exempted from SSO enforcement. Document and periodically test the break-glass procedure to ensure administrative resilience during identity provider outages.