diff --git a/topics/client-registration.adoc b/topics/client-registration.adoc index 304436ebd3..cd28d31058 100644 --- a/topics/client-registration.adoc +++ b/topics/client-registration.adoc @@ -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}}. diff --git a/topics/oidc/oidc-generic.adoc b/topics/oidc/oidc-generic.adoc index d625f9a539..4c71cdade3 100644 --- a/topics/oidc/oidc-generic.adoc +++ b/topics/oidc/oidc-generic.adoc @@ -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 <> 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 \ No newline at end of file + 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. \ No newline at end of file