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 support@15five.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/config/start/ by following the prompts (requires admin privileges and is an additional cost per user).
Go to https://my.15five.com/saml2/config/start/ .You can also find this set up under Company Settings- Single Sign-On.
Here is where you will set your company's subdomain. You can choose anything they want as long as it does not contain characters or spaces. The subdomain name needs to also be a unique name (no other company can be using the domain.)
Once you have selected your subdomain, click "Save."
You will now need to add in your XML metadata. This metadata is taken from their Idp (Identity provider such as Okta or OneLogin) and inserted here. Once added, click "Save."
On the "SAML Single Sign-On" page there are a few options to consider.
- The checkbox next to "SAML Single Sign-On Enabled" should be checked to enable SSO.
- "Allow password sign-in" can be checked if they want their users to have the ability to sign in using their email and password, rather than just through SSO. Turning this off turns it off for all users, including admins.
- Allow JIT (Just In Time) Provisioning- This will create a new account for an employee if they don't already have one in 15Five, but they have permissions in your IdP. We recommend not using this if you have "email" set as your Name ID (see below) as this can result in duplicate accounts when there is an email change.
- The "Contact email" is the IT person's email who we or others in your company should reach out to about SSO related questions or issues.
- The four lines below this will show the Sign-in URL, Idp entity ID, etc. These are auto-populated by pulling from the XML metadata they entered on the previous screen
Add in the Attributes.
Most errors happen during the last part of setup. The only required attributes are "Name ID contents" and "Email attribute name." These have to pull exactly from their end. However, it can sometimes be unclear as to what attributes are used. A good way to help guide you is to click the blue link above labeled "Attributes help."
When wanting to pass a reviewer attribute through SAML, we give two options: ID or Email. If possible, we suggest using ID as emails tend to change more often and with ID. Keep in mind, this information only updates when people log in or are JIT provisioned, so it is preferable to manage reviewer through SCIM if possible.
Once you click this link, the data we see will show up here. We can see in the above screenshot that we are getting "firstName," "lastName," and "mail" from their end. "mail" will go into "Email attribute name" and must match exactly.
If you are unsure of what the "Name ID Contents" should be (either not used, email, or user ID) check their XML metadata from the previous screen.
To do this go to the XML Metadata tab and search (F finder) for "NameID"
This will show you exactly what part of the data indicates the NameID. Here you can see that it is set to "emailaddress" so the NameID in the "Details Setup" tab should be "Email." If you are not able to find the "NameID" like above, then it is "Not Used."
If you have User ID set as your Name ID
You must fill out the optional attribute "Employee ID" to match the attribute in your IdP. Without this the User ID will not be synced to 15Five and your employees will not be able to log in.
Once complete with adding in the attributes, select "Save" and you're done!
If you would like us to set up SSO, please email support@15five.com and 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.
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/
Email Check
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 users already in 15Five. If the emails are different, the 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 you want to use instead of email address 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.
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.
Troubleshooting, Support, and FAQs
Q: A 422 Error
A: 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.
Q: I am unable to log into 15Five with SSO. I am getting an error message. Why can't I log in?
A: You did not navigate to the correct URL for your organization. In order to log in, you need to navigate to your domain URL subdomain.15five.com instead of my.15five.com.
Q: No user information is being sent from ADFS or Azure AD to 15Five. Why is the information not updating properly?
A: If no user attributes/information is being sent from ADFS or Azure AD to 15Five, make sure the below rules are configured on the ADFS/ Azure AD side:
Q: I’m having an issue with ADFS. There is an error when attributes do match. How do I fix this error?
A: Typically this is an issue with the Transform rule. Create a normal rule for email and then a transform rule that transforms email into NameID.
Changing the NameID format to "urn:oasis:names:tc:SAML:2.0:nameid-format:transient" would all be done in the Rely Party Trust modal.
This is the claim rule (a non-default setting) as it would appear in ADFS.
Q: I am looking for information to fill out my Azure AD partner application form. Where can I find that?
A: Below you will find answers to the Azure AD partner application forms (include spreadsheet below).
Partner (Application) Information |
|
Application Descriptions |
Purpose: The application provides for intra-company communication and insight. Name: 15Five https://azuremarketplace.microsoft.com/en-us/marketplace/apps/aad.15five |
Multifactor Authentication |
Does the application Support Multifactor Authentication? Yes Will the application require Authentication? Yes. When? Authentication is required immediately. |
Sign on URL |
https:// subdomain>.15five.com |
Identifier |
https:// subdomain>.15five.com/saml2/metadata |
Reply URL |
https:// subdomain>.15five.com/saml2/acs |
User Identifier |
NameID or email |
Relay State |
https:// subdomain>.15five.com/ |
Secure Hash Algorithm |
SHA256 |
Access Rules |
Members with access to the application in the Azure Marketplace will have access to the 15Five app. |
Q: I am receiving error AADSTS50105. What should I do?
A: See https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/methods-for-assigning-users-and-groups
Q: I am receiving error AADSTS750054. What should I do?
A: Sign-on URL” value in the Azure AD > Enterprise Applications > 15Five > Single Sign-On > Basic SAML Configuration section was set to an incorrect value. It should be set to https://SUBDOMAIN.15five.com. To find your subdomain, you would see in 15Five > Single Sign-On > Getting Started.
Q: I am receiving error AADSTS650056. What should I do?
A: The Issuer attribute sent from the application to Azure AD in the SAML request doesn’t match the Identifier value configured for the application in Azure AD.
The entity ID is set incorrectly in AAD. See below for an example of a misconfigured Entity ID (under Basic SAML configuration). Entity ID should =
https://<tenent-url>.15five.com/saml2/metadata/
Q: I am getting an error message that reads “This subdomain is not configured for SAML2 authentication”. What does this mean?
A: Check to see if the subdomain is capitalized instead of lowercase. This has caused an issue in the past.
Q: Could I be locked out when I am setting up SSO?
A: During your configuration of SSO, password login will still be an option. You will be able to login using both SSO and email+password until you explicitly shut off the option to log in with an email+password.
Q: If I set up SSO today, will people be able to log in immediately?
A: Yes. As soon as SSO is integrated, people will be able to log in.
Q: Can we turn off just in time provisioning?
A: Yes. You can turn on or off this setting by clicking the box next to it on your company's Single Sign-On page in 15Five:
Q: Does 15Five require the full XML or just a snippet?
A: We need the full XML.
Q: When a user is transferred/terminated and we remove them from our IdP would this be reflected as “disabled” or remove them entirely from 15five?
A: This depends on what you use for user management in 15Five. We do not deprovision accounts via SAML. If the employee is transferred/terminated, 1-remove access to the 15Five app in your IdP for that user 2- ensure the user is deactivated in 15Five. If not deactivated in 15Five, they may be able to access their 15Five account- if they have a 'keep me logged in' option in their browser.
Assumption: Customer only has SSO setup. No other integration.
Q: How is OAuth 2 different from SSO/SAML?
A: SAML is an authentication protocol, OAuth 2.0 is not. This means that OAuth 2.0 and SAML cannot be thought of as equal. OAuth 2.0 does not pass attributes about a user who has just authenticated. On top of that, Just-In-Time (JIT) provisioning is rather independent of SAML and not part of the SAML protocol specifications. The fact that SAML sends across user attributes in an assertion can be leveraged to implement a JIT provisioning system on top of, but that is a local implementation choice, not a SAML feature. One could build the same JIT system on top of OpenID Connect, which is a user authentication protocol built on top of OAuth 2.0. That would be comparable to JIT with SAML. (https://stackoverflow.com/questions/29885675/oauth-2-custom-attributes-like-saml#29894429). We do use OpenID Connect. We do not offer JIT provisioning with OpenID connect.
Q: Can a user log on with their local password after SSO is enforced?
A: Account admin have control over whether their people can log in with email+passwords once SSO is enabled. There is a setting (checkbox) that appears during SSO set up. If you would like to allow people to continue using their original passwords set up with 15Five in addition to SSO, leave the 'Allow password login' box checked.
Q: Can I have SSO and HRIS Integration? Why would I need both? Why would I choose one over the other?
A: Yes. SSO would allow your users to sign in with their SSO credentials. An HRIS integration would help keep your people's details up to date. One solves an identity management and security problem, one solves a data management problem.
For us, the answer depends on if we integrate with your HRIS system or not. If we don’t, then you can import user attributes through an SSO and/or SCIM, which would likely require a conversation with IT. The user attributes we can import are: first name, last name, location, title, employee ID, email, reviewer email, and group membership (SCIM/API/HRIS integration only for group membership).
Q: If I do a tiered roll-out of 15Five, how do I ensure that the entire organization doesn't receive email invites when I set up SSO?
A: SSO does not provision users (does not create anyone's 15Five account) automatically. A user can sign in to 15Five with SSO using just in time provisioning (we can shut this off on our side, and they can shut it off on their side). You can make sure the entire organization doesn’t receive email invites via the checkbox on the CSV bulk import or, if SCIM is on - there is a checkbox you can shut off there.
Q: Does SSO mean that when I log into my computer in the morning I will be automatically logged into 15Five?
A: Maybe. It depends on your cache. SSO doesn’t log you in automatically. The best way to describe it is to tell people that SSO is what you see when you go to a website you have never gone before and you have the option to login via Google
Q: Do you provide an SSO service?
A: We do not provide an SSO service, as we are not an IdP; however, we do offer SSO integrations within our application.
Q: Does SSO put people's job titles in 15Five automatically?
A: It can put people’s job titles into 15Five but not automatically. A user would have to sign in to 15Five. SCIM 2.0 could do this automatically.
Q: How long does it take to set-up SSO?
A: SSO should take 5-10 minutes for an IT person to set up.
Q: When does 15Five update user attributes via SSO?
A: When the user logs in, the information is updated.
Q: How will I set this up?
A: Easy to set up, follow wizard we have in-app.
Q: What is the blue login button below in this photo?
A: That is our social auth login. It's not SAML but OAuth 2. It would not set up a SAML profile but would log you in under the right account if a user with the same email address as your google email address clicked that blue button. It's like Facebook login or Spotify.
Q: Does OAuth go away if you set up SSO?
A: Yes
Q: Can SAML 2.0 be used with any SSO/IdP?
No, just SSO/IdPs that use SAML 2.0. It’s standard, so it should be most.
Q: How can I tell if we are passing the Reviewer information?
A: The Reviewer information will be determined if you’ve included it in the Review Email Attribute
If you would like help, please feel free to reach out to support@15five.com.