Authentication Upgrade

About the upgrade to UKG Authentication.

Authentication is the action of verifying the identity of a user or process. Authentication is being upgraded to UKG Authentication.

  • With Basic Authentication, you log in directly from the Login screen with the username and password.

  • With Federated Authentication, you log in from the single sign-on (SSO) link to an identity provider (IDP), and the username and password are shared among multiple applications. The upgrade has little effect on Federated Authentication except for the addition of SSO Username.

Benefits of UKG Authentication

  • Passwords do not expire, so you do not have to reset passwords frequently.

  • Robust session management with fewer disruptive log-outs.

  • Adaptive Multi-Factor Authentication (MFA): If you log in from the same device and location every day, then you do not have to use MFA each time.

  • Client Management to integrate by way of Client Credentials, ROPC, and Auth Code Flow directly. This helps developers to build integrations.

  • A single Logon Profile for everyone with only one, editable setting for Minimum Password Length.

  • You must upgrade to the new Mobile App to replace the previous Mobile App.

Authentication Pre-Upgrade Checklist

Checklist of items to edit before you upgrade to UKG Authentication.

Main Menu > Authentication Upgrade

  1. Before you start to upgrade, clean the data as follows.
  2. Log in.
  3. Click Authentication Upgrade.
  4. Update the following before you upgrade:
    1. (Required) Username formats: Username Formats for the Authentication Upgrade and Upgrade Username Formats.
    2. (Required) Default passwords: Default Passwords for the Authentication Upgrade and Upgrade Default Passwords.
    3. (Required if you use SSO) Single sign-on (SSO): SSO Configuration for the UKG Authentication Upgrade and Upgrade SSO Configuration.
    4. Email addresses: Email Addresses for the Authentication Upgrade and Upgrade Email Addresses.
    5. Phone numbers: Phone Numbers for the Authentication Upgrade and Upgrade Phone Numbers.
  5. Upgrade to UKG Authentication: Upgrade Authentication.

Username Formats for the Authentication Upgrade

Required username formats for UKG Authentication.

For Basic Authentication, the Username must be as follows:

  • Can include only alphanumeric characters and the following: @ . _ + - ! # $ ' ^ ` ~

  • Can be an email address but cannot duplicate a Sign-On Email address that is configured in another person record.
    Note: For example, Person A can have person@abc.com as both Username and Sign-On Email. However, Person B cannot have person@abc.com as Username.

  • Cannot include spaces and accented letters

For Federated Authentication, usernames must be as follows:

  • Usernames can include only alphanumeric characters and the following: @ . _ + - ! # $ ' ^ ` ~

  • Can be an email address but cannot duplicate a Sign-On Email address that is configured in another person record.

  • SSO Username: UKG Authentication adds the SSO Username field which is populated automatically and by default with the same value as in Username. This value matches the value that user accounts that are configured for SSO use. If the value contains a character that is not valid in Username, SSO Username accepts the character automatically. Because SSO Username is the controlling field, the value of Username is adjusted with a value that does not contain the invalid character.

  • Because these fields contract spaces and special characters, non-compliant characters have no impact on Federated user accounts.

Upgrade Username Formats

How to upgrade username formats for the upgrade to UKG Authentication.

Note: Only for user accounts that use Basic Authentication.

Main Menu > Dataviews & Reports

  1. Do either of the following:
    • Expand Username format (required) to show the count of invalid usernames.
    • Click Main Menu > Dataviews & Reports. Click Pre-Upgrade Dataview.
  2. Make sure that the page title is Dataview for Invalid Username. If not, click the drop-down list in the upper left and select Invalid Username.
  3. Review the Dataview of invalid usernames. The Proposed Usernames column shows suggested usernames that are derived from the non-compliant usernames. These suggestions replace spaces, accented letters, or special characters with the last two digits of the hex value for each character. For example, the suggested replacement for the username is . That is, is replaced with , and the space is replaced with .
    • To accept the recommended usernames, select the rows and click Approve.
    • To reject the recommended usernames but update the usernames, select the row for the person and click Go To. Enter a compliant Username.
    • Alternatively, you can export the list from the dataview and update the usernames in another system. Make sure that the updated usernames are compliant.
  4. Once approved, the usernames are updated. People who do not have an email address should be notified of their new username by the organization's standard change-management communication.
  5. For integrations that import usernames from other systems, update the usernames in the source systems. For new user accounts on other systems, configure usernames that comply with this format. Otherwise, the integrations fail.

Default Passwords for the Authentication Upgrade

