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