What is SSO?
Single Sign-On is a method of authentication (logging into a service) that companies have adopted over the years as it centralizes the security for IT administrators. IT admins can use a single portal for controlling their employee's access. In large corporations, this is ideal because new employees that join their company often need access to multiple software services. But, having the new employee sign up for each service on their own can be cumbersome and time-consuming. SSO centralizes the process by allowing an IT admin to give access to a new employee to multiple services at once through a single login profile.
Who can use it?
SSO is included in our Enterprise Plan. If you are on Basic or Plus Plans, please contact support@15Five.com to have SSO enabled as an add-on.
Important details (auto-provisioning and login options)
By default, we offer auto-provisioning (JIT) on the first login. If you do not want to automatically create profiles for new users in 15Five, you can request that change by emailing email@example.com. When SSO is enabled, you can optionally allow your employees to sign in with username/password in addition to SSO (although not recommended). We offer both IdP and SP (15Five) initiated logins. We support email or employee ID name ID type. Depending on capabilities of your IdP, you can pass a number of custom attributes to 15Five. These attributes are email, first name, last name, title, manager email, group name, location. SAML 2.0 does not offer de-provisioning support or asynchronous updates (updates to a profile in Google G Suite or Okta will not automatically show up in 15Five). For that, we offer SCIM integration for full auto-provisioning functionality with Okta or OneLogin (and hopefully Google G Suite soon).
How to setup SSO in 15Five
In most cases, the setup is pretty simple and you can either email us IdP information or set up SSO on your own at https://my.15five.com/saml2/sso/config/start (requires admin privileges and Enterprise Plan).
If you would like us to setup SSO, please include the following information:
- IdP Entity ID
- IdP Metadata XML or URL
- IdP user login URL
- Service binding: HTTP-Redirect or HTTP-POST
- Contact email address for future troubleshooting
We will reach out to you if we need any additional information for more complicated setups.
What you need for your IdP to setup SAML 2.0 with 15Five
15Five Metadata URL/Entity ID: https://<your subdomain>.15five.com/saml2/metadata/
15Five ACS URL: https://<your subdomain>.15five.com/saml2/acs/
15Five Service URL: https://<your subdomain>.15five.com/
By default, a team member's email address is used to look up their specific account in 15Five. Please ensure that the emails sent by your IdP are identical to those for the associated user accounts already in 15Five. If the emails are different, either a new user will be created or, if JIT provisioning is turned off, access will be denied.
If you can not use email addresses to identify your team members in 15Five, a unique ID can be used to identify users by passing the unique ID in the SAML attributes sent by your IdP. Specify the name of the attribute in the 15Five ID field on the SAML Single Sign-On page. Users in 15Five will need to be associated with this unique ID. This can be done using our Bulk Import Feature and the column name saml_user_id.
Identification SAML Attributes
By default, 15Five expects an email address to be passed in the SAML attributes and this is used to look up a specific 15Five account. The name of the attribute holding the email address should be entered into the "Email attribute name" field and the Name ID Contents field should be set to "Not Used". If the email address is being sent as the NameID SAML attribute, then the "Email attribute name" field can be left blank and the Name ID Contents field should be set to "Email".
If your team uses unique IDs to lookup 15Five accounts rather than email addresses and the unique ID is sent as the NameID SAML attribute, the 15Five ID field can be left blank and the Name ID Contents field should be set to "User ID".
To get a list of the last attribute names sent to 15Five by your IdP, click the "Attributes Help" link in the "User Attributes" section of the SAML Single Sign-On page.
Please refer to the following screenshots for some quick visual guidance.
How to test
Looking to test that your SSO setup is working correctly? Follow these steps:
- Log out of 15Five
- Head to https://<your subdomain>.15five.com
- Click the "Sign in using Single Sign-on" button and follow any other login steps provided by you Identity Provider (eg. Okta, OneLogin)
You should then be redirected to 15Five and logged in.
A 422 Error
Not seeing the data you would like being pushed into 15Five? Or are you getting a 422 error like the one below?
These conditions usually mean some manual configuration of SSO is necessary. Specifically, the SAML attributes sent by your Identity Provider (IdP) need to be mapped to the appropriate fields in 15Five. To see what attributes 15Five is receiving from you IdP, click on the "Attributes Help" text under the User Attributes section. Please note that at least one login attempt from your IdP to 15Five must be made before these attributes will be populated. These attribute names can then be used to fill in the form fields below.
Looking at the photo below, we can see that the IdP is sending "mail" but 15Five is configured to look for "Email" as the Email attribute name. By changing the field value to "mail", we can fix this configuration and login successfully.
If you would like help, please feel free to reach out to firstname.lastname@example.org.