Required default password formats for UKG Authentication.

All passwords — including the default passwords that are set by integrations — must comply with the Password Policy as follows:

  • You can edit only the Minimum Password Length from 8 (default) to 64 characters.

  • Passwords do not expire unless the administrator requires a password reset the next time the person logs in.
    Note: User accounts are deactivated if the person does not log in within 30 days of the date the account was created.

  • The concept of multiple Logon Profiles is no longer supported, and all user accounts share the same password policy; see the Password Policy topic.

Integrations that set the default password for user accounts may not comply with the password policy. So, the upgrade adds a suffix to default passwords so that the integrations continue to run without password errors. Because the addition of the suffix meets all password requirements, it is appended to the passwords that the integrations use. As a result, the password plus the suffix is valid as a password and does not trigger an error.

If an integration created a user account with person25 as the password, the integration fails because the password does not have any upper-case letter or special characters, and is shorter than the minimum of 8 characters. However, if the Suffix is Person2025!, the password for the user account becomes person25Person2025! which is a valid password.

Upgrade Default Passwords

How to upgrade default passwords for the upgrade to UKG Authentication.

Main Menu > Administration > Application Setup > Access Profiles > Logon Profiles

Note: Integrations that set the password for user accounts require a password suffix in order to continue to run without password errors. For both Basic and Federated types of authentication, you must set the default password suffix value. To use the value, you must enable the system setting as described below.
  1. Do either of the following:
    • Select Default password policy (required) in the checklist, then click View default password method.
    • Click Main Menu > Administration > Application Setup > Access Profiles > Logon Profiles. Select the profile.
  2. Click Configure Password Policy.
  3. You can edit only the Minimum Password Length from (default) to characters.
  4. In Suffix, enter a value that meets all of the requirements in the Password Policy. Because the suffix alone meets all password requirements, it is appended to the passwords that the integrations use so that the password plus the suffix is valid as a password and does not trigger an error.
  5. (Optional) Select Use ONLY Suffix as the Default Password (false by default) to ignore the original password in the integration and use only the Suffix as the password.
  6. Note: After the upgrade, the only way to edit the password suffix is to click Main Menu > Administration > Application Setup > Access Profiles > Logon Profiles, and select the profile.
    Click Save & Return.
  7. To use the password suffix when you create user accounts, enable the site.security.passwrd.suffix.allowed system setting (not enabled by default) in Main Menu > Administration > Application Setup > System Settings > Security tab.

SSO Configuration for the UKG Authentication Upgrade

Overview of single sign-on (SSO) configuration for the upgrade to UKG Authentication.

SSO configuration for the upgrade to UKG supports the following:

  • You can configure multiple identity providers (IDP).

  • Access to each IDP is by way of a unique vanity URL, and employees can navigate easily to the correct sign in page.

  • A variety of IDPs are supported for compatibility with existing infrastructure.

  • The system supports IDP service level objective (SLO) functionality for SAML2 which eliminates the risks from not terminating IDP sessions.

Upgrade SSO Configuration

How to upgrade your SSO configuration for the UKG Authentication upgrade.

