SAML Single Sign-On (SSO) allows enterprise merchant users to access the TableCheck Manager in-restaurant application using their existing corporate login session. This uses the SAML 2.0 (Security Assertion Markup Language) authentication mechanism, without requiring an additional password. This is also referred to as a “Federated Login”.

Important: SAML SSO for merchants should not be confused with TableCheck Booking Page SSO for diners. For the latter, please refer to the Web Booking v1 API.

Target Audience

SAML Single Sign-On is recommended for use by large enterprises such as hotel brands who have a corporate network environment.

The below is a partial list of authentication systems which can support SAML 2.0:

Implementation Guide

Core Concepts

In a SAML 2.0 authentication flow:

• Your authentication service acts as the Identity Provider (“IdP”). It provides trusted information about the user’s identity.

• TableCheck acts as the Service Provider (“SP”). We are the service which the user wishes to access.

• When your user accesses the TableCheck Manager via the web, TableCheck communicates with your IdP system using SAML to verify the user’s identity. Specifically we require their email address, which is used as the login username in our system.

• All SAML requests a digitally signed, meaning that we as the SP can trust the user is who your IdP says he/she is and securely log them into our system.

Implementation Workflow

Step 1. Prepare your IdP Service and IdP Metadata XML

Please generate a SAML IdP Metadata XML file using your Authentication Service. Kindly refer to your Authentication Service Provider’s documentation regarding specific configurations.

IdP Service Configuration

Please ensure that your IdP service is configured as follows:

• Your SAML IdP endpoints (SingleSignOnService, etc.) must use HTTPS.

• Your SAML IdP system must have “signing” enabled on messages.

• We prefer for your SAML IdP system disable “encryption”. If your policy requires it, please ensure it is possible to disable during testing in order to facilitate troubleshooting.

IdP Metadata XML Format

Your IdP Metadata XML MUST include the elements as specified in the below table. Please check each item carefully. Please refer to Appendix I for sample IdP metadata file. Note that the namespaces ds: and md: may vary depending on your file. Please inform us if your authentication provider does not allow you to meet any specific requirement below.

Step 2. Determine your NameIDFormat value in your IdP Metadata XML

In order to login via SAML, TableCheck matches the NameID (user ID) in your IdP Assertion with the user IDs in TableCheck system. Your NameIDFormat specified in your IdP Metadata XML specifies what value you send TableCheck as the user ID (e.g. email, employee ID, etc.) TableCheck typically uses email addresses as our identifier for our user accounts.

We can support several patterns of NameIDFormat. Please read the below carefully to determine which is appropriate for your use case.

Pattern A: Use NameIDFormat “emailAddress” (preferred)

If you all your users have a standardized email address, please set NameIDFormat as urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress in your IdP Metadata XML. We will directly match the email in your SAML to TableCheck user accounts (case-insensitive.)

Pattern B: Use an employee ID and create dummy email accounts in TableCheck

If your users do not have a standardized email address, and you use an alternative identifier such as an employee ID, we recommend to setup TableCheck user accounts with “dummy” email addresses. For example, if your employee’s ID is ABC123, we would create a TableCheck user account as abc123@your-company.com. (Such user accounts do not need to have a real-world email inbox.)

In order to use this pattern:

• Your IDs must be case-insensitive. For example, ABC123 and abc123 are considered the same ID.

• Your IDs must never contain the @ character, as it would be confused with an email address.

• Your ID should be unique for each employee (though not a hard requirement.)

• You should include the employee’s email (if available) in your IdP Assertion as an Email SAML attribute.

If your wish to use this pattern, please set NameIDFormat in your IdP Metadata XML as one of the following values:

• urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Lastly, it is possible to use both employee IDs and real email addresses on a per-user basis, however, please discuss with TableCheck’s API team first.

Pattern C: Other NameIDFormat or Attribute

If neither Pattern A nor B satisfies your requirements, please discuss with TableCheck’s API team. Kindly note that we cannot support temporary or single-use login IDs (e.g. urn:oasis:names:tc:SAML:2.0:nameid-format:transient)

Step 3. (Recommended) Prepare an IdP Metadata Web Service

Please prepare an HTTPS URL endpoint at which we may retrieve your latest IdP Metadata in XML format via a GET request. This helps to facilitate key rotation.

• The URL should return your live IdP Metadata XML, reflecting any changes (config, key additions, etc.) made on your end in real-time.

• The Content-Type response header must be application/xml, and the response body should contain only your IdP Metadata without additional items.

• The endpoint should be publicly accessible, i.e. without authentication required.

• Please provide separate endpoints for Production and Staging/QA/UAT environments, if applicable.

• We will poll the endpoint for changes once per hour.

Please discuss with our team if you are unable to provide such an endpoint.

