Added generic OIDC chapter
This commit is contained in:
Stian Thorgersen
parent
faaf1460b1
commit
d16bf61846
2 changed files with 152 additions and 24 deletions
|
|
@ -1,3 +1,4 @@
|
|||
[[_client_registration]]
|
||||
== Client Registration
|
||||
|
||||
In order for an application or service to utilize {{book.project.name}} it has to register a client in {{book.project.name}}.
|
||||
|
|
|
|||
|
|
@ -1,47 +1,174 @@
|
|||
== Other OpenID Connect libraries
|
||||
|
||||
OAuth2 https://tools.ietf.org/html/rfc6749
|
||||
OpenID Connect http://openid.net/connect/
|
||||
|
||||
{{book.project.name}} can be secured by supplied adapters that usually are easier to use and provide better integration with {{book.project.name}}. However,
|
||||
if there is no adapter available for your programming language, framework or platform you may opt to use a generic OpenID Connect Resource Provider (RP) library
|
||||
instead. This chapter describes details specific to {{book.project.name}} and doesn't go into low-level details of the protocols. For more details refer to the
|
||||
http://openid.net/connect/[OpenID Connect specifications] and https://tools.ietf.org/html/rfc6749[OAuth2 specification].
|
||||
|
||||
=== Endpoints
|
||||
|
||||
TODO
|
||||
The most important endpoint to know is the `well-known` configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID
|
||||
Connect implementation in {{book.project.name}}. The endpoint is:
|
||||
|
||||
....
|
||||
/realms/REALM-NAME/.well-known/openid-configuration
|
||||
....
|
||||
|
||||
To get the full URL add the base URL for {{book.project.name}} and replace `REALM-NAME` with the name of your realm. For example:
|
||||
|
||||
http://localhost:8080/auth/realms/master/.well-known/openid-configuration
|
||||
|
||||
Some RP libraries will retrieve all required endpoints from this endpoint, but for others you may need to list the endpoints individually.
|
||||
|
||||
==== Authorization Endpoint
|
||||
....
|
||||
/realms/master/protocol/openid-connect/auth
|
||||
....
|
||||
|
||||
Performs authentication of the end-user. This is done by redirecting user agent to this endpoint.
|
||||
|
||||
For more details see http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] section in OpenID Connect specification.
|
||||
|
||||
==== Token Endpoint
|
||||
....
|
||||
/realms/master/protocol/openid-connect/token
|
||||
....
|
||||
|
||||
Used to obtain tokens. Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used.
|
||||
The token endpoint is also used to obtain new access tokens when they expire.
|
||||
|
||||
For more details see http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] section in OpenID Connect specification.
|
||||
|
||||
==== Userinfo Endpoint
|
||||
....
|
||||
/realms/master/protocol/openid-connect/userinfo
|
||||
....
|
||||
|
||||
Returns standard claims about the authenticated user. Protected by a bearer token.
|
||||
|
||||
For more details see http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[Userinfo Endpoint] section in OpenID Connect specification.
|
||||
|
||||
==== Logout Endpoint
|
||||
....
|
||||
/realms/master/protocol/openid-connect/logout
|
||||
....
|
||||
|
||||
Logs out the authenticated user.
|
||||
|
||||
User agent can be redirected to the endpoint in which case the active user session will be logged out. Afterwards the user agent is redirected back to the application.
|
||||
|
||||
The endpoint can also be invoked directly by the application. To invoke this endpoint directly the refresh token needs to be included as well as credentials
|
||||
required to authenticate the client.
|
||||
|
||||
==== Certificate Endpoint
|
||||
....
|
||||
/realms/master/protocol/openid-connect/certs
|
||||
....
|
||||
|
||||
Public key used by realm encoded as a JSON Web Key (JWK). This key can be used to verify tokens issued by {{book.project.name}} without making invocations to
|
||||
the server.
|
||||
|
||||
For more details see https://tools.ietf.org/html/rfc7517[JSON Web Key specification].
|
||||
|
||||
==== Introspection Endpoint
|
||||
....
|
||||
/realms/master/protocol/openid-connect/token/introspect
|
||||
....
|
||||
|
||||
Used to retrieve the active state of a token. Protected by a bearer token and can only be invoked by confidential clients.
|
||||
|
||||
For more details see https://tools.ietf.org/html/rfc7662[OAuth 2.0 Token Introspection specification].
|
||||
|
||||
==== Dynamic Client Registration Endpoint
|
||||
....
|
||||
/realms/master/clients-registrations/openid-connect
|
||||
....
|
||||
|
||||
Used to dynamically register clients.
|
||||
|
||||
For more details see <<fake/../../client-registration.adoc#_client_registration,Client Registration chapter>> and the
|
||||
https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration specification].
|
||||
|
||||
|
||||
=== Flows
|
||||
|
||||
==== Authorization Grant
|
||||
==== Authorization Code
|
||||
|
||||
The Authorization Code flow redirects the user agent to {{book.project.name}}. Once the user has successfully authenticated with {{book.project.name}} an
|
||||
Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code to along with its
|
||||
credentials to obtain an Access Roken, Refresh Token and ID Token from {{book.project.name}}.
|
||||
|
||||
The flow is targeted towards web applications, but is also recommended for native applications, including mobile applications, where it is possible to embed
|
||||
a user agent.
|
||||
|
||||
For more details refer to the http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow] in the OpenID Connect specification.
|
||||
|
||||
==== Implicit
|
||||
|
||||
[[_resource_owner_password_credentials_flow]]
|
||||
The Implicit flow redirects works similarly to the Authorization Code flow, but instead of returning a Authorization Code the Access Token and ID Token is
|
||||
returned. This reduces the need for the extra invocation to exchange the Authorization Code for an Access Token. However, it does not include a Refresh
|
||||
Token. This results in the need to either permit Access Tokens with a long expiration, which is problematic as it's very hard to invalidate these. Or
|
||||
requires a new redirect to obtain new Access Token once the initial Access Token has expired. The Implicit flow is useful if the application only wants to
|
||||
authenticate the user and deals with logout itself.
|
||||
|
||||
There's also a Hybrid flow where both the Access Token and an Authorization Code is returned.
|
||||
|
||||
One thing to note is that both the Implicit flow and Hybrid flow has potential security risks as the Access Token may be leaked through web server logs and
|
||||
browser history. This is somewhat mitigated by using short expiration for Access Tokens.
|
||||
|
||||
For more details refer to the http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth[Implicit Flow] in the OpenID Connect specification.
|
||||
|
||||
==== Resource Owner Password Credentials
|
||||
|
||||
Resource Owner Password Credentials, referred to as Direct Grant in {{book.project.name}}, allows exchanging user credentials for tokens. It's not recommended
|
||||
to use this flow unless you absolutely need to. Examples where this could be useful are legacy applications and command-line interfaces.
|
||||
|
||||
There are a number of limitations of using this flow, including:
|
||||
|
||||
* User credentials are exposed to the application
|
||||
* Applications need login pages
|
||||
* Application needs to be aware of the authentication scheme
|
||||
* Changes to authentication flow requires changes to application
|
||||
* No support for identity brokering or social login
|
||||
* Flows are not supported (user self-registration, required actions, etc.)
|
||||
|
||||
This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 specification.
|
||||
|
||||
For more details refer to the https://tools.ietf.org/html/rfc6749#section-4.3[Resource Owner Password Credentials Grant] chapter in the OAuth 2.0 specification.
|
||||
|
||||
==== Client Credentials
|
||||
|
||||
Client Credentials is used when clients (applications and services) wants to obtain access on behalf of themselves rather than on behalf of a user. This can
|
||||
for example be useful for background services that applies changes to the system in general rather than for a specific user.
|
||||
|
||||
{{book.project.name}} provides support for clients to authenticate either with a secret or with public/private keys.
|
||||
|
||||
This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 specification.
|
||||
|
||||
For more details refer to the https://tools.ietf.org/html/rfc6749#section-4.4[Client Credentials Grant] chapter in the OAuth 2.0 specification.
|
||||
|
||||
=== Redirect URIs
|
||||
|
||||
Keycloak provides two special redirect uris for installed applications.
|
||||
When using the redirect based flows it's important to use valid redirect uris for your clients. The redirect uris should be as specific as possible. This
|
||||
especially applies to client-side (public clients) applications. Failing to do so could result in:
|
||||
|
||||
* Open redirects - this can allow attackers to create spoof links that looks like they are coming from your domain
|
||||
* Unauthorized entry - when users are already authenticated with {{book.project.name}} an attacker can use a public client where redirect uris have not be configured correctly to gain access by redirecting the user without the users knowledge
|
||||
|
||||
In production for web applications always use `https` for all redirect URIs. Do not allow redirects to http.
|
||||
|
||||
There's also a few special redirect URIs:
|
||||
|
||||
[[_installed_applications_url]]
|
||||
==== Installed Applications url
|
||||
`http://localhost`::
|
||||
|
||||
http://localhost
|
||||
|
||||
This returns the code to a web server on the client as a query parameter.
|
||||
Any port number is allowed.
|
||||
This makes it possible to start a web server for the installed application on any free port number without requiring changes in the `Admin Console`.
|
||||
This redirect URI is useful for native applications and allows the native application to create a web server on a random port that can be used to obtain the
|
||||
authorization code. This redirect uri allows any port.
|
||||
|
||||
[[_installed_applications_urn]]
|
||||
==== Installed Applications urn
|
||||
`urn:ietf:wg:oauth:2.0:oob`::
|
||||
|
||||
`urn:ietf:wg:oauth:2.0:oob`
|
||||
|
||||
If its not possible to start a web server in the client (or a browser is not available) it is possible to use the special `urn:ietf:wg:oauth:2.0:oob` redirect uri.
|
||||
When this redirect uri is used Keycloak displays a page with the code in the title and in a box on the page.
|
||||
The application can either detect that the browser title has changed, or the user can copy/paste the code manually to the application.
|
||||
With this redirect uri it is also possible for a user to use a different device to obtain a code to paste back to the application.
|
||||
|
||||
=== Session Management
|
||||
|
||||
=== Dynamic Client Registration
|
||||
If its not possible to start a web server in the client (or a browser is not available) it is possible to use the special `urn:ietf:wg:oauth:2.0:oob` redirect uri.
|
||||
When this redirect uri is used Keycloak displays a page with the code in the title and in a box on the page.
|
||||
The application can either detect that the browser title has changed, or the user can copy/paste the code manually to the application.
|
||||
With this redirect uri it is also possible for a user to use a different device to obtain a code to paste back to the application.
|
||||
Loading…
Reference in a new issue