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 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 it works

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 it be uAs 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.sed in TMS Version SAML authentication is supported in TMS 7, version 7.42.4 onwards, and in Rostering version 2.15.1 onwards.

Products

SAML authentication can be used to log in to the Mitrefinch TMS Silverlight web application. As the authentication requires a HTTP redirect to the Identity Provider, and another back to the Mitrefinch application, it is only applicable to web applications hosted on public-facing servers.

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.

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.

Editing web.config

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>

Editing saml.config

With SAML authentication enabled, the TMS web server will attempt to load connection details from a file named 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://tms.myserver.com/Saml.as x"

                   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>

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 Saml.aspx 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 Login.aspx?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.

Was this article useful?

COVID 19 - How to manage staff working from home

Contact