Important: If you see the Configure your Single Sign-On (SSO) connection (Required) section in the upgrade checklist, the tenant has an SSO URL. (Optional) You can choose to skip SSO configuration if SSO is configured but not being used. If SSO is being used, do not skip this procedure.
Note: The following people are required to complete this configuration: An IT Member who has access to the IDP, and an HR Administrator who has access to the SSO tool for the UKG Pro suiteUKG Pro Workforce Management. Each of the following steps indicates which person completes that step. Alternatively, a single administrator who has access to both systems can complete this configuration.
  1. (HR Administrator role) Do one of the following:
    • If you are configuring SSO before the upgrade, expand Configure your Single Sign-On (SSO) connection (Required) from the Authentication Upgrade checklist (select Administration > Authentication Upgrade).
    • If you are configuring SSO after the upgrade, select System Management > Security > Authentication > SSO Configuration.
    • If you are configuring SSO after the upgrade, select Main > Administration > Identity SSO Config.
  2. (HR Administrator role) Do one of the following:
    • (If the tenant uses SSO, do not skip this step.) Select the Configure SSO button and click Configure SSO. The Configure SSO tab opens.
    • (Recommended for production tenants only if you want to skip SSO configuration) If SSO is configured but not used, and this is a production tenant, click Switch to direct login.
    • (Not available in production tenants) If SSO is not configured, and this is a non-production tenant, click Skip SSO. This is recommended for non-production tenants. You can skip all of the following steps.
  3. (HR Administrator role) If you selected Configure SSO, the SSO Connections tab opened. Click Add SSO.
  4. If you use any of the following IDPs, click the appropriate link below. Otherwise, go to the next step.
  5. Note:

    The values of the UKG ProUKG Pro Workforce Management Username and the SAML unique response from the identity provider must be identical because these are used to grant access. Verify the Username with the other administrator. Example: If the Username is name@company.com, the SAML response from the IDP must also be name@company.com.

    (IT Member role) Create a new SSO Connection in your IDP and do not edit the existing SSO connection that is being used currently. Generate the Metadata URL in the application for the identity provider (IDP). You must have the Entity ID and Assertion URL to generate the Metadata URL, so use placeholder values for these fields until you can get the real values from the HR Administrator in the next step.
  6. (HR Administrator role) Configure the following:
    1. Enter the Configuration name in the Button label field. This name identifies the SSO configuration to the employees. It must be unique, contain no spaces, and should include "SSO" and "UAT" or "PROD". Examples: UKGSSOUAT for the UAT, NPR, or Test environment and UKGSSOPROD for the Production environment.
    2. In Current IdP Information, select Metadata and enter the Metadata URL that you got from the IT Member.
    3. In Security settings, select both Notify IdP about callbacks and Sign SAML request to establish the most secure connection.
    4. In Bindings, select HTTP POST (recommended) to send data securely in the body of the request.
    5. Keep the default NameId for the SAML assertion attribute. Normally, you do not change this value.
    6. Click Next.
    7. Copy the Metadata URL and give it to the IT Member.
  7. (IT Member role) Configure the new IDP as follows:
    1. Enter or paste the Metadata URL in the Address bar of a browser.
    2. From the XML file that opens, copy the Entity ID and Assertion Location attributes for your IDP fields.
    3. Replace the placeholder values that you entered earlier with these values.
  8. (IT Member role) Add the user accounts that need to access UKG ProUKG Pro Workforce Management. Otherwise, the users will be able to enter their SSO credentials but will be denied access by the IDP.
  9. (HR Administrator role) Test the connection from UKG ProUKG Pro Workforce Management as follows:
    1. Click Test connection to open the tab.
    2. In the IDP login page, log in with your user credentials.
    3. If the login failed, close this tab and verify with the IT Member whether they added the user account for the account that you are testing. If the user account was added, but the error persists, for the moment you can select I tested the SSO connection successfully and click Next.
    4. If the login succeeded, select I tested the SSO connection successfully and click Next.
  10. (HR Administrator role) Map the vanity URL to the SSO connection as follows:
    1. Select the vanity URL to use for this SSO connection. All available URLs are listed.
    2. Click All Done!
  11. (HR Administrator role) (Optional) To test, edit, or delete a connection, click the three vertical dots button for that SSO connection and select Test connection, Edit, or Delete.
  12. (HR Administrator role) (Optional) If Test Connection failed earlier, the IT Member added the user account, but the error persists, click the three dots and select Edit.
    1. Remove the Metadata URL value that the IT Member provided, copy the URL again, and paste the same value again in Metadata URL.
    2. Click Next.
    3. If Test Connection continues to fail, make sure that the Entity ID and Assertion Location values are entered correctly in the IDP.
    4. If the error persists, contact UKG for support.
  13. (HR Administrator role) To add another SSO connection, click Add SSO and repeat the previous steps.
  14. (HR Administrator role) When all SSO connections are tested successfully, return to the Authentication Upgrade tool and expand Configure your Single Sign-On (SSO) connection (Required) to refresh and check the settings.
    1. Select Administration > Authentication Upgrade.
    2. Expand Configure your Single Sign-On (SSO) connection (Required) .
    3. Click Refresh. Make sure that the check mark turns green.

Configure SSO with Azure

