Keycloak

1
[id="con-saml-bindings_{context}"]
2

3
==== SAML bindings
4
[role="_abstract"]
5
{project_name} supports three binding types.
6

7
===== Redirect binding
8

9
_Redirect_ binding uses a series of browser redirect URIs to exchange information.
10

11
. A user connects to an application using a browser. The application detects the user is not authenticated. 
12
. The application generates an XML authentication request document and encodes it as a query parameter in a URI. The URI is used to redirect to the {project_name} server. Depending on your settings, the application can also digitally sign the XML document and include the signature as a query parameter in the redirect URI to {project_name}.  This signature is used to validate the client that sends the request.
13
. The browser redirects to {project_name}.  
14
. The server extracts the XML auth request document and verifies the digital signature, if required.
15
. The user enters their authentication credentials.
16
. After authentication, the server generates an XML authentication response document. The document contains a SAML assertion that holds metadata about the user, including name, address, email, and any role mappings the user has.  The document is usually digitally signed using XML signatures, and may also be encrypted.
17
. The XML authentication response document is encoded as a query parameter in a redirect URI. The URI brings the browser back to the application.  The digital signature is also included as a query parameter.
18
. The application receives the redirect URI and extracts the XML document.
19
. The application verifies the realm's signature to ensure it is receiving a valid authentication response.  The information inside the SAML assertion is used to make access decisions or display user data.
20

21
===== POST binding
22

23
_POST_ binding is similar to _Redirect_ binding but _POST_ binding exchanges XML documents using POST requests instead of using GET requests. _POST_ Binding uses JavaScript to make the browser send a POST request to the {project_name} server or application when exchanging documents. HTTP responds with an HTML document which contains an HTML form containing embedded JavaScript.  When the page loads, the JavaScript automatically invokes the form.
24

25
_POST_ binding is recommended due to two restrictions:
26

27
* *Security* -- With _Redirect_ binding, the SAML response is part of the URL. It is less secure as it is possible to capture the response in logs.
28

29
* *Size* -- Sending the document in the HTTP payload provides more scope for large amounts of data than in a limited URL.
30

31
===== ECP
32

33
Enhanced Client or Proxy (ECP) is a SAML v.2.0 profile which allows the exchange of SAML attributes outside the context of a web browser. It is often used by REST or SOAP-based clients.
34

35
====  {project_name} Server SAML URI Endpoints
36

37
{project_name} has one endpoint for all SAML requests.
38

39
`http(s)://authserver.host{kc_realms_path}/{realm-name}/protocol/saml`
40

41
All bindings use this endpoint.
42