This is a guide for configuring federated user authentication using G Suite as the Security Assertion Markup Language 2.0 IdP to Perkbox as the Service Provider to establish user Single Sign On. These steps are relevant for new Perkbox customers who readily have their G Suite configured as their organisation’s Security Assertion Markup Language 2.0 Identity Provider.
Please note - Perkbox currently only support SP initiated SSO
Abbreviations:
Identity Provider (IdP)
Service Provider (SP)
Single Sign-On (SSO)
Security Assertion Markup Language (SAML)
Please note - Perkbox currently only support SP initiated SSO
Get started:
On G Suite
Log in to your G Suite Admin dashboard portal
Go into Apps
Go into SAML apps
You will be adding a new SAML app for Perkbox, so click on the plus (+) sign in the bottom right corner
A pop up window will be presented and serves as a five step wizard to create a new SAML Application.
On Step 1 (Enable SSO for SAML Application) - click on SETUP MY OWN CUSTOM APP
On Step 2 (Google IdP Information) - under the subsection labeled Option 2, click on DOWNLOAD to download your IDP metadata file in XML format
Click NEXT to go to Step 3 (Basic information for your Custom App)
On Step 3 (Basic information for your Custom App), give your application a meaningful name, e.g. Perkbox
The other two fields are optional.
Click 'Next' to proceed to Step 4 (Service Provider Details)
Continue below with this guide’s next section to obtain field values to populate under Step 4 (Service Provider Details).
On Perkbox
Head to the Admin Dashboard
Access 'Login & Integrations' > 'Set up SSO'
2. 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
Upload your metadata file from G Suite
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, this is a unique URL
First enter the URL, https://sso.perkbox.com/v1/provider/
Enable 'hide normal login form' option if you would like SSO to be the only log in method on your login page
Click the CONTINUE button
Under STEP 2 section, copy the unique string next to Value: (NOTE: ignore the URL next to Key:)
Click 'edit' to go back to the SAML Request Issuer field from Step 1 on the Perkbox platform
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
Example: https://sso.perkbox.com/v1/provider/42cc20a3-2f65-2390-b5eb-2170b1cab999
Keep a note of this full URL and leave this page open
On G Suite
3. Resume with G Suite new application setup window, from Step 4 (Service Provider Details):
ACS URL (copy and paste this URL): https://api.production.perkbox.services/sso/v1/provider/saml/callback
NB for Aus locations enter the url : https://api.production.us-west-2.perkbox.services/sso/v1/provider/saml/callback
Entity ID: https://sso.perkbox.com/v1/provider/YOUR_VALUE_FROM_STEP_2
Start URL: (can be left blank)
Signed Response: (can be left blank)
Name ID: (leave at default settings)
Name ID Format (drop down menu with preset values): PERSISTENT
Click next to go to Step 5 (Attribute Mapping):
As minimum, Perkbox requires three attribute mappings, email address, first name, and last name. Copy the following URLs in the table below and map to your respective user attributes:
https://sso.perkbox.co.uk/SAML/Attributes/User/Email : users email address
https://sso.perkbox.co.uk/SAML/Attributes/User/FirstName: users first name
https://sso.perkbox.co.uk/SAML/Attributes/User/LastName: users last name
Click finish
Click into Service Provider Settings
Click ‘manage certificates’
Download the IDP METADATA from Certificate 1
You’ll then need to turn on the SAML App
On Perkbox
5. Upload the metadata file again to step one and then click continue
Click test and save
Log out and test from the login screen