SAML Authentication in TMS 8

SAML Authentication in TMS 8

What is SAML authentication?


Note: This article is intended for someone familiar with the web.config file. It is best utilised by a system administrator.

SAML (Security Assertion Markup Language) Single Sign-On allows users to sign in to TMS by entering their credentials directly into the log-in page of an external Identity Provider (IdP). 
This identity provider would typically be the Active Directory server used to authenticate Windows users on the corporate network, but could also be one of a range of other implementations used to provide an interface for single sign-on.

Using SAML to log in to TMS has two unique benefits over our other authentication methods:

1. The TMS system does not have to be trusted with any log-in credentials, even when logging in from remote locations – any security policy that applies to the Identity Provider will automatically apply to TMS

2. Where employees will be logging in to other services alongside TMS, they will be greeted with a standard log-in page that they trust. Additionally, after using SAML to log in to one service, any subsequent services will log in automatically 

In contrast to the Active Directory Authentication that is available in TMS, there is no requirement for the Identity Provider to be located on the same domain as the TMS server – the only requirement is that the log-in page on the Identity Provider is accessible from the client browser.

How does it work?


When SAML authentication is enabled, browsing to the TMS site will cause your browser to be redirected to the log-in page provided by your Identity Provider.

After entering your credentials into the log-in page, your Identity Provider will authenticate them as usual. If they are invalid, an error message will be displayed by the Identity Provider, normally with an option to try again.

If the credentials were valid, the Identity Provider will return a ‘token’ to the browser, and redirect back to the TMS site. When the browser request reaches the TMS site, this token will be matched against the TMS database to find the matching user or employee, and complete the log-in.




How is it secure?


Both the TMS server and the Identity Provider web page will be protected by using HTTPS connections, as standard for secure web pages. The Identity Provider will always check the source of the identity request – the TMS service will have to be explicitly defined in the Identity Provider’s list of Relying Party Trusts. If the service is not in the list, the request will be denied.

On top of this, communications in both directions are encrypted using certificates shared between the two parties. These certificates are exchanged when the relying party trust is configured (either manually or using metadata). 

When the Identity Provider receives a request from TMS, it will check that it has been signed with the correct certificate – if not it will show an error. Then when TMS receives the token from the Identity Provider it will have been encrypted using the certificate owned by TMS – without access to the private key, the token cannot be decrypted.

When can SAML authentication be used in TMS


Version


SAML authentication is supported in TMS 8 version 8.11.5 onwards.

Products

SAML authentication can be used to log in to the Mitrefinch TMS web application. As the authentication requires a HTTP redirect to the Identity Provider, and another back to the TMS web application, it is only applicable in systems where both the TMS web application and the identity provider can be accessed from the client browser.

 

Therefore other Mitrefinch applications such as TMS for Mobile or WinTMS are unable to use SAML to authenticate users, and will instead use normal TMS authentication. SAML may be used with mobile devices or the TMS Outlook Add-in by requesting the full desktop version of the web application.


Use with other authentication methods





As SAML authentication is entirely configured in the web.config file, it can be enabled for one TMS site whilst being disabled for another site accessing the same database.
For example, if you only wanted to use SAML authentication for users not on your internal network, you could enable Windows authentication on your internal TMS site, and enable SAML on your external TMS site.

Enabling SAML authentication


To turn on SAML authentication, find the AdfsType key in the web.config file, and change it from “None” to “SAML”. If the key isn’t present in your file, pick up the updated web.config from the release package and merge the new entries into your file.

If you are on TMS 8 version 8.35.0.0, you will need to use the workaround below. If you are on 8.36.0.0 or later, skip to the "sameSiteCookies" section. If you have already used the workaround and upgraded to 8.36.0.0 or later, you will also need to complete the "sameSiteCookies" section.

Editing web.config workaround (version 8.35.0.0 and below)

Note: This workaround is only relevant to TMS 8 version 8.35.0.0 and below. Version 8.36.0.0 introduced changes to the web.config file that do not require the URL rewrite workaround.

