SAML
====

Introduction
------------

TRiA supports using SAML as a valid authentication server.
This document details configuring TRiA for use with SAML as an authentication server for users to authenticate against when logging in.

Dependecies
-----------
While it is possible to configure a SAML authentication server, to use it you must first install several additional dependencies.

This does not apply for Docker image deployments as the container contains all requisite SAML dependencies.

The SAML extension uses the `OneLogin python-saml <https://github.com/onelogin/python-saml#installation>`_ library and requires
several OS dependencies which must be installed on each instance running an interface server. Once installed, install the
``python-saml`` library in your virtual environment. ``pip install python-saml``.

SAML Configuration Setup
------------------------

Before starting, ensure that ``base url`` is set for your installation in the System Administration section under General Settings.
This host information is used when building the SAML redirection urls and the urls provided to the Identity Provider.

To create an SAML Authentication Server:

1. Click ``Identity Management`` from the navigation sidebar, and then click ``Authentication Servers``, near the top of the window.

2. Click ``Add Server``

3. Enter whatever you like for the nickname, and then select 'SAML' for the ``Server Type``.

4. Provide the ``Assertion Consumer Service URL`` and ``Metadata Identifier URL`` to the Identity Provider. These urls used for response validation and identifying the Service Provider (you) respectively.

5. For ``Idp Entity ID / Metadata URL``, this is the Identity Provider's identifier url. It is a unique ID, provided via xml payload, that allows the SP and IdP can identify each other.

6. For ``Single Sign-on (SSO) URL``, this A session and user authentication service that permits a user to use one set of login credentials (e.g., name and password) to access multiple application. Service Provider redirects to this url.

7. For ``Idp x509 Certificate``, Certificate provided by Idp to verify signature of SAML payload. No need to format in a certain way. Simply paste the text into the form input and newlines with be converted to ``\n``.

8. The remaining checkboxes are for fine tuning the authentication payload requirements required for provided by the Identity Provider. For example, authentication will fail if ``wantAttributeStatement`` is set to true and the Identity Provider does not supply an attributes section in the SAML payload.

Authentication works by correlating the ``NameID`` attribute of a SAML user to the ``username`` of a local user. Ensure that when creating a new user with the intent on authenticating with SAML the username is ``NameID`` in the SAML directory. Automatic user provisioning is not supported.