How to configure SSO for UKG Authentication and Microsoft AzureTM.

  1. Note: The following people are required to complete this configuration: An IT Member who has access to Microsoft Azure, and an HR Administrator who has access to the SSO tool for the UKG Pro suiteUKG Pro Workforce Management. Each of the following steps indicates which person completes that step. Alternatively, a single administrator who has access to both systems can complete this configuration.
    (IT Member role) Log in to Azure.
  2. (IT Member role) Create a new Enterprise Application instance.
  3. (IT Member role) Create the Metadata URL as follows:
    1. Identifier (Entity ID): The placeholder value of http://[companySsoURL].mykronos.com. If you are configuring a UAT tenant, copy the SSO URL from the existing UAT SSO configuration. If you are configuring a PROD tenant, copy the SSO URL from the PROD configuration. If the SSO URL is not available, enter a placeholder value.
    2. Reply URL (Assertion Consumer Service URL): Also the placeholder value of http://[companySsoURL].mykronos.com or a placeholder value.
    3. Sign on URL: Enter the actual value of the SSO URL in http://[companySsoURL].mykronos.com. To verify whether the URL is the correct SSO URL, enter it in the Address bar of a browser and see if it links to an SSO page. If the URL does not link, enter a placeholder value and wait for the HR Administrator to configure Metadata URL and give you the SSO URL value.
  4. (IT Member role) Generate the Metadata URL and give it to the HR Administrator.
  5. (HR Administrator role) Log in to the UKG Pro suiteUKG Pro Workforce Management.
  6. (HR Administrator role) Do either of the following:
    • If you are configuring SSO before the upgrade, select Main Menu > Authentication Upgrade, Then, select Configure your Single Sign-On (SSO) connection and click Configure SSO.
    • If you are configuring SSO after the upgrade, select System Management > Security > Authentication > SSO Configuration. Then, select and click Configure SSO.
    • If you are configuring SSO after the upgrade, select Main > Administration > Identity SSO Config. Then, select and click Configure SSO.
  7. (HR Administrator role) Configure the following:
    1. Enter the Configuration name in the Button label field. This name identifies the SSO configuration to the employees. It must be unique, contain no spaces, and should include "SSO" and "UAT" or "PROD". Examples: UKGSSOUAT for the UAT, NPR, or Test environment and UKGSSOPROD for the Production environment.
    2. In Current IdP information, select Metadata and enter or paste the Metadata URL for Azure.
    3. In Security settings, select both Notify IdP about callbacks and Sign SAML request to establish the most secure connection.
    4. In Bindings, select HTTP POST (recommended) to send data securely in the body of the request.
    5. Keep the default NameId for the SAML assertion attribute. Normally, you do not change this value.
    6. Click Next.
  8. (HR Administrator role) Copy the Metadata URL and give it to the IT Member.
  9. (IT Member role) Paste the Metadata URL in the Address bar of a browser.
  10. (IT Member role) From the XML file that opens, copy the entityID and Location for your IDP fields.
  11. (IT Member role) Return to Azure and do the following:
    1. Replace the Identifier (Entity ID) with the entityID from the XML file.
    2. Replace the Reply URL (Assertion Consumer Service URL) with the Location from the XML file.
    3. Assign the appropriate Users and Groups to the application.
  12. (HR Administrator role) In the UKG Pro suiteUKG Pro Workforce Management, do the following:
    1. Click Test Connection to open the tab.
    2. Log in with your user credentials.
    3. If the login failed because of an incorrect configuration in Azure, the error shows Microsoft or your organization's logo. Ask the IT Member to check that the User, Group, Entity ID, Assertion URL, and Sign-on URL are correct in Azure. Close the tab.
    4. Select I configured the IdP by entering the metadata URL in the settings and click Next.
    5. Map the vanity URL to the SSO connection as follows: Select the vanity URL to use for this SSO connection. All available URLs are listed. Click All Done! If the IT Member needs the SSO URL, copy this URL and give it to the IT Member.
  13. (HR Administrator role) (Optional) To test, edit, or delete a connection, click the three vertical dots button for that SSO connection and select Test Connection, Edit, or Delete.
  14. (HR Administrator role) To add another SSO connection, click Add SSO and repeat the previous steps.
  15. (HR Administrator role) (Optional) If Test Connection failed earlier, the IT Member added the user account, but the error persists, click the three dots and select Edit.
    1. Remove the Metadata URL value that the IT Member provided, copy the URL again, and paste the same value again in Metadata URL.
    2. Click Next.
    3. If Test Connection continues to fail, make sure that the Entity ID and Assertion Location values are entered correctly in the IDP.
    4. If the error persists, contact UKG for support.
  16. (HR Administrator role) When all SSO connections are tested successfully, return to the Authentication Upgrade tool and expand Configure your Single Sign-On (SSO) connection (Required) to refresh and check the settings.
    1. Select Administration > Authentication Upgrade.
    2. Expand Configure your Single Sign-On (SSO) connection (Required) .
    3. Click Refresh. Make sure that the check mark turns green.

Email Addresses for the Authentication Upgrade

Required and optional email addresses for UKGAuthentication.