To allow SAML authentication, changes need to be made to the web.config file. Before making the changes, ensure you download and install URL Rewrite from the following link:

https://www.iis.net/downloads/microsoft/url-rewrite 

Installing this extension will allow the following changes to web.config to work.

Once the extension has been installed, locate your web.config file and add the following lines into the <system.webServer> section. There may be several locations in your web.config file that has <system.webServer> - the correct section is around line 549, and is a section that is not nestled into another section (e.g. on line 276 the <system.webServer> is nestled into the <location path> section). The lines to add are as follows:


<system.webServer>

<rewrite>

<outboundRules>  

<rule name="AddSameSiteCookieFlag">  

<match serverVariable="RESPONSE_Set-Cookie" pattern="((.*)(__SessionId)(=.*))(SameSite=Lax)" />   

<action type="Rewrite" value="{R:1};SameSite=None" /> 

</rule>

</outboundRules>

</rewrite>

</system.webServer>

SameSiteCookies changes in Web.Config

As of version 8.36.0.0, changes have been made to the standard web.config file (this is normal found in the "WebConfig" sub-folder of the TMS 8 website folder) to support changes in how web browsers handle cookies and follow recommended security practice. The change was made to limit cross-site attacks in TMS 8. A new section of code has been introduced to the file:


<!-- sameSite and cookieSameSite can be one of [None|Lax|Strict].  For SAML authentication, the sessionState needs to be cookieSameSite="None" and the site must be https

       The httpCookies and forms setting can also specify requireSSL="true" to force cookies to be sent as https on https enabled sites, but will cause logins to fail on http only sites-->

    <httpCookies httpOnlyCookies="true" sameSite="Lax" requireSSL="true" />

    <sessionState cookieName="__SessionId" mode="StateServer" cookieSameSite="Lax" />

    <authentication mode="Forms">

      <forms name="__Auth" loginUrl="tms/login" timeout="20" defaultUrl="dashboard/home/" cookieSameSite="Lax" />

    </authentication>

As mentioned in the code snippet, this change may affect users who use SAML authentication in TMS 8.

For SAML authentication to work correctly, the following changes need to be made:
  1.  TMS 8 needs to access external cookies, and therefore the cookieSameSite flag needs to be set to "None"
  2. within the <sessionState> section, and RequireSSL needs to be set to "True".
  3. TMS 8 needs to be hosted on an https site. 
When you upgrade to version 8.36.0.0, you should take some time to review the changes to the Web.config file and make any alterations necessary to your installation of TMS 8. Further information on SameSite cookies can be found by searching online. 

Editing saml.config

With SAML authentication enabled, the TMS web server will attempt to load connection details from a file names saml.config. Create this file in the same directory as web.config, either using the sample file provided by Mitrefinch or by copying the XML below:

<?xml version="1.0"?>

<SAMLConfiguration xmlns="urn:componentspace:SAML:2.0:configuration">

  <ServiceProvider Name="https://tms.myserver.com/"

    AssertionConsumerServiceUrl="https://myserver.com/tms8/TMS/Saml/Index"

    LocalCertificateFile="adfs-sign.pfx"

    LocalCertificatePassword="pass" />

 

  <PartnerIdentityProviders>

    <PartnerIdentityProvider

      Name="https://adfs.myserver.com/adfs/services/trust"

      Description="ADFS"

      SignAuthnRequest="true"

      SignLogoutRequest="true"

      WantSAMLResponseSigned="false"

      WantAssertionSigned="true"

      WantAssertionEncrypted="true"

      WantLogoutResponseSigned="true"

      DigestMethod="http://www.w3.org/2000/09/xmldsig#sha1"

      SignatureMethod="http://www.w3.org/2000/09/xmldsig#rsa-sha1"

      SingleSignOnServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

      SingleSignOnServiceUrl="https://adfs.myserver.com/adfs/ls/"

      PartnerCertificateFile="adfs_token_signing.cer"

      SingleLogoutServiceBinding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

      SingleLogoutServiceUrl = "https://adfs.myserver.com/adfs/ls/"/>

  </PartnerIdentityProviders>

