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.
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
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