This is a generic guide for configuring federated user authentication using an Identity Provider that supports SAML 2.0 to Perkbox as the Service Provider to establish user Single Sign On.
Please note - Perkbox currently only support SP initiated SSO
Identity Provider (IdP) e.g. G Suite, ADFS, OKTA, Azure, Onelogin
Service Provider (SP) i.e. Perkbox
Single Sign-On (SSO)
Security Assertion Markup Language (SAML)
Assertion Consumer Service (ACS)
General setup on the Identity Provider's end
Login to your Identity Provider's console
Create a SAML application and enter Perkbox as the application name
On the SAML settings, enter the ACS URL as https://api.production.perkbox.services/sso/v1/provider/saml/callback. If you are in Australia, please enter the ACS URL as https://api.production.us-west-2.perkbox.services/sso/v1/provider/saml/callback
Enter Audience URI (Entity ID) as https://sso.perkbox.com/v1/provider/xxx. Note: that you'll need to come back to this field later and update the xxx with your unique ID.
Enter the Attribute Statements as follows mapped to your use
https://sso.perkbox.co.uk/SAML/Attributes/User/Email mapped to user's email address
https://sso.perkbox.co.uk/SAML/Attributes/User/FirstName mapped to user's first name
https://sso.perkbox.co.uk/SAML/Attributes/User/LastName: mapped to user's last name
6. Download the IDP METADATA XML file and save it to your computer.
Note: Some IdP's provide an Issuer URL which you click on to download the file. If the XML file opens in the browser, you can save it going to File then Save Page As...
7. Set up users if you need to on the IdP
Head to the Admin Dashboard
Access 'Login & Integrations' > 'Set up SSO'
On your company's unique Perkbox URL website, open the single sign on settings page (you'll find this within 'sign up settings', in the admin panel)
The first field is the text that will appear on your user log in button. Enter something like Login via SSO
Upload your IDP METADATA XML file
Under SAML Request Type section of Step 1, check off Requires AuthNRequest box
Under the SAML Request Name field, enter SAMLRequest
Under the SAML Request Issuer field, enter https://sso.perkbox.com/v1/provider/
6. Enable 'hide normal login form' option if you would like SSO to be the only log in method on your login page
7. Click the CONTINUE button
8. Under STEP 2 section, copy the unique string next to Value: (NOTE: ignore the URL next to Key:)
9. Click 'edit' to go back to the SAML Request Issuer field from Step 1 on the Perkbox platform
10. Append the string to the end of the URL under SAML Request Issuer field, e.g., https://sso.perkbox.com/v1/provider/YOUR_VALUE_FROM_STEP_2
11. Copy this url and leave this page open
12. Go back to your Identity Provider console settings for the Perkbox app you created earlier and then paste the url into the Audience URI (Entity ID) field there then hit save.
13. Now on the Perkbox SSO settings page, click Test and Save.
Now let's test if everything is working as expected.
Log out of Perkbox
Click the Login via SSO button. The button may be named differently if you used a different name under the Perkbox SSO settings.
External guides in setting up a SAML application