</SAMLConfiguration>


HTTP-POST configuration

If your saml.config file specifies that the SingleSignOnServiceBinding ends with "HTTP-POST" (as in the above example), then you need to ensure that your web.config is updated. In particular, the Content-Security-Policy needs to be updated to include the SAML server address directly after the form-action value, with a space between the address and 'self'. For example, using the above SingleSignOnServiceBinding (that includes HTTP-POST) setting, the Content-Security-Policy line in the web.config file would be updated to something akin to the following (value that is added highlighted):

<add name="Content-Security-Policy" value="default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' npmcdn.com; style-src 'self' 'unsafe-inline';img-src 'self' data:; frame-src *; frame-ancestors 'self'; form-action 'self' idp.saml.example.examplecompany.co.uk;" />

Saml.config Service Provider



The ServiceProvider part of the file describes the TMS system to your Identity Provider. This is always required, whether you are configuring manually or using metadata.

 

The name is the identifying string for your TMS service on your Identity Provider – normally you will set this to match your main TMS URL. The AssertionConsumerServiceUrl is the path to TMS/Saml/Index in your TMS web directory, and the LocalCertificateFile is the path of the certificate you wish to use. If only a name is specified (as above), it will look for the file in the TMS web directory.

 

When configuring the Relying Party Trust on your Identity Provider, the details must match as follows:

 

Name

Must be added as a Relying party identifier

 

AssertionConsumerServiceUrl

Must be used as the URL for a POST SAML Assertion Consumer Endpoint, and (where single log-out is required) for POST and Redirect SAML Logout Endpoints.

 

LocalCertificateFile

The corresponding public key (*.cer file) should be set as the Encryption certificate, and Signature verification certificate.

 

Secure hash algorithm

Note also that the secure hash algorithm of the relying party trust must be set to SHA-1.


Saml.config Partner Identity Provider


The PartnerIdentityProvider section defines the Identity Provider that you are connecting to. If using metadata to configure your system, this will be imported automatically.

If setting up manually, the values will normally be identical to those above, where adfs.myserver.com is the path to your ADFS server, and the Name is set to the FederationServiceIdentifier in ADFS.

 

The certificate used (adfs_token_signing.cer above) is the public key of the Token-signing certificate exported from ADFS and copied to your TMS web server.


Claim Rules



TMS will read the Name ID claim type to determine the user ID, so this claim type must always be defined. Which attribute is mapped to it is dependent on your specific system settings, but it must be unique for every user. Typically User-Principal-Name will be a good choice.



Once the claim rule, the relying party trust, and the saml.config file have all been set up, you should be able to connect and test your SAML authentication.

Configuring using Metadata


Instead of manual configuration, TMS supports configuring SAML Authentication using metadata files. These are a pair of XML files, one provided by the Identity Provider and one by TMS, which tell the other party about the required SAML settings.
This has the advantage of saving setup time, and of automatically updating in the event of system changes (e.g. after certificate expiry). However it can also be harder to debug configuration issues, so if you are unsure about any settings it may be easier to configure manually first.

Import TMS metadata to Identity Provider


Before using the metadata file, the ServiceProvider part of the saml.config file must be defined correctly – this will be used to generate the metadata.
When this is done, use a web browser to browse to SamlMetadata.ashx in your TMS directory. You should be offered metadata.xml to download. Save the file, and open it to make sure it looks OK.

Now go to your Identity Provider, create a new relying party trust, and enter the URL for SamlMetadata.ashx into the metadata URL field. It should be able to connect and verify the data, then set up the relying party trust for you.

Now edit the relying party, and set the secure hash algorithm to SHA-1. Also ensure appropriate Claim Rules have been created.

Import Identity Provider metadata to TMS


The Identity Provider settings can also be imported to TMS using metadata. Your Identity Provider will need to provide a URL to let you access the metadata file, which you should put into the AdfsMetadataUrl key in your TMS web.config file.

