Outbound Federation

Introduction

Outbound Federation enables users that are already authenticated with Fourth to access other web applications using their Fourth credentials. With SAML Outbound Federation:

  • Fourth is the Identity Provider (IdP)
  • Your business is the Service Provider (SP)

All connected apps in Fourth Engage use Outbound Federation.

This page explains how to integrate with Fourth using Outbound Federation. You may also want to read:

Fourth Identity & Access Management for an overview of our solution.

Single Sign-On & SAML if you need more information about these topics.

Federated Authentication if you are integrating Okta or Active Directory with Fourth.

Why use Fourth as the IdP?

Fourth's platform is tailored to the hospitality industry, and this includes its user management. The platform manages employee user accounts easily, regardless of whether they are a new starter (or yet to join), currently employed, have finished their employment, or have rejoined the business. As many hospitality employees are not given email accounts, key to Fourth's user management is our ability to create and manage users without needing an initial email address or other identifier. This means that partners can also leverage Fourth's user management to do the difficult work of confirming that a user account is valid regardless of whether they have an email address for the customer's domain.

And, as an IdP, Fourth Identity & Access Management includes strong security features, such as:

  • Robust authentication services to verify users
  • Centrally-controlled access permissions for modules
  • Customer-specific password complexity rules
  • Enforcement of two-factor authentication
  • Identity event logs, for auditing purposes

SAML Workflow

We support both IdP-initiated and SP-initiated Outbound Federation. Connected apps must support IdP-initiated federation.

Steps to integrate

Step Description
Step 1   Decide on the Federation ID you wish to use, and how you will synchronize users, and confirm this with Fourth. 
Step 2  
Provide Fourth with the following SAML SP metadata information:
  • Entity ID: This is a globally unique identifier for a service provider. Please provide a URL that your business controls to act as your ID.
  • Assertion Consumer Service (ACS) URL: The endpoint that the SAML assertion will be POSTed to.

Fourth uses this information to add a trusted application (your business) to our system.

Step 3
Once the application is set up, Fourth provides you with an IdP metadata file which includes:
  • X509 certificate information
  • IdP Login URL: This is the endpoint that the SP sends AuthnRequests.
  • Single logout URL: The URL to send single logout requests.
You will need to add this file (or the data within) to your server.
Step 4 Test the single sign-on connection. Fourth will provide you with a login to a sandbox environment and dummy user accounts for testing.
Step 5 Go live!

Federation ID options

The Federation ID is the identifier that the SP and IdP agree to use to identify each end user. We have the ability to use any identifying information that our platform knows about the end users. However, the most common options used by Fourth and its partners are:

  • Fourth Account ID — We recommend using this ID in all possible scenarios, as it is a unique identifier that all users are immediately assigned. We offer several APIs for retrieving employee details, including their Fourth Account ID.
  • Payroll number — The payroll number may be suitable when the mutual customer is not using Fourth's Workforce Management solutions, and the employee data is provided to Fourth from a separate system. 
  • Email address — If necessary, we can use the email address of user. However, it is not recommended, as many hospitality users do not have corporate email address, and so may use multiple personal email addresses, or may not yet have an email address listed within Fourth.

Synchronizing user accounts

Once you've decided which Federation ID to use, you need to decide how to create users in your system with the user data in Fourth. And of course, Fourth needs to notify you whenever a new user is created or terminated so that our systems remain synchronized. There are a few options for doing this, and which one to use depends on both your system's capability to consume data and how much information you need about each user. The options are:

Fourth Account SCIM API
This API leverages the existing System for Cross-domain Identity Management (SCIM) standard.  It's ideal for applications that need to know a small range of employee data useful for user provisioning, such as their name, job title, location, or preferred language.

Workforce Management APIs
Our Workforce Management APIs can provide extensive employee information about both current and terminated employees. We recommend this option only if your application needs detailed information about the user. Depending on the Fourth product your customer is using, you will need to either connect via the:

Workforce Management Export
Fourth can generate a .csv file with the same employee data that is available through the Workforce Management APIs. Fourth can also accept employee data via a .csv file.

Just-in-time (JIT) Provisioning

SAML supports JIT provisioning. Less information is passed in the token, but the user is created as soon as they log in the first time.

Attributes

Information about the end user is sent in the attribute statement of a SAML assertion. An attribute is simply a name-value pair, which we can customize if necessary.

By default, Fourth sends the following attributes in the SAML assertion.

Attribute Description
email

The email address of the user. This is not guaranteed to be unique.

FirstName The first name of the user.
LastName The last name of the user.
LongUserId The Fourth Account ID. This is an 18-digit alphanumeric string.

Mobile app limitations

Web apps

By default, we use the WkWebView to launch third-party applications from the Fourth App. This provides a good user experience, as the user doesn’t leave the Fourth App. However, it does mean the following for your web app:

  • Pop-ups: Users cannot open additional windows (i.e. pop ups) when viewing your site.
  • File downloads: Users cannot download files from pages displayed in WkWebView.
  • Adobe Captivate: Unusual formats that aren’t quite HTML5 are not supported.

If your app requires these functionalities, please let the Fourth partnership team know, as we can enable your app to open in a new browser window.

Native apps

