Single sign-on (SSO) allows users to log into Prescreen using an existing identity without the need to remember additional login data. The user identity can be provided from various sources (e.g., Google Workspace, your own active directory, etc.). We utilize SAML 2.0 (Security Assertion Markup Language) in order to provider a secure and standardized single sign-on mechanism. Read below the steps necessary in order to setup SSO with SAML 2.0 and Prescreen.

Table of contents

1. SAML setup

2. Things to consider after the setup

3. Troubleshooting

1. SAML setup

Step 1: Log into Prescreen and go to "Settings" (1) > "Integrations" (2) > "Single Sign-on" (3). Find the link to an XML schema containing all necessary information to configure your SAML 2.0 identity provider under "Service provider XML" (4).

Step 2: Now setup your SAML 2.0 identity provider (IdP). This step may vary slightly depending on which IdP you are using. However, the output of this step should be an SAML 2.0 IdP metadata XML file including a valid certificate. Please contact your IT administrator if you need help with this.

Find the path to the appropriate instructions in this overview:

The identity provider metadata XML file should have the following format. This is an example from Google Workspace:

<?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-URL (AssertionConsumerService) found in the XML described in step 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.

Step 3: Go back to Prescreen > "Settings" (1) > "Integrations" (2) > "Single Sign-on" (3) > "SAML 2.0 Identity providers" (4) and click on "Add identity provider" (5).

Fill in the required information, paying attention to the following fields:

1. USER ATTRIBUTE: This field defines, which attribute of the Prescreen user is used for authentication: email or active directory username. In case of the active directory username please contact our support so we can setup your account accordingly.
2. SAML-RESPONSE ATTRIBUTE: With this field you can select which XML response attribute (containing the identifying information) we should use for authentication. The following options are available:
   - Subject Name-ID
   For example:

   <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">user@example.com</saml:NameID>

   - Custom Attribute Statement
   In case of a custom attribute statement, the name must match your identity provider 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 identity provider solutions use the full URL schema as naming convention e.g.: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   
   
3. METADATA FILE: Upload in this field your metadata file.

After you have filled in everything, click "Save". Log out of Prescreen and now you should be able to sign in using your configured identity provider.

2. Things to consider after the setup

• If you are using Google Workspace (formerly known as Google Apps or 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 by using your Prescreen login credentials. If you want to provide both login possibilities simultaneously, please contact our support team.

3. Troubleshooting

• 404 page: If you are experiencing a "404" error message after getting redirected to Prescreen after a successful login, please check if the username (in most cases the email address) of the 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.
  
  
• Other errors: If you have configured everything according to our guidelines and still experience any errors, please contact our support team. In order to solve your issue faster, please try to include the following information 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.
  - When possible: please attach the unencrypted SAML response.
•