Because UKG Authentication allows the use of email addresses in addition to usernames for logging in, so no one can share or duplicate email addresses for the purpose of logins. Each person must have their own, unique Sign-On Email address.

The following email fields are available:

  • Email (not required, can be blank): Alerts and workflow notifications go to this email address. This Email address can be duplicated in multiple person records.

  • Sign-On Email (new and optional): Use this email address for Login, MFA, and Forgot Password functions. This address must be unique, and by default, the address is copied automatically from the Email field but only if that address is unique. If the Email field does not contain a unique address, Sign-On Email is blank. You can enter a Sign-On Email address in this field or by way of an API; then, Sign-On Email does not auto-populate from the Email address. If Sign-On Email is left blank, Login, MFA, and Forgot Password functions cannot be used.
    Note: To receive multi-factor authentication (MFA) access codes without duplicate email addresses, use the MFA Policy to get the code by Authenticator or SMS.

Upgrade Email Addresses

How to upgrade email addresses for the upgrade to UKG Authentication.

Invalid emails

Note: Only for user accounts that use Basic Authentication.
  1. Expand Invalid emails to show the count of invalid email addresses.
  2. Click View invalid emails.
  3. Review the Dataview of invalid email addresses.
  4. (Optional) Click Share to Print the list or Export the list to a comma-separated values (CSV) file.
  5. To update email addresses, select Main Menu > Maintenance > People Information for each person and enter a valid Email address.

Phone Numbers for the Authentication Upgrade

Required phone number format for the upgrade to UKG Authentication.

All user accounts must have a valid phone number as follows:

  • Start the number with a plus (+) sign.

  • Use the complete number, including the country and area codes.

  • Do not use spaces or special characters.

Example: Format a phone number such as +1 (555) 555-1212 as +15555551212.

Upgrade Phone Numbers

How to correctly format phone numbers for the upgrade to UKG Authentication.

Invalid phone numbers

Note: Only for user accounts that use Basic Authentication.
  1. Expand Invalid phone numbers to show the count of invalid phone numbers.
  2. Click View invalid phone numbers.
  3. Review the Dataview of invalid phone numbers.
  4. (Optional) Click Share to Print the list or Export the list to a comma-separated values (CSV) file.
  5. To update phone numbers, select Main Menu > Maintenance > People Information for each person and enter a valid Phone number as follows. Use the complete number: start with the plus sign (+), then the country and area code, but do not use spaces or special characters. Example: Format a phone number such as +1 (555) 555-1212 as +15555551212.

Upgrade Authentication

How to run the Authentication Upgrade Tool to upgrade to UKG Authentication.

Main Menu > Authentication Upgrade

  1. Before you start, check the following:
    1. Make sure that your function access profile (FAP) allows you to access the Upgrade Tool menu item.
    2. After the upgrade, the system will use your current Vanity URL, or will create a new Vanity URL if one does not exist.
  2. Log in.
  3. Select Main Menu > Authentication Upgrade.
  4. Note: The upgrade tool will provide a list of email addresses that are not unique and usernames that are not valid. The Primary email address and primary phone number fields are used for multi-factor authentication (MFA) tokens.
    Complete the data clean-up of usernames, default passwords, SSO configuration, email addresses, and phone numbers as listed in the Authentication Pre-Upgrade Checklist.
  5. Click Start Upgrade. The upgrade usually lasts from 12 to 30 minutes to update all services and systems. If the downtime lasts longer than 30 minutes, shared services may be doing maintenance or other updates. Try again to start the upgrade.
  6. Test the results as follows:
    1. Select Log in using Direct Login flow with a number of user accounts.
    2. If you use SSO, select Log in using SSO flows.
    3. Select Navigate between products and add-on products.
    4. Select Initiate API integrations.
  7. Do the following to wrap up the upgrade process:
    1. Update saved bookmarks and deep links to the new Vanity URL.
    2. Provide the new Vanity URL to employees.
    3. Bookmark the new Login screen after you successfully log in and remove the bookmark to the previous Login screen.
    4. If a saved bookmark starts with cus or dcus, use the Vanity URL which is https://[value].mykronos.com. The Login screen is in the center of the page after the upgrade completes successfully.
    5. Remind employees of potential changes to their usernames.
    6. Update email addresses.
    7. Verify that multi-factor authentication (MFA) is working successfully with the configured email addresses and phone numbers.
  8. If you encounter significant issues after the upgrade is completed, you have 7 days to roll back the upgrade. Click Rollback Everything or Rollback API Upgrades.