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
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:
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
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.
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.
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
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.
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.
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.
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.
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:
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:
SingleLogoutServiceBinding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
SingleLogoutServiceUrl = "https://adfs.myserver.com/adfs/ls/"/>
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:
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.
Note also that the secure hash algorithm of the relying
party trust must be set to SHA-1.
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
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.
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 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.
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.
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 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.
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.