Step 4. Raise a request to TableCheck

Please send a mail to api@tablecheck with subject “<Your Company> SAML Integration Request”. Please include the following item:

1. Your IdP Metadata XML.

   • Can be either as either a URL endpoint (recommended) or XML file.

   • Please include separate items for both Production and Staging/QA/UAT environments, if applicable.

   • If you are unable to provide a URL endpoint, please provide an email address at which we may notify when new signing certificates are issued.

2. Your NameIDFormat and an explanation of we can match your user IDs to TableCheck user accounts (see above.)

3. An explanation of your IdP certificate rotation methodology.

   • Refer to “Certificate Expiry and Rotation” section below.

4. Your requirements for the SP digital signing certificates used by TableCheck, if any

   • Please check if your policy requires use of a specific certificate authority (e.g. in-house).

   • If not specified, we will use self-signed SP certificates.

5. A list of email domains to whitelist for SAML access.

   • Please list an any subdomains explicitly.

   • Example: @your-company.com, @sub.your-company.com, @other.domain.com

6. A list of emails (or user IDs) to create test user accounts for both Staging/QA/UAT and Production certification testing.

* Items 5 and 6 above may be provided during certification testing.

Step 5. TableCheck configures your SAML Integration

Upon receipt of Step 3, the TableCheck API Team will take approximately 5 business days to configure your SAML Metadata. If any issues are found with respect to the above requirements, we will ask you to re-submit your file and the process will be delayed.

When configuration is complete, we will reply by email with:

• The list of test user accounts we have added in the TableCheck system.

• Our SP Metadata URL.

Step 6. Upload and configure TableCheck’s SP Metadata in your system

Our SP Metadata is accessible via HTTPS endpoints resembling the below URLs. Our SP Metadata will be digitally signed as instructed in Step 3.

• https://id.app.tablecheck.com/sso/saml/<your company>/metadata/sp
  Our SP Metadata XML specific to your SAML integration. Please use this to configure your SAML integration with us. Please also poll this endpoint regularly (i.e. once per hour) for any changes to keys.

• https://id.app.tablecheck.com/sso/saml/<your company>/metadata/idp
  Our cache of your IdP Metadata XML. Useful for troubleshooting.

Please configure your authentication system to automatically poll these URLs for changes at a 1 hour interval. If this is not possible, you must manually copy the SP Metadata into your system.

Step 7. Certification Testing and Go-Live

Upon your acceptance of our SP Metadata in Step 5, we will schedule certification testing in both Staging and Production environments. As our system allows fully dynamic configuration, we prefer to coordinate testing both Staging and Production in the same session, if permitted by your Change Policy.

Upon successful Go-Live, we will send a Certification Sign-off email and will ask your reply on the same. Following Go-live, our Implementation Team will coordinate with your end-user venues and properties to activate SAML integration for their TableCheck user accounts.

Certificate Expiry and Rotation

The IdP and SP XML metadata files contain each party’s certificates for which the opposite party should use when signing and/or encrypting its SAML messages. This section explains methodology by which we can exchange our respective metadata files, to ensure each party has an up-to-date copy of the other party’s certificates.

The digital signing certificates used to sign SAML messages expire after a given validity period, typically between 6 months and 3 years.

SP (TableCheck) Certificate Rotation

Three (3) months in advance of certificate expiry, we will publish new certificate(s) in our SP Metadata URL (see Step 5 above.) For the three month period prior to expiry, the SP Metadata XML will include <md:KeyDescriptor> elements for both the current and new certificate(s) listed in that order. The current certificate will be used to sign requests until midnight UTC one day before expiry, at which time the new certificate will take effect and the old certificate will be removed.

If you are unable to poll our HTTPS endpoint for changes, we can configure our system to send email alerts at the following timings:

• Three (3) months before expiry (when the new certificate is published)

• One (1) month before expiry

• One (1) week before expiry

IdP (Your) Certificate Rotation

We ask that you follow a similar rotation methodology which includes the following:

• Please publish new certificates alongside existing certificates in your IdP Metadata for a reasonable overlap period.

• Please provide an HTTPS endpoint at which we may poll for updates to your IdP Metadata. If this is not possible, please provide some alternative method by which you push your updated IdP Metadata to us, e.g. as an attachment to an automated email.

• As a shared goal between our companies, we wish to minimize the amount of communication and manual work necessary to perform rotation.

Appendix I: Sample IdP Metadata XML File

The IdP Metadata XML file which you generate should look similar to the following. This file is provided for references purposes only; signatures, etc. will not validate correctly.

Appendix II: Sample TableCheck SP Metadata XML File

TableCheck’s SP Metadata XML will look similar to the following. This file is provided for references purposes only; signatures, etc. will not validate correctly. Note that this file contains TableCheck’s certificates.