SAML 2.0 Integrations

Overview

The Oleeo application may be integrated with SAML 2.0 SSO implementations to allow authentication and minimal authorization via external identity providers. Features include:

  • Authentication of recruiters using the Client’s identity provider.
  • Optional account creation if an account does not already exist

SSO assertions must supply:

  1. A unique ID which is used as the UserID for that user in the ATS.
  2. First name
  3. Last name
  4. Email address

Changes to user details (e.g. name and email address) are updated automatically for assertions which match existing unique IDs.

Standard SSO integration does not include authentication of candidates. All candidates (including internal candidates, and users with recruiter accounts which may want to apply for internal positions) must register and login through the standard Oleeo registration screen and username/password authentication screen.

SAML Implementation and Supported Features

Oleeo uses a Shibboleth open source SAML implementation as a service provider to support SAML 2 authentication. Oleeo expects the client to host a SAML 2 identity provider service.

Oleeo supports certificates issued by any authority: either client issued or issued via Certificate Authority.

Oleeo supports the Authentication Request Protocol via HTTP POST Binding. Oleeo do not host an Identity Provider service. The standard service is implemented as SP Initiated but IdP initiated can be supported and may be preferable in mixed-authentication environments. Unauthenticated users or users with expired sessions or expired assertions can be redirected to a single URL (which would normally be the Oleeo SP SAML service but could be the IDP or any client-hosted landing page for IDP initiated authentication).

Oleeo do not currently support Single Logout Protocol, Name Identifier Management Protocol, Name Identifier Mapping Protocol (and Artefact Resolution Protocol), metadata monitoring, or deep linking (newly authenticated users always go to default home page).

Summary of Authentication Flow

For SP initiated SSO, Oleeo provide a single URL for all recruiter logins to the live client system via SAML2.

Access to the recruiter URL is protected by the Shibboleth open-source implementation installed within the Oleeo secure hosting environment.

A recruiter attempting to access the recruiter Shibboleth URL should be redirected through to the appropriate authentication service (the clients Identity Provider (IdP)).

If a recruiter already has an authenticated session at their local IdP then the user will be redirected back to Oleeo with an appropriate assertion and then redirected to the ATS home page.

If a recruiter is not logged in at their IdP then the user will be directed to an appropriate login page (hosted outside of Oleeo) for login. If a recruiter fails authentication then they will be shown an error page by their local identity provider.

When an authenticated recruiter is passed from the IdP to Oleeo then Oleeo’s SAML service will expect to receive an assertion with the user’s identifying attributes from the external identity provider which must include:

  • a unique identifier for each user e.g. <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="username"/>
  • first name e.g <Attribute name="urn:oid:2.5.4.42" id="firstname"/>
  • last name e.g <Attribute name="urn:oid:2.5.4.4" id="surname"/>
  • email address e.g <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="email"/>

On receipt of a valid assertion:

If the identity is found to match an existing user in the Oleeo system, then the user will be logged into the Oleeo system as the identified user. The Oleeo system can be configured to update the user account with information from the assertion (first name, last name, email).

If no appropriate matching record is found then the Oleeo system can be configured to either:

  1. Not allow authentication to proceed or
  2. Create a new user record using personal details from the additional Attributes and initialising authorisation access rights.

SSO Setup

Oleeo needs to create a system for the client before any features of SAML can be set up. As part of this implementation, Oleeo will agree a client-id which will be used in the URL of the system. For standard implementations the system will be hosted under the *.tal.net domain using a client specific identifier e.g. [client_id].tal.net. Default implementations provide two systems per client, one for ‘live’ use and one ‘config’ for configuration and testing. The ‘config’ system will append -config to the client_id e.g. [client_id]-config.tal.net.

Once the initial system has been created, federation metadata must be exchanged between the client and Oleeo in order to configure the instance of a SAML implementation. The client must provide metadata for their IdP service, and Oleeo must provide metadata for the specific client’s system within the Oleeo ATS environment. Metadata can be exchanged via URL or file. Oleeo’s Service Provider metadata for live and config can be obtained at https://[client_id].tal.net/shibboleth/metadata and https://[client-id]-config.tal.net/shibboleth/metadata respectively.

