From 412fee7335b04c23179cd28ac75a7fdb8b616271 Mon Sep 17 00:00:00 2001 From: Bill Burke Date: Wed, 18 May 2016 20:36:13 -0400 Subject: [PATCH] oidc/saml --- topics/sso-protocols/oidc.adoc | 10 ++-- topics/sso-protocols/saml-vs-oidc.adoc | 18 +++++++ topics/sso-protocols/saml.adoc | 69 ++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 5 deletions(-) diff --git a/topics/sso-protocols/oidc.adoc b/topics/sso-protocols/oidc.adoc index 56653954ee..cb9cd40c48 100644 --- a/topics/sso-protocols/oidc.adoc +++ b/topics/sso-protocols/oidc.adoc @@ -81,20 +81,20 @@ _identity_, _access_, and _refresh_ tokens. This is also used by REST clients, but instead of obtaining a token that works on behalf of an external user, a token is created based on the metadata and permissions of a service account that is associated with the client. -==== {{book.project.name}} Server URI Endpoints +==== {{book.project.name}} Server OIDC URI Endpoints Here's a list of OIDC endpoints that the {{book.project.name}} publishes. These URLs are useful if you are using a non-{{book.project.name}} client adapter to talk OIDC with the auth server. These are all relative URLs and the root of the URL being the HTTP(S) protocol, hostname, and usually path prefixed with _/auth_: i.e. https://localhost:8080/auth -/realms/\{realm-name}/protocols/openid-connect/token:: +/realms/\{realm-name}/protocol/openid-connect/token:: This is the URL endpoint for obtaining a temporary code in the Authorization Code Flow or for obtaining tokens via the Implicit Flow, Direct Grants, or Client Grants. -/realms/\{realm-name}/protocols/openid-connect/auth:: +/realms/\{realm-name}/protocol/openid-connect/auth:: This is the URL endpoint for the Authorization Code Flow to turn a temporary code into a token. -/realms/{realm-name}/protocols/openid-connect/logout:: +/realms/{realm-name}/protocol/openid-connect/logout:: This is the URL endpoint for performing logouts. -/realms/\{realm-name}/protocols/openid-connect/userinfo:: +/realms/\{realm-name}/protocol/openid-connect/userinfo:: This is the URL endpoint for the User Info service described in the OIDC specification. In all of these replace _\{realm-name}_ with the name of the realm. diff --git a/topics/sso-protocols/saml-vs-oidc.adoc b/topics/sso-protocols/saml-vs-oidc.adoc index e69de29bb2..34ee8c648c 100644 --- a/topics/sso-protocols/saml-vs-oidc.adoc +++ b/topics/sso-protocols/saml-vs-oidc.adoc @@ -0,0 +1,18 @@ + +=== OIDC vs. SAML + +Choosing between OIDC and SAML is not just a matter of using a newer, sexier protocol (OIDC) instead of the old, mature, dinosaur (SAML). +{{book.project.name}} has chosen OIDC as the protocol we use to both recommend and write all our extensions on top of. +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 much better suited for HTML5/Javascript applications because it is +much much simpler to implement on the client side than SAML. Since tokens are in the JSON format, +they can be directly consumed by Javascript. Also, you'll find many nice little switches and features that +make implementing security in your web applications easier. For example, check out the 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 by it. \ No newline at end of file diff --git a/topics/sso-protocols/saml.adoc b/topics/sso-protocols/saml.adoc index e69de29bb2..5920ec7442 100644 --- a/topics/sso-protocols/saml.adoc +++ b/topics/sso-protocols/saml.adoc @@ -0,0 +1,69 @@ + +=== SAML + +link://https://saml.org/fill/this/in[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. + +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 specify various attributes about the user. THis XML document is digitially 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 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 {{book.project.name}} only +supports those 3. + +===== 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 {{book.project.name}} server. + Depending on your settings, the application may also digitially sign this XML document and also stuffs this signature as a query + param in the redirect URI to {{book.project.name}}. This is signature is used to validate the client that sent this + request. +. The browser is redirected to {{book.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 also an role mappings the user + might have. This document is almost always digitially signed and 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 {{book.project.name}} server or application when exchanging documents. Bascially 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. + +===== ECP + +TODO. Ask Pedro to fill in. + +==== {{book.project.name}} Server OIDC URI Endpoints + +{{book.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. + + + +