In this article you will learn about how to get access to all HRworks services with a single login to your enterprise portal.
Table of contents
5. Connect Login-URL with Admin interface
1. Introduction
With Single Sign-On, or SSO for short, you have access to all services with a single login to your company portal. Integrate HRworks into your intranet or Internet portal. Your employees and your company benefit from an increase in security and convenience.
HRworks uses SAML (Security Assertion Markup Language), an XML-based framework for user authentication that works without the need to exchange passwords. The digital XML signature provides even more security.
Your employees only have to remember one password. This can be made all the more complex and secure. In addition, an SSO solution means that the password only has to be transmitted once.
2. Activate Single Sign-On
Due to the SAML standard, the integration of HRworks works without much effort. The HRworks Single Sign-On can be connected to all SAML-supporting products, including Microsoft’s Active Directory® composite services or Google G Suite’s SAML.
Setting up the SSO for HRworks takes just two steps.
Configure SSO in HRworks
To set up the function you need the role Security basics administrator. Open the menu “Admin/Basics/Security/SingleSign-On” and first check “Use Single Sign-On”. Under “Metadata input method”, you can decide whether you want to enter the metadata of your identity provider manually via a form or import it via the XML metadata.
If you would like to use the XML input method, select which master data attribute of the persons in HRworks is to be used as the NameID attribute for the login via SAML SSO under “Value for NameID” . This value must also be transmitted later by your IdP in the SAML response. Possible options available to you here are the “User-ID”, the “Employee ID” or the assignment of an “individual NameID identifier”. If “individual NameID identifier” was selected, the corresponding value must still be stored in the master data view of all persons or inserted via an import (see also Appendix 3 in this article).
Then insert the complete XML metadata of your identity provider into the input area.
To check the data, switch to the form view and check whether all values have been parsed correctly. If the parsing of the XML file fails, you can also enter the necessary values directly via the integrated form.
If you have decided to “Input via form”, enter the required data selected in the respective text fields. At “SingleSignOn-Url”, enter the URL that HRworks can use for AuthenticationRequest at your IdentityProvider. Then enter your public key or your X.509 certificate in PEM/Base64 format in the next field. At “Issuer”, enter the value of the SAML tag that your IdentityProvider sends in the AuthenticationResponses. Finally, use the drop-down menu “NameID format” to decide on a SAML format that is to become valid for the value of the SAML tag NameID.
Enter HRworks as a Service Provider in your company’s Identity Provider
Enter the HRworks metadata into your authentication server. The HRworks metadata is slightly parameterised depending on the company (concerns the SLO URL).
These can be accessed in the menu “Admin/Basics/Security/Single Sign-On” via the button “Download HRworks metadata”.
Complete the setup of the SSO function by clicking “Save”. If you would like to change your details in the future, select the “Reset” option to remove all the values entered for your identity provider.
Setting up Microsoft Azure
If you are using Microsoft’s Azure Active Directory, you can easily add HRworks there via the application catalogue. You can find step-by-step instructions on how to do this in the Microsoft documentation (you can select to read this in English in the top right “Auf Englisch lesen”).
3. Test Single Sign-On
After you have completed steps one and two of the setup, please test the SSO. It is advisable to perform the test at a time when little traffic is expected in HRworks. Make sure that the NameID value corresponds to the master data attribute in HRworks that has been set as the NameID value in the settings. Then call up the link to the direct SSO (see Direct login url in the appendix). If the setup was successful, you will be logged into HRworks directly after authentication in the IdP.
4. Troubleshooting
If the login via SSO is not successful and the error message of the login server does not help, please send the AuthResponse as an XML file to your responsible consultant for problem solving or contact the HRworks Customer Service Team.
In addition, please check whether all settings are set according to the checklist in Appendix 1. If you are using an ADFS server, also check whether you have correctly configured the rules described in Appendix 2.
Also check that the NameID format in HRworks and on the IdP (your authentication server) are identical. If the selected NameID format does not work in HRworks, select as NameID format: SAML:1.1:nameid-format:unspecified
5. Connect Login-URL with Admin interface
If you want to log in directly via the Admin interface, you can add “useflow=false” to the login url for SSO accordingly.
Example:
https://login.hrworks.de/?companyId=&directssologin=true&useflow=false
This will lead the users directly to the Admin interface. Without adding the parameter you will be logged in the user interface as default.
Appendix 1
Additional information about configuration of IdP
SSO
- HRworks supports only SAML 2.0
- HRworks supports only SP-initiated SSO
- HRworks expects the AuthResponse as POST-Request (Format application/x-www-form-urlencoded)
- HRworks expects that the Assertion (AuthResponse) is digitally signed
- HRworks supports RsaSha256 and RsaSha1
- HRworks does not support (XML-)Encryption der Assertions/AuthResponse
- HRworks does not sign AuthRequests
- The Name-ID attribute has to correspond to personal data selected in HRworks (Name-ID, Employee-ID, individual NameID-Identifier)
- HRworks does not require any attributes other than NameID
- InResponseTo has to be set in Assertions
SLO
- HRworks supports only IdP-initiated SLO
- HRworks expects that Logout requests are digitally signed
- HRworks supports RsaSha256 and RsaSha1
- HRworks does not support (XML-)Encryption der Assertions/AuthResponse
General Data SSO/SLO (also included in HRworks-Metadata)
ACS-URL:
https://login.hrworks.de/saml-sso
Entity ID:
https://login.hrworks.de/HrwMeLoginView
SLO-URL:
https://login.hrworks.de/saml-slo?customerNumber=<customer-number> (The customer number can be found here: Administrator/Basics/Company Data (remove “<” and “>” in the URL).
Direct Login-URL:
(Your employees will be redirected directly to your IdP for authentication): https://login.hrworks.de/?companyId=<company ID>&directssologin=true (remove “<” and “>” in the URL).
The metadata can be accessed in the admin-menu "Basics/Security/Single Sign-On".
Appendix 2
Example Claim Rules for Microsoft ADFS Server
For the configuration of HRworks as SP in an ADFS-IdP, so-called claim rules must be stored, which ensure that the correct ActiveDirectory attributes are passed on to HRworks via the SAML response. Here, only the AD attribute must be transferred to the value NameID-, which corresponds to the master data attribute selected in HRworks as NameID (user ID, personnel number or individual NameID identifier). Further attributes
do not have to be sent.
Below is an example of these rules that you can adapt for your AD structure. Two rules must be created:
Rule 1:
The first rule is used to fetch the desired value (which must correspond to the selected NameID attribute in HRworks) from the attribute in AD and store it in a local variable. In the example, the value is fetched from the AD attribute “initials” and stored in the local variable “surname”.
c:[Typ == “http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname”,
Issuer == “AD AUTHORITY”]
=> issue(store = “Active Directory”, types =
(“http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname”), query = “;initials;{0}”,
param = c.Value);
Rule 2:
The second rule converts the value in the local variable into the value for the SAML attribute NameID.
In the example, the NameID format “unspecified” is used for this.
However, you can of course change this according to your requirements.
c:[Type == „http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname“]
=> issue(Type = „http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier“,
Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType =
c.ValueType,
Properties[„http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format“] =
„urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified“);
Appendix 3
Add SSO NameID to all staff via a change import.
First create a report with all the personal data of your employees in the admin-menu “Basics/Lists/Generate”. In the “Lists” tab, select the “Import – All master data for import” and decide on a file format in which the report should be downloaded. In the tabs “Organisational units” and “Persons”, check whether all employees of your company are selected and then click on “Start report”.
As soon as the status of the report is “Successfully created”, download it by clicking on “Download”. Then copy the report (Ctrl + A and Ctrl + C) and paste it into Excel (Ctrl + V). Delete the first three and the last line from the file. For a better overview, you can remove all columns from the file except for the User ID and the SSO NameID and enter the NameID values of your staff.
Once you have edited the file so far, save it in CSV format. To import the edited person data into the software, open the admin-menu “Persons/Persons” and click on the button “Import”. Upload the CSV file and confirm the process by clicking on “Upload”. In the selection of the import window, select “Change existing persons” and complete the change with “Import”.