Oleeo’s Service Provider Metadata

The following is an example of an Oleeo metadata file (but this example cannot be used for setting up any actual SSO implementation):

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://client_id.tal.net/shibboleth">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
    <md:KeyDescriptor>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>
            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
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://client_id.tal.net/Shibboleth.sso/SAML2/POST" index="1"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://client_id.tal.net/Shibboleth.sso/SAML2/POST-SimpleSign" index="2"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https:// client_id.tal.net/Shibboleth.sso/SAML2/ECP" index="3"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="https:// client_id.tal.net/Shibboleth.sso/SAML/POST" index="4"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

The client must supply metadata to Oleeo either by file or by URL. If the client has live and test identity providers then the test IdP should be configured to use the Oleeo ‘config’ environment metadata.

Client’s Identity Provider Metadata

The following is example metadata that Oleeo might expect to receive from a client (in this case it is an example from a third-party SSO provider okta.com.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor entityID="http://www.okta.com/eXko04iH8roYJXVGW0x7" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <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>
            MIIE/zCCBGgCAg4CMA0GCSqGSIb3DQEBBQUAMIGbMQswCQYDVQQGEwJKUDEOMAwG
            A1UECBMFVG9reW8xEDAOBgNVBAcTB0NodW8ta3UxETAPBgNVBAoTCEZyYW5rNERE
            MRgwFgYDVQQLEw9XZWJDZXJ0IFN1cHBvcnQxGDAWBgNVBAMTD0ZyYW5rNEREIFdl
            YiBDQTEjMCEGCSqGSIb3DQEJARYUc3VwcG9ydEBmcmFuazRkZC5jb20wHhcNMTIw
            ODIyMDcyNzIyWhcNMTcwODIxMDcyNzIyWjBKMQswCQYDVQQGEwJKUDEOMAwGA1UE
            CAwFVG9reW8xETAPBgNVBAoMCEZyYW5rNEREMRgwFgYDVQQDDA93d3cuZXhhbXBs
            ZS5jb20wggNHMIICOQYHKoZIzjgEATCCAiwCggEBAMbmu6uSdZWRxnO5PteARz5I
            nrdM7vJadzJcY9Spf0cAhUDWyINCrUDn8h8QjbMiAxd+E7v5N85TbfvrW+/g7lYa
            e7DB0uX02Rw29yoK+TE/znNTNq6HdPn/H4ll77uJqpkWgQwXgAQ3qDKRv96QaTfr
            fSXYRxG9NvKzUBs9S7Woby7K6Pgh7/EmgeiOHKSX49XD+ihvkFRSFdeL5qV5hzDf
            epfk8Ghl0cyK9jpM/yKlRuUUkP1pSMwUrCrptyRpqqXmam0UfFuFhMT2SJyNTyo2
            SfnyZb78lbYcVLJQLJA+O3l469eOH3Odv/Pq7bvOstBKg96Q7imz5t0honf63EMC
            IQCw7FeY0QQbxWYy+MI8/0m2kiRzIruA8RUPcEs4il1mwwKCAQB4W3QLepQRTWhR
            69Xv+fC5JLEDyngw9KEalKorlg6o4Z9hASMbFMwECjlXZCxKd/NFjUMbtPcrMCoa
            /KuaqRvHLs2bqe94X5VR4lWCv0SgOunKBj58jnVuN/OkkLu4cSZQ/jia/yPkdcMv
            w8ZjF7zjPXGVhh9XC0QU9ipVfrreGaBSN+0zODKY5TyQI84FsZFZNetOTIT0HT2S
            fIDRGYaL/0xMfQx070Z07cdTTuibzJHVr38qjKqEDiwAUyjXVdE+GJ15ZD4d56Ef
            0qgRpzDmuvUjOtv1t8Hr2O2HTABqRMtAKZsLEVPjwnpKpcStixfg0uIPGVIKbej4
            FzHHpO6bA4IBBgACggEBAJNRaaTFe253sOVm/JmUgsO1QB5GI5hOEWLpC8KHxgwn
            nf/GQUaJLrN8TT4hXgJM2CdvdAkY6et1HpT6BUoz1cYTgsE3ToIsbH3SzPJvU7jz
            cPOvY1jQv+xVBrU8Ydw2D8pydbAcw/L6JZnGpFBqeHa1iFAQc0B8ToXEgxnmGAdP
            IOAKAHX0S4m6CrP5fKwYbmzu8WuWO4bRqvX7QJofrs2RaGFESulw0VrMFffJ/guf
            HTvhDaMW7TSCKo1tBZK9SdEbWCQN2stnfnRSyZFQ+v02oyQtLg+3vSuCx4PS9DM9
            /Uh3r9JDDH3GveUMbqw8Dmy6WH9iV3oOJt8aVF8F4CMwDQYJKoZIhvcNAQEFBQAD
            gYEAbxDoJM8vKVfhltpfG3YXmBKnoGb2UpdKpcjmxMt1/yX8lWJaRBwUDeiDqjVC
            JGi9gXO2SDAtXl7GI1cXTs/l7QlmoTmnc6kDwqk3pl6jC72rQH3E/Fpg7hBkSWL9
            3V1dbLU5id63lVD8sUEULyfWFGk3L+Uka5oiSsxwZhdIb/Q==
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <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-POST" Location="https://client_id.okta.com/app/client_id_oleeo_1/exko0eih7rrYJXVgW0x6/sso/saml"/>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://client_id.okta.com/app/client_id_oleeo_1/exko0eih7rrYJXVgW0x6/sso/saml"/>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

SAML Terminology

Target Resource

This is the URL which users should access when attempting to use the ATS. If the user has a valid session (has been authenticated to the ATS, an ATS session cookie has been set, and that session has not timed-out) then the user will be directed to the ATS dashboard. If the user is not authenticated then the user will be redirected to the client’s Identity Provider.

This may be referred to as ‘Start URL’.

AssertionConsumerService

The Oleeo standard implementation expects a browser-post profile. From the above metadata we would expect authenticated users browsers to be redirected such that it submits a POST with the SAML assertion as content to https://client_id.tal.net/Shibboleth.sso/SAML/POST. This end-point is referred to as Assertion Consumer Service or ACS in SAML but implementations may refer to it with other names including ‘Relying Party SAML 2.0 SSO Service URL’, ‘Single Sign On URL’, ‘Return URL’

EntityDescriptor In the above metadata example, this would be https://[client_id].tal.net/shibboleth. In some implementations it may be referred to as ‘Relying party trust identifier’ or ‘Audience URI’

Configuration Details to be agreed with Client

Oleeo will provide a single URL for all recruiter access to a system of the form: https://[clientname].tal.net/saml2 Where a config/test environment supports SAML then the URL is of the form: https://[clientname]-config.tal.net/saml2

The client must agree details of access and actions for DEFAULTRECRUITER profile.

The client must supply a SAML2 compliant identity provider service.

The client must configure their SAML implementation appropriately.

Advanced Features

The ATS supports additional features which can be discussed during implementation. These include:

  • Supporting multiple identity providers for a single system Some clients may share a single system across multiple divisions and individual divisions may implement their own IdP. The ATS can support multiple IdPs but either a single federated service must be provided by the client so that the SP initiated requests can be redirected to a single address (the ATS cannot know which IdP to send unauthenticated users to), or IdP initiated paradigm must be used (but note that recruiters that are not authenticated cannot be directed to the appropriate IdP).

If the auto-vivification feature is enabled then each IdP can be configured to initialise new users with a user RoleProfile specific to that IdP (e.g. the users from different divisions may have different authorisation).

  • A mix of SSO and local username/password authentication A single system can support a mix of SSO and username/password authentication. This may be useful for the config/test environment or to allow some other users access to the ATS who do not have an SSO account (e.g. API access). The ATS can enforce at the user-level that the user can only be authenticated by SSO.

  • Updating other user values from SSO parameters The ATS can be configured to populate ‘Recruiter Acess Values’ in the ATS from the SSO assertion e.g. this might be used to set the user’s Department. It is possible for such values to influence what a user can see (e.g. adjust their authorisation to view just a subset of vacancies).

  • Authorisation determined from SSO parameters SSO parameters can be used to set the users ‘RoleProfile’ in the ATS which determines their authorisation (what a user can see and what actions they can perform).

Information for clients to supply to Oleeo

The client should supply what flavour of SAML2 they are using. Many customers use Microsoft ADFS, some use PingIdentity, and some have their own implementations. This is not an essential step, but it can help make things easier especially in the later stages.

The client should describe if they have separate test and live Identity Providers. Usually the client has a QA environment and a live environment, and has two IDPs to match. Others just have one IDP for both.

The client should determine if:

  • they want the ATS to create new uses if the SAML Assertion sent to the ATS is valid but does not match an existing user.
  • they want users to be redirected somewhere after log out

Exchange of metadata. The client must make available an xml file known as metadata. This sets up some of the trust relationships and has embedded the URLs of their IDP. We would need one for each of their IdPs (so two if they support separate live and test IdPs).. Sometimes the metadata is published as a URL on their website but usually this is exchanged by email as an XML file. Some clients also want metadata from Oleeo, known as sp-metadata. Oleo can provide this once a base system has been created and system URLs have been agreed.

Oleeo require the client to send four things as attributes (“claims” in M$ ADFS language) in the SAML request, all of which are mandatory. (The ATS will raise an exception in vX visible in the error log if the appropriate attributes are not sent). The four things needed are username (must be unique and constant (email is a bad choice as email addresses can change through marriage)), email, firstname and surname. The username becomes the vX username. Oleeo does not mandate what the attribute names are - this is configurable and Oleeo will determine appropriate configuration after first login attempt.

After provisional set-up, A recruiter user should try to log in via the config /saml2 URL and inform Oleeo of the date, time, and username of the attempt. The attributes usually differ from implementation to implementation, so we expect the first login to fail. Oleeo then reviews logs to see identify the actual attribute names that are being sent. Oleeo adjusts mappings accordingly, and then usually everything works from then on!

Oleeo Preferred and Supported Options

Oleeo standard is SP initiated, but can support IDP initiated

Oleeo only supports redirect Browser POST Profile. urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Oleeo does not sign requests by default. Singing can be supported.

Oleeo support signed assertion requests and is recommended. Response signing is not supported.

Oleeo support and recommend Sha256 singing. Sha1 can be supported but is not recommended.

Oleeo can support encryption of SAML assertions but this is not default.

If assertions are encrypted, then Oleeo recommends Aes256/KwRsa15

Oleeo do not require the InResponseTo attribute to be set.

Oleeo do not require the SessionIndex attribute to be set.

Oleeo require attributes for ID (can be NameID), First Name, Last Name, Email

Oleeo do not require additional attributes, but some can be supported to enable authorisation.

Live Environment:

  • Service Provider Base URL: https://[clientname].tal.net
  • Assertion Consumer URL: https://[clientname].tal.net/Shibboleth.sso/SAML2/POST
  • Service Provider Entity ID: https://[clientname].tal.net/shibboleth
  • Oleeo will provide a Service Provider metadata file at https://[clientname].tal.net/shibboleth/metadata

Test/Config/Staging environment:

  • Service Provider Base URL: https://[clientname]-config.tal.net
  • Assertion Consumer URL: https://[clientname]-config.tal.net/Shibboleth.sso/SAML2/POST
  • Service Provider Entity ID: https://[clientname]-config.tal.net/shibboleth
  • Oleeo will provide a Service Provider metadata file at: https://[clientname]-config.tal.net/shibboleth/metadata