193 lines
9.6 KiB
Text
193 lines
9.6 KiB
Text
== Other OpenID Connect libraries
|
|
|
|
{{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
|
|
|
|
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 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
|
|
|
|
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_flow]]
|
|
==== 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.)
|
|
|
|
For a client to be permitted to use the Resource Owner Password Credentials grant the client has to have `Direct Access Grants Enabled` enabled.
|
|
|
|
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.
|
|
|
|
===== Example using CURL
|
|
|
|
The following example shows how to obtain an access token for a user in the realm `master` with username `user` and password `password`. The example is using
|
|
the confidential client `myclient`:
|
|
|
|
[source,bash]
|
|
----
|
|
curl \
|
|
-d "client_id=myclient" \
|
|
-d "client_secret=40cc097b-2a57-4c17-b36a-8fdf3fc2d578" \
|
|
-d "username=user" \
|
|
-d "password=password" \
|
|
-d "grant_type=password" \
|
|
"http://localhost:8080/auth/realms/master/protocol/openid-connect/token"
|
|
----
|
|
|
|
==== 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
|
|
|
|
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]]
|
|
`http://localhost`::
|
|
|
|
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]]
|
|
`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.
|