[[_supported_protocols]]

=== Supported Protocols

==== OpenID Connect

link:http://openid.net/connect/[Open ID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0].
While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization
protocol.  OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards.  These standards define an
identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way.

There is really two types of use cases when using OIDC.  The first is an application that asks the {{book.project.name}} server to authenticate
a user for them.  After a successful login, the application will receive an _identity token_ and an _access token_.  The _identity token_
contains information about the user such as username, email, and other profile information.  The _access token_ 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 {{book.project.name}}
to obtain an _access token_ it can use to invoke on other remote services on behalf of the user.  {{book.project.name}} authenticates the user
then asks the user for consent to grant access to the client requesting it.  The client then receives the _access token_.  This _access token_
is digitally signed by the realm.  The client can make REST invocations on remote services using this _access token_.  The REST service
extracts the _access token_, verifies the signature of the token, then decides based on access information within the token whether or not to process
the request.

==== SAML 2.0

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 are used to verify requests and responses.

In {{book.project.name}} SAML serves two types of use cases: browser applications and REST invocations.

There is really two types of use cases when using SAML.  The first is an application that asks the {{book.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 specifies 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 {{book.project.name}}
to obtain a SAML assertion it can use to invoke on other remote services on behalf of the user.

==== OpenID Connect vs. SAML

Choosing between OpenID Connect and SAML is not just a matter of using a newer protocol (OIDC) instead of the older more mature protocol (SAML).

In most cases {{book.project.name}} recommends using OIDC.

SAML tends to be a bit more verbose than OIDC.

Beyond verbosity of exchanged data, if you compare the specifications you'll find that OIDC was designed to work with the web while SAML was retrofitted to work on top of the web.  For example, OIDC is also more suited for HTML5/JavaScript applications because it is
easier to implement on the client side than SAML. As tokens are in the JSON format,
they are easier to consume by JavaScript. You will also find several nice features that
make implementing security in your web applications easier. For example, check out the link:http://openid.net/specs/openid-connect-session-1_0.html#ChangeNotification[iframe trick] that the specification uses to easily determine if a user is still logged in or not.

SAML has its uses though. As you see the OIDC specifications evolve you see they implement more and more features that SAML has had for years. What we often see is that people pick SAML over OIDC because of the perception that it is more mature and also because they already have existing applications that are secured with it.