oidc/saml
This commit is contained in:
Bill Burke
parent
b7e7405f99
commit
412fee7335
3 changed files with 92 additions and 5 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in a new issue