The rest should happen automatically, with TMS downloading the metadata after the application restarts (e.g. after you save web.config, after restarting the application pool, or after an IIS reset). Any serious errors will be logged to the normal error logs (either the event viewer, or the Elmah_Data folder), and if SAML logging is enabled then details of the process will be logged there.

If you are informed of changes to the Identity Provider that require a new metadata file to be downloaded, this can be triggered immediately by restarting the application. Alternatively, it will happen automatically the next time the application restarts.

Customisation of SAML in TMS


There are several other options in the web.config file that can be used to customise the operation of SAML authentication in TMS. The full list of options are as follows:

 

AdfsType

 

Whether to use SAML authentication or not. Valid options are None and SAML.

 

AdfsMetadataUrl

 

The URL of the Identity Provider’s metadata file. Leave empty if you’re not importing metadata.

 

AllowAdfsFallbackToTms

 

If true, then a TMS login is available as a fall-back option – either provided as an option when a SAML login doesn’t match a TMS user, or by browsing to TMS/Login/Index?noadfs=true.

This is useful in cases where not every user has an account on the Identity Provider, or connectivity with the Identity Provider is known to be a problem. But where security is the primary concern, this should be set to false to force users to login through SAML.

 

AdfsEmpLoginField

 

The field in TMS used to match employees against the token supplied by SAML authentication. By default TMSTMS.USERNAME, however you may want to change this on systems where Windows Authentication is also enabled.

 

AdfsSupLoginField

 

The field in TMS used to match supervisors against the token supplied by SAML authentication. By default USERS.WINUSER, although again this may be changed.

 

AdfsLogoutPrompt

 

When to display a logout prompt, informing the user that they have logged out and should close their browser to continue. On systems where Single Log-out is configured and working correctly, this should not be necessary, however when Single Log-out is not available it gives an alternative means of forcing users to close their browser, ending their session with the Identity Provider.

 

 

The options are:

 

None            Never display the logout prompt. Use when Single Log-out is working correctly

 

Once            Display the logout prompt once. When the user browses to another URL it will take them to the login screen. If they were logged in using SAML this will automatically log them in again.

 

Always         Once logged out, always display the logout prompt until the browser window is closed. If they attempt to browse to another TMS URL, they will not be logged in and will be shown the logout prompt again.

 

OnceAfterSLO        Display the logout prompt once, after making the Single Log-out request. If the request has worked, then when they next navigate to a TMS URL they will be prompted to login.



Logging


To enable logging, if not enabled for the whole of the TMS application, uncomment the web.config section labelled Enable this logger to turn on debugging for ADFS authentication only. This will cause log entries to be written into tms.log every time a SAML login or logout is attempted.

 

This is helpful in diagnosing connection faults during initial setup, and also to show the tokens that have been received when trying to match TMS users to SAML login requests.




    • Related Articles

    • SAML Authentication in TMS 7

      What is SAML authentication? SAML (Security Assertion Markup Language) Single Sign-On allows users to sign in to TMS by entering their credentials directly into the log-in page of an external Identity Provider (IdP). This identity provider would ...

    • TMS 8 8.36.0.1 Release Report

      Note: TMS 8.36.0.0 has been withdrawn, and instead has been replaced by version 8.36.0.1. If you have previously downloaded 8.36.0.0 please replace it with this version. This version of TMS 8 introduces the following new features: • Web.config has ...

    • Employee in TMS but not in HR Manager

      To check the Employee Type License for that employee, select the employee in WINTMS.  Then under the Employee Menu, go to Change Employee Type.    Then select Set Licence Options.   And ensure that the HR Licence is checked.   

    • TMS 8 8.36.6.0 Release Report

      This version of TMS 8 is a bug-fix release. No new features have been added. For instructions on how to upgrade your installation of TMS 8, please take a look at our TMS 8 Upgrade guide by clicking here.  You can read about the changes made to the ...

    • TMS 8 8.36.1.0 Release Report

      This version of TMS 8 introduces the following new features: • P60 XML changes to support Statutory Parental Bereavement Pay              The XML file for P60s has been updated to include Statutory Parental Bereavement Pay. This change to XML P60s ...