Configure UKG Workforce Central for single sign-on
Single sign-on or SSO is a method of access control that enables a user to log in once and gain access to the resources of multiple software systems without being prompted to log in again. It lets users log in to their company portal page and be pre-authenticated, without needing to re-enter a user name and password.
Although there are many ways to configure single sign-on, three of the most common methods are:
- Security Assertion Markup Language (SAML) — An XML-based open protocol for exchanging authentication and authorization data between security domains
- Computer Associates’ eTrust® SiteMinder® — A third-party commercial product that passes user credentials within an unencrypted HTTP header
- Integrated Windows Authentication (IWA) — A method of single sign-on for Windows-only environments. It provides a form of user authentication for users who all belong to shared-trust Windows domain of domains based on Windows Active Directory.
This document describes how to enable these methods of single sign-on with UKG Workforce Central. If you are using a different application to implement single sign-on, there might be differences in the procedures.
A large number of system settings are available to implement various single sign-on methodologies. For a summary of all single sign-on system settings, see SAML/SiteMinder System Settings Summary
Notes
- When UKG Workforce Central is used in a single-sign-on environment, password recovery is handled by the SSO infrastructure. Because of this, you should disable the UKG Workforce Central password recovery and security question:
- Log on as an administrator.
- Select Setup > System Configuration > System Settings.
- Select the Security tab.
- Set the following setting to false:
- global.security.authentication.question.RequireSecurityQuestion
- Because single sign-on methods can significantly increase the header size, you may need to increase the packetsize parameter of the AJP connector.
- Stop UKG Workforce Central if already running.
- With a text editor such as Notepad, open the following file:
- \\Kronos\jboss\wfc\configuration\standalone.xml
- Add the following line, changing **** to the desired packet size:
- <system-properties>
- <property name="org.apache.coyote.ajp.MAX_PACKET_SIZE" value="****"/> </system-properties>
- Close the file, save your edit, and then restart UKG Workforce Central.
Important
Because SAML configurations can vary significantly, this description focuses on explaining only the UKG Workforce Central part of the configuration. It assumes that you have configured SAML and that you understand your configuration.
UKG Workforce Central requires that your IdP signs the assertion within each response.
The SAML 2.0 specification defines three roles: the principal (typically a user), the identity provider or IdP , and the service provider or SP (typically UKG Workforce Central).
The SAML module of UKG Workforce Central handles the SAML response and allows access to the requested resource. You can configure UKG Workforce Central to use IdP-initiated SAML or SP-initiated SAML, with or without encryption.
- In IdP-initiated SAML, the authentication process is initiated by the IdP sending an unsolicited SAML response to the SP.
- In SP-initiated SAML, the SP generates an AuthnRequest that is sent to the IdP as the first step in the authentication process and the IdP then generates a SAML response.
- A Public SP X.509 certificate is used by the IdP to encrypt a randomly generated symmetric key that is used to encrypt the SAML assertion. Note that only full assertion encryption is supported.
- The SP-authentication SAML module uses a private key that is associated with the X.509 public certificate to decrypt the encrypted key. This produces the randomly generated symmetric key. The symmetric key is then used to decrypt the actual encrypted data.
- The http://www.w3.org/2001/04/xmlenc#rsa-1_5 algorithm is used for encryption of the randomly generated symmetric key using SP public key.
- The http://www.w3.org/2001/04/xmlenc#aes128-cbc algorithm is used to encrypt the assertion using the randomly generated symmetric key.
- CBC and GCM block cypher encryption modes are supported. Signature validation and encryption support includes the following:
- Signature algorithms: rsa-sha1, rsa-sha256, dsa-sha1
- Key encryption algorithms: rsa-1_5, rsa-oaep-mgf1p
- Data encryption algorithms: aes128-cbc, aes128-gcm
- For assertion encryption, UKG Workforce Central needs the private key to be in pk8 format with the .pk8 file extension.
- Starting in UKG Workforce Central v8.1.2, SAML responses must be signed, in addition to the inner SAML assertions. This default behavior reflects security best practices. You can, however, disable this behavior by adding the following setting to the custom_wpksite.properties file (located in \instance\applications\wpk\properties) on each application server:
- hidden.security.sso.saml.requiresignedresponses = false
To configure UKG Workforce Central for single sign-on with IdP-initiated SAML authentication, complete the following steps.
Note: A large number of system settings are available to implement various single sign-on methodologies. For an overview of all single sign-on system settings, see SAML/SiteMinder System Settings Summary.
- Log on to UKG Workforce Central as SuperUser and select Setup > System Configuration > System Settings and click the Security tab.
- Edit the following settings to enable single sign-on with SAML:
- site.security.singlesignon — Enable single sign-on by setting this value to true.
- site.security.singlesignon.module — Enter the name of the SAML SSO Logon module. For example:
- com.kronos.wfc.platform.security.business.authentication.ssoplugin.SSOSamlSubject
- Enter the SAML-specific settings as follows. You must specify the location of the certificate and/or metadata file. The SAML module requires an IdP certificate to validate the SAML response returned by the IdP. On its first invocation, the SAML module attempts to load the certificate from the certificate file. If the certificate file is not present (no value specified in the setting), it attempts to load the certificate from the metadata file. When the certificate is loaded, it is cached for performance reasons.
- (Optional) site.security.sso.saml.attribute.name— Enter the SAML attribute name in the response from the IdP.
- An attribute statement asserts that a subject is associated with certain attributes. An attribute is a name-value pair. Relaying parties use attributes to make access-control decisions.
- If an attribute name is provided in this system setting and the attribute name is not present in the SAML response, an error is generated.
- site.security.sso.saml.lib.path — Enter the base path for the certificate and metadata file. For example:
- c:\saml
- site.security.sso.saml.certificate.file.path — Enter the name and path of the certificate file provided by the IdP. This path is relative to the location of site.security.sso.saml.lib.path. The signature validation pubic key needs to be DER encoded (binary non ASCII). For example:
- cacert.pem
- site.security.sso.saml.IdPmetadata.file.path — Enter the name and path of the metadata file provided by the IdP. This path must be relative to the location of site.security.sso.saml.lib.path. The metadata file can also hold the certificate. For example:
- meta\metadata.xml
- If a certificate is not available, either from certificate file or the metadata file, an error is generated. See SAML Error messages for more information.
- Configure the following timeout settings:
- site.security.singlesignon.timeout — This setting controls whether or not sessions can time out. If set to true, the session can time out; if set to false, the session cannot time out.
- site.security.singlesignon.show.timeout.warning — This setting controls a warning box that allows users to extend a session that is about to time out. If set to true, the warning box appears; if set to false, the warning box does not appear.
- Edit the following settings to control where users will be redirected when a timeout occurs:
- site.security.SSOTimeoutRedirectURL — Enter the SSO timeout redirect URL. If you use a non-UKG Workforce Central URL, you must enter the full URL, for example, http://www.google.com. The default URL is /wfc/logonWithUID.
- site.security.ESSsinglesignon.timeouturl — Enter the logoff address or URL to use when an ESS single sign-on session times out. If you use a non-UKG Workforce Central URL, you must enter the full URL, for example, http://www.google.com. The default address is /wfc/applications/wtk/html/ess/logoff.jsp.
- Edit the following settings to control where users will be redirected when a user logs off:
- site.security.singlesignon.logoffurl — Enter the logoff address or URL to use when a user logs out. The default address is /wfc/logon/logonWFC.html.
- site.security.ESSsinglesignon.logoffurl — Enter the logoff address or URL to use when a user logs out of an ESS single sign-on session. The default address is /wfc/applications/wtk/html/ess/logoff.jsp.
- site.security.singlesignon.hide.logoff — This setting controls the Logoff/Signout links in the user interface. If set to false, the Logoff/Signout link appears. If set to true, the Logoff/Signout link does not appear. Setting this to true avoids issues when the user clicks the browser’s Back button.
- Click Save.
SP-initiated SAML is stronger than IdP-initiated SAML and includes deep link support. Key features include the following:
- SAML 2.0 support using HTTP POST binding (not all optional components such as metadata are supported)
- For SP-initiated SSO support from mobile devices, the site.security.sso.saml.idpendpoint property must be set to process SAML requests.
- IdP- and SP- initiated SSO modes can be used concurrently. Users can link directly to the service provider or from links set up in a company portal.
- The digital signature of an assertion can be validated using the non-anchored trust model.
- Decrypt assertions in SP-initiated mode is supported automatically.
To configure UKG Workforce Central for single sign-on with SP-initiated SAML authentication, provide the following information. Note that SP-initiated SAML authentication requires the same system settings as IdP-initiated SAML authentication in addition to several SP-specific settings.
- Complete the steps outlined in Configure the suite for IdP-initiated SAML authentication.
- Edit the following settings:
- site.security.sso.saml.authentication.request.privateKey.file.path — (Optional) Enter the name and path of the privateKey file to sign a SAML SP-initiated authentication request. The path is relative to the library path. If this value is null or empty, UKG Workforce Central will send unsigned SAML authentication requests to the IdP server.
- site.security.sso.saml.splogon — Select true to enable the SP-initiated SSO service.
- site.security.sso.saml.idpendpoint — Enter the URL of the resource that redirects the user to a logon page and consumes the SAML authentication request. This is typically the URL to the IdP server, for example:
- http://server:port/saml2idp.server/SAMLEndpoint
- You can also add a parameter to the IdP end point, as shown in bold in the following example:
- https://server:port/saml2idp.server/startSSO.ping?PartnerSpid=KRNOS_UAT
- site.security.sso.saml.mobile.idpendpoint — Enter the URL of the resource that redirects the user to a mobile logon page.
- site.security.sso.saml.spendpoint — Enter the URL of the resource that consumes the SAML response coming from the IdP server. This is the SP server, which is UKG Workforce Central. For example:
- http://server:port/instance/logonWithUID
- site.security.sso.saml.mobile.spendpoint — Enter the URL of the resource that consumes the SAML response coming from the IdP server after a request issued from a mobile device.
- site.security.sso.saml.providername — Enter the name of the service provider. This is typically the machine name of the UKG Workforce Central application server. For example:
- prod-80-ksi
- site.security.sso.saml.issuer — Enter the name of the service provider that issues the requests. This is typically the name of machine where the UKG Workforce Central application server resides. For example:
- prod-80-ksi
- Edit the following settings to control where users will be redirected when a timeout occurs:
- site.security.sso.saml.splogon.exception.logonurl — Alternate URL for logon when an exception occurs (for administrator use only), for example, wfc/logon/logonWFC.html.
- (Optional) site.security.sso.saml.splogon.exception.url.param.name — Enter a parameter for when an exception occurs. For example, the following URL navigates directly to UKG Workforce Central:
- IOS — http://servername/wfc?splogonexception=true
- Desktop — http://servername/wfc/logon?splogonexception=true
- site.security.sso.saml.authentication.request.relaystate.param.name — Parameter name for the original link in the SAML authentication request. This was formerly called a relaystate link or deep link.
- Click Save.
If desired, you can configure UKG Workforce Central for encrypted assertions with either IdP- or SP- initiated SAML.
- Configure UKG Workforce Central for either IdP- or SP-initiated SAML as outlined in Configure the suite for IdP-initiated SAML authentication or Configure the suite for SP-initiated SAML authentication.
- Edit the following settings:
- site.security.sso.saml.encryption.enable — To enable encryption of the SAML message, select true.
- site.security.sso.saml.decryption.privateKey.file.path — Enter the name and path of the privateKey file for SAML assertion decryption. The path is relative to the library path. It is typically in the same location as the certificate.
- Click Save.
When using SAML, the user accesses a “customer portal” that authenticates the user against the SAML IdP. When authentication is successful, the portal redirects control to the UKG Workforce Central URL */logonWithUID, for example:
http://server/instance/logonWithUID
For Workforce Mobile users, the logon is:
http://server/instance/mobile/logonWithUID
Multifactor authentication combines two or more independent credentials: what the user knows (password), what the user has (security token), and what the user is (biometric verification).
If multifactor authentication is required, UKG Workforce Central must be integrated with a third-party identity provider. This identity provider must perform Multifactor Authentication before redirecting the user to UKG Workforce Central.
If MLSI (Multiple Language on a Single Instance) is used at your site, users who log on using SAML can log on in a language other than the one specified in their Locale Policy only if the IdP supports adding URL parameters to the SP endpoint URL:
/InstanceName/logonWithUID?LOGON_LOCALE_POLICY=<LANGUAGE_ID>
This URL sets the language of the user’s session to the LANGUAGE_ID. You can retrieve the list of language IDs from the LOCALEPROFILE table in the database by using an XML API call.
Note: Because this functionality is not widely supported and is unavailable in most IdPs, the recommended practice is to set a default Locale Profile appropriate for each user in the People Editor.
Error message | Displays In | Description | Corrective Action | ||
UI | Log | Exception Trace | |||
SAML token validation failed. Please contact your system administrator. |
X |
|
|
Generic message that displays in the UI regardless of the underlying failure or error. | Check the logs for more information about the underlying reason for the failure. |
SAML Response cannot be found |
|
X |
|
The response from the IdP is not empty or null. UKG Workforce Central cannot proceed without SAML response. | Contact the IdP administrator to validate the IdP configuration. |
Signature can not be found in SAML Response! | X | The response from the IdP does not contain a signature, or the assertion was not signed. UKG Workforce Central cannot proceed without correctly signed assertions in the SAML response. | Contact the IdP administrator to validate the IdP configuration. Note that this error message only appears in v8.1.0 and v8.1.1. It will not appear in v8.1.2 and later. | ||
Signature validation exception |
|
X | X | The signature in the SAML response cannot be validated against the certificate information retrieved from certificate or metadata file. This happens when the signature information in the SAML response is not in synch with the certificate read from the files. |
Contact the IdP administrator to get the latest certificate and metadata files. Make sure that the files are in the paths identified in the Security tab of Setup and restart UKG Workforce Central. |
No AttributeStatement found in SAML response. |
|
X |
|
(Optional) The SAML response can contain the principal in the Attribute field. Only if you use the Attribute field, the site.security.sso.saml. attribute.name system setting must be set. The error is generated if this system setting is set, but the response does not use the Attribute field. |
Log on to UKG Workforce Central, select Setup, click the Security tab, and remove the value for:site.security.sso.saml attribute.name |
No Attribute found in SAML response. |
|
X |
|
||
<<Attribute Name>> contains WFC logon is empty! |
|
X |
|
||
<<Attribute Name>>, can not be found! |
|
X |
|
||
Subject can not be found! |
|
X |
|
The subject is not available in the assertion of the SAML response. | Contact the IdP administrator. |
NameId can not be found! |
|
X |
|
The response contains the subject, but the NameId is missing. | |
Subject NameID is empty! |
|
X |
|
The principal from the NameId is not available in the SAML response. | |
Certificate source is not set, Cannot retrieve certificate for signature verification.
Certificate Not found. Cannot create Signature Validator. So, returning error |
|
X |
|
The SAML module cannot create the Signature Validator because the certificate is not available from either the certificate file or the metadata file. | Contact the IdP administrator for the correct certificate and/or metadata file. |
IDP Metadata file Path is not set correctly: METADATA_FILE_PATH= <<metadata file path>> LIB_PATH = <<library path>> |
|
X |
|
The metadata file path is not configured in System Settings. | Log on to UKG Workforce Central, select Setup, click the Security tab, and enter the correct path in site.security. sso.saml.IdPmetadata.file.path. |
Cannot create Filesystem Metadata Provider: <<metadata file path>> |
|
X | X | The SAML module attempts to read the signature validation information from either the certificate file or metadata file. These errors occur when all of the following occurs:
|
If the certificate file is available, try using it for creating the Signature Validator. This can be done by setting the value for site.security. sso.saml.certificate.file.path.If the certificate file is not available, contact the IdP administrator to obtain the valid metadata file or certificate file. |
Cannot retrieve Entity Descriptor from FilesystemMetadataProvider |
|
X | X | ||
EntityDescriptor cannot be found |
|
X |
|
||
IDPSSODescriptor can not be found! |
|
X |
|
||
KeyDescriptor for can not be found! |
|
X |
|
||
KeyDescriptor for signing can not be found! |
|
X |
|
||
X509Data can not be found |
|
X |
|
||
X509Certificate can not be found! |
|
X |
|
||
Certificate file Path is not set correctly: CERT_FILE_PATH= <<certificate file path>> LIB_PATH = <<library path>> |
|
X |
|
The certificate file path is not configured in the site.security.sso.saml.certificate.file.path setting and the metadata file path is not configured in the site.security.sso.saml.IdPmetadata.file.path setting. | Log on to UKG Workforce Central, select Setup, click the Security tab, and enter the correct path in site.security.sso.saml.certificate.file.path. |
Certificate file Not found: <<certificate file path>> |
|
X | X | The system setting site.security.sso.saml.certificate.file.path points to a location that does not contain the required file. | |
Certificate file cannot be parsed: <<certificate file path>> |
|
X | X | The certificate file specified by the site.security.sso. saml.certificate.file.path system setting is corrupt or invalid. |
Contact the IdP administrator to obtain the correct certificate file or log on to UKG Workforce Central, select Setup, click the Security tab, and enter the correct path in site.security.sso.saml.certificate.file.path. |
time validity failed | X | The time window provided in the assertion and the assertion subject is validated with the current datetime. This happens to prevent a replay attack. | Contact the IdP administrator. | ||
spEndPoint Property Missing, whereas Destination is present in assertion XML! | X | Warning: Prints in the UKG Workforce Central logs only. The site.security.sso.saml.spendpoint system setting is left blank in UKG Workforce Central but the destination attribute is present in the assertion XML. | Log on to UKG Workforce Central, select Setup, click the Security tab, and enter the correct path in the site.security.sso.saml.spendpoint system setting. | ||
Destination <<Attribute Name>>, does not match the expected destination of site.security.sso.saml.mobile.spendpoint. | X | The site.security.sso.saml.mobile.spendpointsystem setting does not match the destination attribute coming in the SAML assertion. This is for mobile only. | Contact the IdP administrator. | ||
Destination <<Attribute Name>> does not match the expected destination of site.security.sso.saml.spendpoint. |
X | The site.security.sso.saml.mobile.spendpoint system setting does not match the destination attribute coming in the SAML assertion. | Contact the IdP administrator. | ||
spEndPoint Property Missing, whereas Recipient is present in assertion XML! | Warning: Prints in the UKG Workforce Central logs only. The site.security.sso.saml.spendpoint system setting is left blank in UKG Workforce Central but the recipient attribute is present in the assertion XML. | Log on to UKG Workforce Central, select Setup, click the Security tab, and enter the correct path in the site.security.sso.saml.spendpoint system setting. | |||
Recipient <<Attribute Name>> does not match the expected destination of site.security.sso.saml.mobile.spendpoint. | X | The site.security.sso.saml.mobile.spendpoint system setting does not match the recipient attribute in the SAML assertion. This is for mobile only. | Contact the IdP administrator. | ||
Recipient <<Attribute Name>> does not match the expected destination of site.security.sso.saml.spendpoint. | X | The site.security.sso.saml.mobile.spendpoint system setting does not match the recipient attribute in the SAML Assertion. | Contact the IdP administrator. | ||
Issuer in Assertion is not present, setting Issuer from response! | X | The issuer is included in the saml:Assertion tag. Only use the one outside of the saml:Assertion if it does not exist within the saml:Assertion tag. | Nothing to do, just logging. | ||
IDPIssuer Property Missing, whereas IDPIssuer is present in assertion XML! | X | Warning : Prints in the UKG Workforce Central logs only. The site.security.sso.saml.IDPissuer system setting is left blank in UKG Workforce Central but the destination attribute is present in the assertion XML. | Log on to UKG Workforce Central, select Setup, click the Security tab, and enter the correct path in the site.security.sso.saml.IDPissuer system setting. | ||
Issuer <<Attribute Name>> does not match the expected issuer for site.security.sso.saml.IDPissuer | X | The site.security.sso.saml.IDPissuer system setting does not match the issuer attribute in the SAML assertion. | Contact the IdP administrator. | ||
Signature can not be found for SAML response! | X | The SAML response was not signed. | Contact the IdP administrator. | ||
SAML Response signature is not valid | X | X | The SAML response was improperly signed by the IdP. | Contact the IdP administrator. | |
Signature can not be found for SAML assertion! | X | The SAML assertion was not signed. | Contact the IdP administrator. | ||
SAML Assertion signature is not valid | X | X | The SAML assertion was improperly signed by the IdP. | Contact the IdP administrator. |
Computer Associates eTrust® SiteMinder®SiteMinder is a third-party security and management product for enterprise Web applications with a centralized security infrastructure for managing user authentication and access.
Important: Because SiteMinder configurations can vary significantly, this section focuses on explaining only the UKG Workforce Central part of the configuration. This document assumes that you have installed SiteMinder and that you understand your SiteMinder configuration. For information about configuring SiteMinder, refer to the SiteMinder documentation.
Workforce Mobile supports SiteMinder, but you must configure SiteMinder to manage the following URL:
http://webserver/instance/smmobile/logonWithUID
To configure SiteMinder with UKG Workforce Central, complete the following steps.
UKG Workforce Central requires a file called SSOSiteMinder.properties. Because this file is not provided by default, you must create it and add the following information:
- Set the location of the SiteMinder SSO log file, for example:
- sso.log.file={WFC.externaldir}\\logs\\SSOSiteMinder.log
- Set the logging level (NOLOG, DEBUG, INFO, WARNING, or ERROR) to DEBUG, for example:
- sso.log.level=DEBUG
- Set the sso.principal.key to identify the principal/user name that has been authenticated by SiteMinder. The module will search for the key first in the HTTP header, then in the cookie, and last in the HTTP body.
Note: Setting the sso.principal.key correctly for your environment is extremely important. The variable (SMUSER or SM_USER) is found in the HTTP header and is used to identify the user name passed to UKG Workforce Central. The default legacy variable was SMUSER, where other sites using SiteMinder v6.0 may be using SM-USER or any other configured variable (for example, SSO_USERNAME).
- For example, if your environment uses the variable SMUSER, you would enter:
- sso.principal.key=SMUSER
Sample SSOSiteMinder.properties file:
# Attributes of this property file
SSOSiteMinder.fName=SSOSiteMinder
SSOSiteMinder.ConfigurationSource=PROPERTIES_FILE
SSOSiteMinder.verbose=true
SSOSiteMinder.canEdit=false
SSOSiteMinder.canView=false
SSOSiteMinder.required=true
# The name of the log file for SiteMinder SSO
sso.log.file={WFC.externaldir}\\logs\\SSOSiteMinder.log
# The logging level, (NOLOG,DEBUG,INFO,WARNING,ERROR)
sso.log.level=DEBUG
# The key used to identify the principal/username that has been
# authenticated by SiteMinder. This module will search for the key:
# First in the HTTP Header
# Second in the Cookie.
# Last in the HTTP Body
# This will look for the HTTP header "SMUSER=<username>"
sso.principal.key=SMUSER
# An example of a another key in the HTTP Header
# that identifies the authenticated user. This key has been configured in
# a SiteMinder response.
#sso.principal.key=WFCUSER
# An example of a another key in the HTTP Cookie that identifies
# the authenticated user.
# This key has been configured in a SiteMinder response.
#sso.principal.key=WFCCUSER
# The key used to identify the credential/password that has been
# authenticated by SiteMinder. This module will search for the key:
# First in the HTTP Header.
# Second in the Cookie.
# Last in the HTTP Body
# NOTE: ALL CURRENTLY KNOWN SITEMINDER AUTHENTICATION METHODS DO NOT
# PASS CREDENTIAL TO THEIR APPS. THIS IS ONLY INCLUDED FOR POSSIBLE
# FUTURE USE.
sso.credential.key="DUMMY_PASSWORD"
- Copy SSOSiteMinder.properties file to the following directories for all instances that connect to the same database:
- \\Kronos\instance\applications\wcb\properties
- \\Kronos\deployments\instance\wfp_staging\app_server\
applications\wcb\properties - Rebuild each instance.
The recommended settings to configure UKG Workforce Central for single sign-on with SiteMinder are as follows.
Note: A large number of system settings are available to implement various single sign-on methodologies. For an overview of all single sign-on system settings, SAML/SiteMinder System Settings Summary
- Log on to UKG Workforce Central as SuperUser and select Setup > System Configuration > System Settings and click the Security tab.
- Edit the following settings to enable single sign-on with SiteMinder:
- site.security.singlesignon — Enable single sign-on by setting this value to true.
- site.security.singlesignon.module — Enter the name of the Single Sign-on module. The default value for SiteMinder is:
- com.kronos.wfc.platform.security.business.authentication.ssoplugin.
SSOSiteMinderSubject - site.security.singlesignon.module.properties — Enter the name of the property file (created in step 1) that contains the configuration information used by the single sign-on module:
- <Kronos home>/instance/applications/wcb/properties/
SSOSiteMinder.properties
- Configure the following values:
- site.security.singlesignon.timeout — Set to false. This setting controls whether or not sessions can time out. If set to true, the session can time out; if set to false, the session cannot time out. This setting is used by classic, ESS, and navigator user interfaces.
- site.security.singlesignon.show.timeout.warning — Set to false. This setting controls a warning box that allows users to extend a session that is about to time out. If set to true, the warning box appears; if set to false, the warning box does not appear. This setting is used by classic, ESS, and navigator user interfaces.
- site.security.singlesignon.hide.logoff — Set to true. This setting controls the Logoff/Signout links in the user interface. If set to false, the Logoff/Signout link appears; if set to true, the Logoff/Signout link does not appear. Setting this to true avoids issues when the user clicks the browser’s Back button.
- Verify that the ISAPI SiteMinder Agent Filter precedes the ISAPI JBoss Filter. You can verify this using the Microsoft Management Console.
Note: This section assumes that you have installed SiteMinder and that you understand the basic SiteMinder configuration. For information about configuring SiteMinder, refer to the SiteMinder documentation.
Use the SiteMinder Policy Server to configure SiteMinder to work with the following types of UKG Workforce Central URLs:
- Non-logon URLs
- Logon URLs
- Navigator framework URL
- HTML Client URL
You do this by completing the following tasks.
- Create an anonymous authentication scheme named WFCAnon.
- For example, WFCAnon contains “ou=People, dc=Kronos, dc=com” for the User DN.
- Create a basic or form authentication scheme named WFCFormAuthentication.
- Create a realm for UKG Workforce Central non-logon URLs named WFCRealm.
- Set the resource filter to the instance name /instance/ and the authentication scheme to WFCAnon.
- Create a realm for the UKG Workforce Central logon URLs named WFCLogonRealm.
- The WFCLogonRealm should be a sub-realm of WFCRealm. Set the resource filter to logonWithUID and the authentication scheme to WFCFormAuthentication.
- Create a realm for the navigator framework logon URL named NGUILogonRealm.
- The NGUILogonRealm should be a sub-realm of WFCRealm. Set the resource filter to navigator/logonWithUID and the authentication scheme to WFCFormAuthentication.
- Create a realm for the HTML Client logon URL named HTMLClientRealm.
- The HTMLClientRealm should be a sub-realm of WFCRealm. Set the resource filter to HTMLClient/logonWithUID and the authentication scheme to WFCFormAuthentication.
- Create a rule that will handle all non-logon UKG Workforce Central URLs in the WFCRealm named WFCAllowAllRule.
- Set the effective resource to the wildcard character *.
- Select the Perform regular expression pattern matches check box.
- Set the Actions button to Web Agent actions.
- Select all types of HTTP methods (Get, Post, and Put).
- This rule activates for all non-logon UKG Workforce Central URLs accessed by the HTTP methods Get, Post, and Put. Because this rule is part of the WFCRealm, it uses anonymous authentication. Therefore, all UKG Workforce Central URLs are passed through the UKG Workforce Central without an authentication check by SiteMinder. UKG Workforce Central only allows access to protected non-logon URLs by previously authenticated users.
- Create a rule that will handle all UKG Workforce Central logon URLs in the WFCLogonRealm named logonWithUIDRule
- Set the effective resource to the wildcard character *.
- Select the Perform regular expression pattern matches check box.
- Set the Actions button to Web Agent actions.
- Select all types of HTTP methods (Get, Post, and Put).
- This rule activates for all UKG Workforce Central logon URLs accessed by the HTTP methods (Get, Post and Put). Because this rule is part of the WFCLogonRealm, it uses basic or form authentication. Therefore, access to all logon URLs are redirected to the form identified in WFCFormAuthentication. All users are prompted for their credentials, user name, and password.
- If SiteMinder authenticates a user accessing this logon URL, it informs UKG Workforce Central that this user has been authenticated.
- Create a rule that will handle the navigator framework logon URL in the NGUILogonRealm named nguiLogonWithUIDRule.
- Set the effective resource to the wildcard character *.
- Select the Perform regular expression pattern matches check box.
- Set the Actions button to Web Agent actions.
- Select all types of HTTP methods (Get, Post, and Put).
- This rule activates for all UKG Workforce Central navigator logon URLs accessed by the HTTP methods (Get, Post and Put). Because this rule is part of the WFCLogonRealm, it uses basic or form authentication. Therefore, access to all logon URLs are redirected to the form identified in WFCFormAuthentication. All users are prompted for their credentials, user name, and password.
- If SiteMinder authenticates a user accessing this logon URL, it informs UKG Workforce Central that this user has been authenticated.
- Create a rule that will handle the HTML Client logon URL in the HTMLClientRealm named HTMLClientLogonWithUIDRule.
- Set the effective resource to the wildcard character *.
- Select the Perform regular expression pattern matches check box.
- Set the Actions button to Web Agent actions.
- Select all types of HTTP methods (Get, Post, and Put).
- This rule activates for allUKG Workforce Central HTML Client logon URLs accessed by the HTTP methods (Get, Post and Put). Because this rule is part of the WFCLogonRealm, it uses basic or form authentication. Therefore, access to all logon URLs are redirected to the form identified in WFCFormAuthentication. All users are prompted for their credentials, user name, and password.
- If SiteMinder authenticates a user accessing this logon URL, it informs UKG Workforce Central that this user has been authenticated.
- Create a policy for the UKG Workforce Central non-logon URLs named WFCAllowAllPolicy.
- Configure this policy to contain the WFCAllowRule and the LDAP users that you want to access UKG Workforce Central.
- Create a policy for UKG Workforce Central logon URLs named AllowLogonWithUIDPolicy.
- Configure this policy to contain the logonWithUIDRule, nguiLogonWithUIDRule,HTMLClientLogonWithUIDRule, and the LDAP users that you want to access UKG Workforce Central.
When finished, you should have configured the following:
Type of UKG Workforce Central URL |
Realm | Authentication Scheme | Rules | Policies | |
WFC Anon |
WFCForm Authentication |
||||
Non-logon URLs |
WFCRealm |
X |
|
WFCAllowAllRule |
WFCAllowAll |
Logon |
WFCLogonRealm |
X |
logonWithUID |
|
|
Navigator |
NGUILogonRealm |
|
X |
nguiLogonWith |
|
HTML Client URL |
HTMLClientRealm |
|
X |
HTMLClientLogon |
Use one or more of the following URLs to log on in a single sign-on environment, such as SiteMinder:
- Single sign-on, HTML Client only:
- https://webserver/instance/logonESS_SSO
- Single sign-on using SiteMinder for the navigator framework:
- http://webserver/instance/navigator/logonWithUID
- Single sign-on for users changing their locale_policy:
- http://logonwithUID?LOGON_LOCALE_POLICY=<LANGUAGE_ID>
- Proprietary authentication, HTML Client only:
- https://www.webserver/instance/applications/wtk/html/ess/logon.jsp
- Workforce Mobile:
- http://webserver/instance/smmobile/logonWithUID
Note: If you are using an application other than SiteMinder, your specific URL must conform to your organization’s environment.
If MLSI (multiple language on a single instance) is used at your site, users who log on using SiteMinder can log on in a language other than the one specified in their locale policy. To enable logging on in a different language:
Add a URL for a locale policy
Implement single sign-on for users who want to view the system in a language other than the one specified in their locale policy by using the following URL:
/InstanceName/logonWithUID?LOGON_LOCALE_POLICY=<LANGUAGE_ID>
This URL sets the language of the user’s session to the LANGUAGE_ID. You can retrieve the list of language IDs from the LOCALEPROFILE table in the database by using an XMLAPI call.
Modify Policy Server rules
Update the Policy Server rules to allow the parameter, LOGON_LOCALE_POLICY, to be used as part of the URL when users want to change languages.
To update the rules:
- Open the SiteMinder Rule dialog box.
- In the Realm and Resource section, with the Realm logonWithUID, update the Resource to be:
- \?LOGON_LOCALE_POLICY=[0-9]+
Setting/Environment | Description | Default | Site Minder |
SAML | |
---|---|---|---|---|---|
IdP-initiated | SP-initiated | ||||
site.security.singlesignon |
Specifies if single sign-on is enabled: true or false |
false |
true |
true |
true |
site.security.singlesignon.aoid |
Specifies if single sign-on accepts AOIDs (Associate Identifiers): true or false. This setting is used by the API authentication feature. |
false |
NA |
NA |
NA |
site.security. |
Switch to turn off mobile employee single sign-on validation: true or false |
false |
NA |
NA |
NA |
site.security. |
Defines the logoff URL |
/wfc/logon/ logonWFC.html |
|
X |
X |
site.security. |
Defines the logoff URL for the ESS UI |
/wfc/applications/wtk/ html/ess/logoff.jsp |
|
X |
X |
site.security. |
Name of the module that implements single sign-on for UKG Workforce Central. |
com.kronos.wfc.platform. security.business. authentication.ssoplugin. SSOSiteMinderSubjects |
X |
|
|
site.security. |
Name of the property file that contains configuration information used in the SiteMinder single sign-on module |
c:/Kronos/wfc/applications /wcb/properties/ SSOSiteMinder.properties |
X |
|
|
site.security. |
Specifies the SSO timeout redirect URL |
/wfc/logonWithUID |
NA |
X |
X |
site.security. |
Name of the SAML IdP attribute as returned in the SAML response |
|
X |
X | |
site.security. |
Path to the directory containing the SAML IdP certificate and metadata file |
|
X |
X | |
site.security. |
Name and path of the SAML IdP certificate file. The path is relative to the library path. |
|
X |
X | |
site.security.sso.saml. |
Name and path of the SAML IdP metadata file. The path is relative to the library path. |
|
X |
X | |
site.security. sso.saml.encryption.enable |
Setting to enable or disable SAML encrypted SSO service | false | X | X | |
site.security. sso.saml.decryption. privateKey.file.path |
Name and path of the privateKey file for SAML assertion decryption. The path is relative to the library path | ||||
site.security. sso.saml.authentication. request.privateKey.file.path |
(Optional) Name and path of the SAML private key to sign SAML SP-initiated authentication request. The path is relative to the library path. | ||||
site.security. sso.saml.splogon |
Setting to enable or disable SP-initiated SAML service. | false | false | true | |
site.security. sso.saml.idpendpoint |
IdP end point for SAML request in SP-initiated SSO process | X | |||
site.security. sso.saml.spendpoint |
SP end point for SAML request in SP-initiated SSO process | X | |||
site.security. sso.saml.providername |
Provider name for SAML request in SP-initiated SSO process | X | |||
site.security. sso.saml.issuer |
Issuer name for SAML request in SP-initiated SSO process | X | |||
site.security. sso.saml.splogon.exception. logonurl |
Specifies the URL for redirection in case of an exception | /wfc/logon/logonWFC.html | X | ||
site.security. sso.saml.splogon. exception.url.param.name |
Parameter name to check if the request needs to be redirected to the specific target URL or not | splogonexception | X | ||
site.security. |
Set to true to enable session timeout when single sign-on is enabled: true or false (same value for all UIs) |
false |
|
X |
X |
site.security.singlesignon.show. timeout.warning |
false | ||||
site.security. |
Specifies the SSO timeout redirect URL for the ESS UI |
/applications/wtk/html/ |
NA |
X |
X |
site.security. |
Controls the Logoff/Signout links in all user interfaces: true or false. True hides the Logoff/Signout link on the top of page and false displays it. |
false |
X |
X |
X |
Integrated Windows Authentication (IWA) enables users who are already logged into their Windows desktop to enter the system without providing their user ID or password.
Note: IWA requires service release 8.1.3 or higher.
Step 1: Implement IWA
To implement IWA, do the following:
- Set jakarta connector security to use IWA. To do this, open Internet Information Services (IIS) Manager and do the following:
- Select Sites > Default Web Site > jakarta and double-click Authentication.
- Right-click Anonymous Authentication and select Disable.
- Right-click Windows Authentication and select Enable.
- Navigate to .\Kronos\jboss\wfc\configuration, make a backup copy of standalone.xml, and then with a text editor, edit standalone.xml as follows:
- Look in the <system-properties> block for:
- <property name="org.apache.tomcat.util.http.Parameters.MAX_COUNT" value="5000"/>
- Add the following line:
- <property name="com.kronos.wfc.enableIwa" value="true"/>
- This line must exist within the <system-properties> block before the line:
</system-properties> - Then make the same changes to .\Kronos\jboss\wfc_staging\configuration\standalone.xml after making a backup copy of this file. This step is extremely important to enable the changes to persist when service packs are added or removed, or when Configuration Manager is used to rebuild the instance.
- Log on to UKG Workforce Central, select Setup > System Configuration > System Settings, and click the Security tab. Set the following settings:
- site.security.singlesignon=true
- site.security.singlesignon.module=com.kronos.wfc.platform.
security.business.authentication.ssoplugin.SSOWIASubject - Shut down the server, rebuild the instance, and then restart the server.
- In the People Editor, select the Person tab and, in User Information, select NT authentication for users who are using IWA.
These users can then log on to a Windows machine and navigate to http://<machineName>/wfc/navigator/logonWithUID to access the system. Note that this URL is for Internet Explorer.
Step 2: Provide an open channel for JBoss to communicate to the notification server
Because the Windows authentication used for supporting IWA in IIS can block JBoss communication to the OpenFire notification server, you also need to install the Application Request Routing (ARR) and URL Rewrite extensions from Microsoft as follows:
- Open a browser and go to http://www.iis.net/downloads/microsoft/application-request-routing
- Click Install this extension.
- In the Application Request Routing 3.0 box, click Install.
- Review the prerequisites and license terms, then click I Accept.
- When the finished screen appears, click Finish.
- The installer installs ARR and all of its components. If the URL Rewrite extension is not installed, you can install it separately from http://www.iis.net/downloads/microsoft/url-rewrite.
- Open IIS Manager and select your IIS server.
- Open Application Request Routing Cache.
- From the Actions pane select Proxy > Server Proxy Settings.
- Select the Enable proxy check box and click Apply in the Actions pane.
- In the Connections pane, open Sites and select the site where UKG Workforce Central is installed, typically the Default Web Site.
- In the main screen, double-click URL Rewrite.
- In the Actions pane, click Add Rule(s).
- Below Inbound rules, click Blank rule and click OK.
- In the Edit Inbound Rule box, configure the rule as follows:
- In the Requested URL box, select Matches the Pattern.
- In the Using box, select Regular Expressions.
- In the Pattern box, enter /XMPPBOSHService/ and select Ignore Case.
- In the Action type box, select Rewrite.
- In the Rewrite URL box, enter the name of your notification server and its port number in the format:
- http://<servername>:7070/http-bind/
- If selected, deselect Append Query string.
- Click Apply.
- Restart IIS.
To test the configuration:
- Try to access the following URL from your browser window:
- <server name>/wfcstatic/XMPPBOSHService/
- You should not be able to access the URL. You should see the following error message:
- HTTP ERROR: 400
- Problem accessing /http-bind/ Reason/
- Bad Request
You can use IWA only with Internet Explorer. To configure Internet Explorer for use with IWA, do the following:
- Go to Tools > Internet Options > Local intranet > Sites.
- Click Advanced.
- Add the server name to the list of websites, and click Close.
- Go back to the Security tab and click Custom Level.
- Scroll down to User Authentication, select Automatic logon only in Intranet zone, and click OK.
- Go to the Advanced tab on the Internet Options screen, and scroll down to security section.
- Select Enable Integrated Windows Authentication [on some versions of IE this item says “Select Enable Integrated Windows Authentication (requires restart)”].
Integrated Windows Authentication does not support anonymous access to the application. Because of this, certain products such as Integration Manager and Device Manager are unable to communicate with an IWA application server and are unable to use the single sign-on feature.
If you plan to use Integrated Windows Authentication and you also use products such as Integration Manager or Device Manager, then you must use a second, non-IWA web server to handle authentication for the incoming traffic for those products.
Some features such as Quick Time Stamp, Worksheet, and the XMLAPI require a username and password, but do not include an interface with IWA. Therefore, these features cannot take advantage of single sign-on.
If your configuration includes devices in an SP-initiated SSO environment, create a separate web/application server that is not configured for single sign-on, then configure your devices to communicate with this server. This will ensure that data collection and Smart Views function properly.