Enabling single sign-on and setting options

After the Helix Authentication Service (HAS) is installed and working correctly, an administrator needs to configure single sign-on in the Hansoft Server Administrator.

Keep the following in mind:

  • You must use a version of the Hansoft server that supports integration with HAS. Hansoft 11.0041 and later are supported.
  • The identity provider and HAS must be installed, configured, and running before using SSO in Hansoft. This also includes adding certificates on the Hansoft server so Hansoft can be a client to HAS. See Installing the Helix Authentication Service for single sign-on and Configuring certificates for single sign-on on the Hansoft server.
  • The user email address from the identity provider is used to map to a user in Hansoft. If the same email address is set for multiple Hansoft users, the wrong users may be mapped. If multiple users have the same email address, you may need to change email address in each system for single sign-on to work.
  • SSO settings apply to all databases on the Hansoft server you are logged in to.
  • Review and adjust SSO settings if you share users between multiple Hansoft servers. For example, you have two Hansoft servers (ServerA and ServerB). A user is shared from ServerA to ServerB. ServerA is configured to only allow login using SSO. You must also allow login using SSO on ServerB or the user will not be able to log in to the server.

1. In the Hansoft Server Administrator, click SSO options under Server settings.

The SSO options dialog box opens.

2. Select Enable Helix Authentication Service to enable communication with HAS for SSO.

3. Enter the Helix Authentication Service URL, including the port that the service is running on.

This is the SVC_BASE_URI value in the HAS .env file. It can be an http or https URL and must include the port number. For example, https://has.mycompany.com:3000.

Note:  If you use https, you must configure client certificates on the Hansoft server. See Configuring certificates for single sign-on on the Hansoft server.

4. Select a Login option.

  • Use SSO login only lets users log in with SSO only. If this option is selected, users can only log in through the identity provider and not with their Hansoft or LDAP username and password.
  • Allow password or SSO login lets users log in using either SSO or their Hansoft or LDAP username and password.

5. Optionally enter an Email mapping override if user email addresses in the identity provider are not using the default fields, which are loginID (SAML) or email (OIDC) fields.

For example, if the email address in a field named signin in the identity provider, Hansoft does not recognize the field to map the user email address from the identity provider to Hansoft. In this case, you need to enter signin in the Email mapping override field. If the integration is not working, you can enter any value in this field and then attempt to log in to the Hansoft client with SSO. The login will not be successful, but you can then review the Hansoft server log to see all fields in the response from HAS and find the correct field name.

6. Click OK to save the changes.

7. Log in to the Hansoft client to make sure SSO works correctly.