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
SAML authentication is supported in TMS 8 version 8.11.5 onwards.
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 18.104.22.168, you will need to use the workaround below. If you are on 22.214.171.124 or later, skip to the "sameSiteCookies" section. If you have already used the workaround and upgraded to 126.96.36.199 or later, you will also need to complete the "sameSiteCookies" section.
Editing web.config workaround (version 188.8.131.52 and below)
Note: This workaround is only relevant to TMS 8 version 184.108.40.206 and below. Version 220.127.116.11 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:
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:
SameSiteCookies changes in Web.Config
As of version 18.104.22.168, 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:
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
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" />
<forms name="__Auth" loginUrl="tms/login" timeout="20" defaultUrl="dashboard/home/" cookieSameSite="Lax" />
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:
- TMS 8 needs to access external cookies, and therefore the cookieSameSite
flag needs to be set to "None"
- within the
<sessionState> section, and RequireSSL needs to be set to "True".
- TMS 8 needs to be hosted on an https site.
When you upgrade to version 22.214.171.124, 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.
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:
SingleLogoutServiceBinding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
SingleLogoutServiceUrl = "https://adfs.myserver.com/adfs/ls/"/>
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
When configuring the Relying Party Trust on your Identity
Provider, the details must match as follows:
Must be added as a Relying party identifier
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.
The corresponding public key (*.cer file) should be set as
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.
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.
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.
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.
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:
Whether to use SAML authentication or not. Valid options are None and SAML.
The URL of the Identity Provider’s metadata file. Leave
empty if you’re not importing metadata.
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
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
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.
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
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
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.
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.