[[_saml]]

=== SAML

link:http://saml.xml.org/saml-specifications[SAML 2.0] is a similar specification to OIDC but a lot older and more mature.  It has its roots in SOAP and the plethora
of WS-* specifications so it tends to be a bit more verbose than OIDC.  SAML 2.0 is primarily an authentication protocol
that works by exchanging XML documents between the authentication server and the application.  XML signatures and encryption
is used to verify requests and responses.

There are really two types of use cases when using SAML.  The first is an application that asks the {project_name} server to authenticate
a user for them.  After a successful login, the application will receive an XML document that contains
something called a SAML assertion that specify various attributes about the user.  This XML document is digitally signed by
the realm and contains access information (like user role mappings) that the application can use to determine what resources the user
is allowed to access on the application.

The second type of use cases is that of a client that wants to gain access to remote services.  In this case, the client asks {project_name}
to obtain an SAML assertion it can use to invoke on other remote services on behalf of the user.

==== SAML Bindings

SAML defines a few different ways to exchange XML documents when executing the authentication protocol.  The _Redirect_ and _Post_ bindings
cover browser based applications.  The _ECP_ binding covers REST invocations.  There are other binding types but {project_name} only
supports those three.

===== Redirect Binding

The _Redirect_ Binding uses a series of browser redirect URIs to exchange information.  This is a rough overview of
how it works.

. The user visits the application and the application finds the user is not authenticated.  It generates an XML authentication
  request document and encodes it as a query param in a URI that is used to redirect to the {project_name} server.
  Depending on your settings, the application may also digitally sign this XML document and also stuff this signature as a query
  param in the redirect URI to {project_name}.  This signature is used to validate the client that sent this
  request.
. The browser is redirected to {project_name}.  The server extracts the XML auth request document and verifies
  the digital signature if required.  The user then has to enter in their credentials to be authenticated.
. After authentication, the server generates an XML authentication response document.  This document contains
  a SAML assertion that holds metadata about the user like name, address, email, and any role mappings the user
  might have.  This document is almost always digitally signed using XML signatures, and may also be encrypted.
. The XML auth response document is then encoded as a query param in a redirect URI that brings the browser back
  to the application.  The digital signature is also included as a query param.
. The application receives the redirect URI and extracts the XML document and verifies the realm's signature to make
  sure it is receiving a valid auth response.  The information inside the SAML assertion is then used to make
  access decisions or display user data.

===== POST Binding

The SAML _POST_ binding works almost the exact same way as the _Redirect_ binding, but instead of GET requests, XML
documents are exchanged by POST requests.  The _POST_ Binding uses JavaScript to trick the browser into making a POST request to
the {project_name} server or application when exchanging documents.  Basically HTTP responses contain an HTML document
that contains an HTML form with embedded JavaScript.  When the page is loaded, the JavaScript automatically invokes the form.
You really don't need to know about this stuff, but it is a pretty clever trick.

_POST_ binding is usually recommended because of security and size restrictions. When using _REDIRECT_ the SAML response
is part of the URL (it is a query parameter as it was explained before), so it can be captured in logs and it is considered
less secure. Regarding size, if the assertion contains a lot or large attributes sending the document inside the HTTP payload
is always better than in the more limited URL.

===== ECP

ECP stands for "Enhanced Client or Proxy", a SAML v.2.0 profile which allows for the exchange of SAML attributes outside the context of a web browser.
This is used most often for REST or SOAP-based clients.

===== Artifact Binding

The SAML _Artifact_ binding works alongside the standard _Redirect_ or _POST_ bindings. The purpose of this binding is
to prevent SAML messages from passing by the browser. When a SAML message would be sent to the application or the {project_name}, it is instead saved and in its place a Redirect or a POST is sent containing an unique identifier (this is the artifact).
The contacted party uses SOAP to send a message containing the artifact directly to the originator, which in turn replies via SOAP with the saved SAML message. 

This binding can have some security benefits, for example when the user is not trusted with the contents of a SAML assertion. Instead, they are exchanged between the application and {project_name} via SOAP.

====  {project_name} Server SAML URI Endpoints

{project_name} really only has one endpoint for all SAML requests.

`http(s)://authserver.host/auth/realms/{realm-name}/protocol/saml`

All bindings use this endpoint.