This document describes the general process for setting up single sign-on (SSO) using SAML 2.0. SAML is a widely adopted standard; you may find instructions for your specific identity provider in our online help center.
Enabling SSO is highly recommended because it allows your employees to access Workpath with their internal company accounts without having to manage an additional password. In addition, it removes overhead due to manual user management.
Step 1 – Identify Stakeholders
First, contact your internal IT department to learn which group or person is responsible for configuring SSO integrations. Find out if there are waiting times or approval processes.
Workpath is happy to directly liaise with your IT department to work through technical details, but they might require a business stakeholder to be involved in initial phases.
Step 2 – Decide How to Provision New Accounts
You need to make a decision how new accounts will be created in Workpath:
Automatic user management. Your IT team will grant all employees, or employees of certain departments or roles access to Workpath. If an employee logs in to Workpath for the first time, we will automatically create a regular user account (“just-in-time provisioning”).
Manual user management. Only allow users to access Workpath if they’ve been invited by an admin, program lead or team lead through Workpath user management.
Workpath recommends the first option for the least administrative effort. Communicate this decision to your Workpath client success manager and your IT team.
Step 3 – Decide on a Testing Strategy
Once SSO is configured, Workpath and your IT department should agree on a time to enable it and test. There are two ways of doing that:
Testing directly on your productive instance, e.g. YOURCOMPANY.workpath.com. We recommend this if no, or only a few pilot users have access to Workpath.
Testing on a QA instance first, e.g. YOURCOMPANY-test.workpath.com. We recommend this if many users already use Workpath productively with regular email and password accounts.
Communicate this decision to Workpath so we can create the QA instance, if required.
Step 4 – Exchange SAML Configuration
For SSO to work, your IT department and Workpath need to exchange a few configuration parameters, as well as cryptographic certificates for security.
Your IT department can download all required configuration and certificates in a so-called metadata XML file from https://api.workpath.com/v1/saml/metadata/YOURCOMPANY(-test), where YOURCOMPANY is the subdomain which you see when access the Workpath login: https://YOURCOMPANY.workpath.com/
Ask your IT department to configure these attributes, which will be synchronized over to Workpath:
|
Attribute *) required |
Description |
| first_name* | First name of the user to display in the platform |
| last_name* | Last name of the user to display in the platform |
| external_id | ID given by IDP to match users on. Highly recommended to avoid duplicating accounts if an employee’s email changes |
| Pass the employee’s email. If not present, will be inferred from UPN | |
| team_code | If a team with this Team Code exists in Workpath, the user will be automatically assigned |
| manageruid | ID given by IPD to user’s manager; used to display reporting lines |
| locale | User’s preferred language (‘de’ or ‘en’); company’s default language is used if skipped |
| office | Office that the user is located at |
| job_title | Job title of the user |
| department | Department of the user; does not affect the membership of teams within Workpath, but useful for the initial setup and recommendations |
Using this configuration, your IT department will configure Workpath as a SAML application, and send back another metadata XML file to Workpath. Workpath technical staff needs to perform configuration of SAML on our side; there is no self-service option currently.
IMPORTANT NOTE:
We expect the attributes without XML namespace.
<AttributeValue>Daniel</
</Attribute>
FALSCH:
<Attribute Name=http://schemas.xmlsoap.
<AttributeValue>Daniel</
</Attribute>
Step 5 – Test
Test SSO, and confirm that login works and all passed attributes are applied to Workpath profiles.
For the fastest reaction to problems, the Workpath team offers to perform the switch in a live call. Contact your client success manager to arrange this.
After enabling SSO, the so-called service-provider-initiated login will become available directly from https://YOURCOMPANY.workpath.com/.
Step 6 – Phase Out Password Login (Optional)
If you had a significant number of users who access Workpath using passwords, you can decide to leave password login enabled for a number of days. This way, employees for whom SSO does not work for some unexpected reason are not locked out of Workpath.
Once an account has successfully used SSO, they will no longer be able to use their previous Workpath password.
Workpath recommends a transition period of 7 days if you have a significant number of employees to transition from password login to SSO.