Single sign-on is possible even if your product uses a native app, rather than a web app. This is achieved by embedding a web view within your application. We can provide further advice if you wish to use SAML with your native app, just get in touch with our Partnerships Team.

FAQs

For IdP-initiated SAML — what should you do if you do not recognise the federation ID?

If you receive a SAML assertion for an end user that you do not recognise, your application could:

  • Reject the user, displaying an "unauthorized" response.
  • Perform "just in time" provisioning; that is, create a new user account on the fly.

Which option you choose to do will depend on your type of business. We can guide you on your decision during the onboarding technical call, if you're not sure. 

What happens if the user fails to authenticate with Fourth?

We will show the end user a username and password authentication screen after a failed attempt. We do not limit the number of times a user can attempt authentication.

We do not send a SAML message to your platform unless the user successfully authenticates.

How are users logged out?

There are two options that can occur based on the behavior the IdP and SP have agreed upon:

  • Independent logout: The user is logged out of the session that they currently have with either the IdP or SP only.
  • Single logout: The user is logged out of all sessions with the SP and IdP that are using the same single sign-on. The IdP also updates any other third-party SP sessions that support single logout.

Your business can choose whether or not to support single logout.

Sample Fourth IdP metadata file

In the sample:

  • X509Certificate holds the certificate data (and has been truncated in this example).
  • The IdP Login URL is either (depending on your binding):
    • https://secure.fourth.com/idp/endpoint/HttpPost
    • https://secure.fourth.com/idp/endpoint/HttpRedirect
  • Single logout URL: https://secure.fourth.com/services/auth/idp/saml2/logout
<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://fourth-app.my.salesforce.com" validUntil="2029-07-17T10:23:51.357Z" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
   <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
      <md:KeyDescriptor use="signing">
         <ds:KeyInfo>
            <ds:X509Data>
               <ds:X509Certificate>7xFF7...pwqp=</ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </md:KeyDescriptor>
      <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://secure.fourth.com/services/auth/idp/saml2/logout"/>
      <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://secure.fourth.com/services/auth/idp/saml2/logout"/>
      <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
      <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://secure.fourth.com/idp/endpoint/HttpPost"/>
      <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://secure.fourth.com/idp/endpoint/HttpRedirect"/>
   </md:IDPSSODescriptor>
</md:EntityDescriptor>

Sample SAML assertion from Fourth

This sample assertion includes the default set of attributes: FirstName, LastName, email, and LongUserId (the Fourth Account ID, which is used as the Federation ID). It also includes some additional attributes that the integration required: is_portal_user and username.

<?xml version="1.0" encoding="UTF-8"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Destination="https://stage.acme.com/here/loginsso.aspx" ID="_b2b5496918b52fc48fa16015dd6984582ac19ec68c560" IssueInstant="2019-04-11T12:09:45.960Z" Version="2.0">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://fourth-app.my.example.com</saml:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
      <ds:Reference URI="#_b2b5496918b52fc48fa1582ac19ec68c56015dd698460">
        <ds:Transforms>
          <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
          <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"><ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="ds saml samlp xs xsi"/>
          </ds:Transform>
        </ds:Transforms>
        <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <ds:DigestValue>MyYXAErM8DfLocwVE6i3iBy9SAA=</ds:DigestValue>
      </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>Ksr...H2g=</ds:SignatureValue>
    <ds:KeyInfo>
      <ds:X509Data>
        <ds:X509Certificate>7xFF7...pwqp=</ds:X509Certificate>
      </ds:X509Data>
</ds:KeyInfo>
</ds:Signature>
<samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_38321a698497c93ff86362871b555915aa56549845861" IssueInstant="2019-04-11T12:09:45.961Z" Version="2.0">
  <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://fourth-app.my.example.com</saml:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
      <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
      <ds:Reference URI="#_828458497c95543f31a5596115698367919f863628aaf863628aa55b5">
        <ds:Transforms>
          <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
          <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
            <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="ds saml xs xsi" />
          </ds:Transform>
        </ds:Transforms>
        <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <ds:DigestValue>Bkf02ia5jIrWVjd9F41MuvMv1W+=</ds:DigestValue>
      </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>rsK...g2H=</ds:SignatureValue>
    <ds:KeyInfo>
      <ds:X509Data>
        <ds:X509Certificate>7xFF7...pwqp=</ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </ds:Signature>
  <saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">string@example.sso@fourth.com</saml:NameID>
    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml:SubjectConfirmationData NotOnOrAfter="2019-04-11T12:14:45.961Z" Recipient="https://stage.acme.com/devhere/loginsso.aspx" />
    </saml:SubjectConfirmation>
  </saml:Subject>
  <saml:Conditions NotBefore="2019-04-11T12:09:15.961Z" NotOnOrAfter="2019-04-11T12:14:45.961Z">
    <saml:AudienceRestriction>
      <saml:Audience>https://stage.acme.com/here/</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AuthnStatement AuthnInstant="2019-04-11T12:09:45.961Z">
    <saml:AuthnContext>
      <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
    </saml:AuthnContext>
  </saml:AuthnStatement>
  <saml:AttributeStatement>
    <saml:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">sso-example@example.com</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">user@example.com</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="is_portal_user" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">true</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="longUserId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">0510AAq000M010cAS1</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="LastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">Acme Example</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="FirstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">Test SSO</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>