Configuring SAML Single Sign-On in Prescreen
Single sign-on (SSO) allows users to login into Prescreen using an existing identity without the need to remember addtional login data. The user identity can be provided from various sources (e.g. Google Apps for Work, your own Active Directory, etc.). We utilize SAML 2.0 in order to provider a secure and standardized single sign-on mechanism. Below we describe the steps necessary in order to setup SSO with SAML 2.0 and Prescreen.
- In Prescreen go to Account > Integration > Single sign-on
- Under "Service Provider XML" you can find a link to a XML schema containing all necessary information to configure your SAML 2.0 Identity Provider.
- Setup your SAML 2.0 Identity Provider (IdP)
Depending on which IdP you are using, this step may vary a little bit. However, the output of this step should be a SAML 2.0 IdP metadata XML file including a valid certificate. Please contact your IT administrator if you need help with this.
- If you are using Google Apps for Work (G Suite) you can find a setup guide here.
- A guide for Microsoft Active Directory with ADFS (Active Directory Federation Service) can be found here.
- A guide for Microsoft Azure AD can be found here.
- A guide for OneLogin can be found here.
The IdP metadata XML file should have the following format. This is an example from G Suite:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://accounts.google.com/o/saml2" validUntil="2022-02-28T14:34:20.000Z"> <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate>CERTIFICATE</ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://accounts.google.com/o/saml2/idp"/> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://accounts.google.com/o/saml2/idp"/> </md:IDPSSODescriptor> </md:EntityDescriptor>
- Metadata XML file:
- WantAuthnRequestsSigned should be false!
- When configuring Windows Azure the "Reply URL" should be the ACS (AssertionConsumerService) URL found in the XML described in point 2.).
- SAML Response:
- The main assertion must include the authentication statement: AuthnStatement.
- The InResponseTo attribute must be included and should contain the ID from the SAML Request.
The following steps assume, that you have generated a valid SAML 2.0 IdP metadata (certificate) file.
- Metadata XML file:
- Back in Prescreen click "Add identity provider"
- Fill in the required information, select your metadata file and click "Save".
- The USER ATTRIBUTE field defines, which attribute of the Prescreen user (e-mail or active directory username) is used for authentication. In the case of AD username please contact our support so we can setup your account accordingly.
- With the SAML-RESPONSE ATTRIBUTE field you can select which XML response attribute (containing the identifying information) we should use for authentification. Available options are:
- Subject Name-ID. Example: <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">firstname.lastname@example.org</saml:NameID>
- Custom Attribute Statement
In case of a custom attribute statement, the name has to match your IdP configuration. For example: If you are returning a user field named "EmailAddress" (this is the default in many cases), it must have the same name in the Prescreen SAML configuration. Some IdP solutions use the full URL schema as naming convention e.g.: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- After logging out you should now be able to sign in using your configured Identity Provider.
Things to consider after the setup:
- If you are using Google Apps for Work (G Suite) as Identity Provider it can take up to 24 hours on their side to activate new configurations or changes.
- By default, adding a SAML 2.0 Identity Provider results in deactivating the possibility to login manually (using Prescreen login credentials). If you want to provide both login possibilities simultaniously, please contact our support: email@example.com
- If you are experiencing a 404 page after getting redirected back to Prescreen after a successful login, please check if the username (in most cases the e-mail address) of the Prescreen user matches the one in your active directory.
Also check, if the username in your SAML response is passed in the correct SAML attribute (NameID or custom attribute) according to your configuration in Prescreen.
- If you have configured everything according to our guidelines and still experience any errors, please contact firstname.lastname@example.org
In order to solve your issue faster, please try to include the following in your support request:
- Date and time when the SSO / SAML login process was started (when you clicked the SSO button in our login mask)
- Date and time when you got redirected to our ACS url
- If possible, please attach the unencrypted SAML response.