oidc/saml

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.

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.

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.
+
+
+
+