libre.sh/keycloak-scim
4
0
Fork 0
Code Issues 15 Pull requests Releases 1 Activity Actions

KEYCLOAK-18301 Fix broken links

Browse source
This commit is contained in:
Hynek Mlnarik 2021-05-27 14:29:27 +02:00 committed by Stian Thorgersen
parent fde7cdeb70
commit b572fcff07
23 changed files with 46 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
authorization_services/topics/service-rpt-overview.adoc
View file

@ -1,7 +1,7 @@
[[_service_rpt_overview]] [[_service_rpt_overview]]
= Requesting Party Token = Requesting Party Token
A requesting party token (RPT) is a https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] digitally signed using https://tools.ietf.org/html/rfc7515[JSON web signature (JWS)]. The token is built based on the OAuth2 access token previously issued by {project_name} to a specific client acting on behalf of a user A requesting party token (RPT) is a https://datatracker.ietf.org/doc/html/rfc7519[JSON web token (JWT)] digitally signed using https://datatracker.ietf.org/doc/html/rfc7515[JSON web signature (JWS)]. The token is built based on the OAuth2 access token previously issued by {project_name} to a specific client acting on behalf of a user
or on its own behalf. or on its own behalf.
When you decode an RPT, you see a payload similar to the following: When you decode an RPT, you see a payload similar to the following:

4
authorization_services/topics/service-rpt-token-introspection.adoc
View file

@ -10,7 +10,7 @@ There are two main use cases where token introspection can help you:
= Obtaining Information about an RPT = Obtaining Information about an RPT
The token introspection is essentially a https://tools.ietf.org/html/rfc7662[OAuth2 token introspection]-compliant endpoint from which you can obtain information about an RPT. The token introspection is essentially a https://datatracker.ietf.org/doc/html/rfc7662[OAuth2 token introspection]-compliant endpoint from which you can obtain information about an RPT.
``` ```
http://${host}:${port}/auth/realms/${realm_name}/protocol/openid-connect/token/introspect http://${host}:${port}/auth/realms/${realm_name}/protocol/openid-connect/token/introspect
@ -68,7 +68,7 @@ If the RPT is not active, this response is returned instead:
= Do I Need to Invoke the Server Every Time I Want to Introspect an RPT? = Do I Need to Invoke the Server Every Time I Want to Introspect an RPT?
No. Just like a regular access token issued by a {project_name} server, RPTs also use the No. Just like a regular access token issued by a {project_name} server, RPTs also use the
https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] specification as the default format. https://datatracker.ietf.org/doc/html/rfc7519[JSON web token (JWT)] specification as the default format.
If you want to validate these tokens without a call to the remote introspection endpoint, you can decode the RPT and query for its validity locally. Once you decode the token, If you want to validate these tokens without a call to the remote introspection endpoint, you can decode the RPT and query for its validity locally. Once you decode the token,
you can also use the permissions within the token to enforce authorization decisions. you can also use the permissions within the token to enforce authorization decisions.

2
release_notes/topics/4_0_0_final.adoc
View file

@ -11,7 +11,7 @@ See the documentation and migration guide for more details.
= OAuth 2 Certificate Bound Access Tokens = OAuth 2 Certificate Bound Access Tokens
We now have a partial implementation of the specification We now have a partial implementation of the specification
https://tools.ietf.org/html/draft-ietf-oauth-mtls-08[OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens] . https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-08[OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens] .
More accurately we have support for the Certificate Bound Access Tokens. If your confidential client is able to use 2-way SSL, More accurately we have support for the Certificate Bound Access Tokens. If your confidential client is able to use 2-way SSL,
{project_name} will be able to add the hash of the client certificate into the tokens issued for the client. At this moment, {project_name} will be able to add the hash of the client certificate into the tokens issued for the client. At this moment,
it's just the {project_name} itself, which verifies the token hashes (for example during `refresh token` requests). it's just the {project_name} itself, which verifies the token hashes (for example during `refresh token` requests).

2
release_notes/topics/product/7_4_final.adoc
View file

@ -102,7 +102,7 @@ When you go to Manage Account, you will see the new Account Console. Here is a
image:{project_images}/device-activity.png[] image:{project_images}/device-activity.png[]
This new console is based on link:https://reactjs.org/[React] and link:https://www.patternfly.org/v4/[PatternFly 4]. It allows you to use link:https://www.patternfly.org/v4/get-started/global-css-variables/#global-css-variables[PatternFly CSS variables] for easy styling. It also allows you to remove pages and add your own pages. Full documentation will be provided at a future release. This new console is based on link:https://reactjs.org/[React] and link:https://www.patternfly.org/v4/[PatternFly 4]. It allows you to use link:https://www.patternfly.org/v4/developer-resources/global-css-variables/#global-variables[PatternFly CSS variables] for easy styling. It also allows you to remove pages and add your own pages. Full documentation will be provided at a future release.
== New default hostname provider == New default hostname provider

2
securing_apps/topics/client-registration.adoc
View file

@ -108,7 +108,7 @@ This means that for the JavaScript adapter you can load the client configuration
=== OpenID Connect Dynamic Client Registration === OpenID Connect Dynamic Client Registration
{project_name} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://tools.ietf.org/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://tools.ietf.org/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol]. {project_name} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://datatracker.ietf.org/doc/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://datatracker.ietf.org/doc/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol].
The endpoint to use these specifications to register clients in {project_name} is `/auth/realms/<realm>/clients-registrations/openid-connect[/<client id>]`. The endpoint to use these specifications to register clients in {project_name} is `/auth/realms/<realm>/clients-registrations/openid-connect[/<client id>]`.

4
securing_apps/topics/oidc/java/client-authentication.adoc
View file

@ -18,7 +18,7 @@ You can generate the secret for a particular client in the {project_name} admini
===== Client Authentication with Signed JWT ===== Client Authentication with Signed JWT
This is based on the https://tools.ietf.org/html/rfc7523[RFC7523] specification. It works this way: This is based on the https://datatracker.ietf.org/doc/html/rfc7523[RFC7523] specification. It works this way:
* The client must have the private key and certificate. For {project_name} this is available through the traditional `keystore` file, which is either available on the client application's classpath or somewhere on the file system. * The client must have the private key and certificate. For {project_name} this is available through the traditional `keystore` file, which is either available on the client application's classpath or somewhere on the file system.
@ -72,7 +72,7 @@ The client has a secret, which needs to be known to both the adapter (applicatio
} }
---- ----
The "algorithm" field specifies the algorithm for Signed JWT using Client Secret. It needs to be one of the following values : HS256, HS384, and HS512. For details, please refer to https://tools.ietf.org/html/rfc7518#section-3.2[JSON Web Algorithms (JWA)]. The "algorithm" field specifies the algorithm for Signed JWT using Client Secret. It needs to be one of the following values : HS256, HS384, and HS512. For details, please refer to https://datatracker.ietf.org/doc/html/rfc7518#section-3.2[JSON Web Algorithms (JWA)].
This "algorithm" field is optional so that HS256 is applied automatically if the "algorithm" field does not exist on the `keycloak.json` file. This "algorithm" field is optional so that HS256 is applied automatically if the "algorithm" field does not exist on the `keycloak.json` file.

2
securing_apps/topics/oidc/javascript-adapter.adoc
View file

@ -437,7 +437,7 @@ Options is an Object, where:
* responseMode - Set the OpenID Connect response mode send to {project_name} server at login request. Valid values are `query` or `fragment`. Default value is `fragment`, which means that after successful authentication will {project_name} redirect to JavaScript application with OpenID Connect parameters added in URL fragment. This is generally safer and recommended over `query`. * responseMode - Set the OpenID Connect response mode send to {project_name} server at login request. Valid values are `query` or `fragment`. Default value is `fragment`, which means that after successful authentication will {project_name} redirect to JavaScript application with OpenID Connect parameters added in URL fragment. This is generally safer and recommended over `query`.
* flow - Set the OpenID Connect flow. Valid values are `standard`, `implicit` or `hybrid`. * flow - Set the OpenID Connect flow. Valid values are `standard`, `implicit` or `hybrid`.
* enableLogging - Enables logging messages from Keycloak to the console (default is `false`). * enableLogging - Enables logging messages from Keycloak to the console (default is `false`).
* pkceMethod - The method for Proof Key Code Exchange (https://tools.ietf.org/html/rfc7636[PKCE]) to use. Configuring this value enables the PKCE mechanism. Available options: * pkceMethod - The method for Proof Key Code Exchange (https://datatracker.ietf.org/doc/html/rfc7636[PKCE]) to use. Configuring this value enables the PKCE mechanism. Available options:
- "S256" - The SHA256 based PKCE method - "S256" - The SHA256 based PKCE method
Returns a promise that resolves when initialization completes. Returns a promise that resolves when initialization completes.

18
securing_apps/topics/oidc/oidc-generic.adoc
View file

@ -1,6 +1,6 @@
=== Other OpenID Connect Libraries === Other OpenID Connect Libraries
{project_name} can be secured by supplied adapters that are usually easier to use and provide better integration with {project_name}. However, if an adapter is not available for your programming language, framework, or platform you might opt to use a generic OpenID Connect Relying Party (RP) library instead. This chapter describes details specific to {project_name} and does not contain specific protocol details. For more information see the https://openid.net/connect/[OpenID Connect specifications] and https://tools.ietf.org/html/rfc6749[OAuth2 specification]. {project_name} can be secured by supplied adapters that are usually easier to use and provide better integration with {project_name}. However, if an adapter is not available for your programming language, framework, or platform you might opt to use a generic OpenID Connect Relying Party (RP) library instead. This chapter describes details specific to {project_name} and does not contain specific protocol details. For more information see the https://openid.net/connect/[OpenID Connect specifications] and https://datatracker.ietf.org/doc/html/rfc6749[OAuth2 specification].
==== Endpoints ==== Endpoints
@ -61,7 +61,7 @@ The endpoint can also be invoked directly by the application. To invoke this end
/realms/{realm-name}/protocol/openid-connect/certs /realms/{realm-name}/protocol/openid-connect/certs
.... ....
The certificate endpoint returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK). Depending on the realm settings there can be one or more keys enabled for verifying tokens. For more information see the link:{adminguide_link}[{adminguide_name}] and the https://tools.ietf.org/html/rfc7517[JSON Web Key specification]. The certificate endpoint returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK). Depending on the realm settings there can be one or more keys enabled for verifying tokens. For more information see the link:{adminguide_link}[{adminguide_name}] and the https://datatracker.ietf.org/doc/html/rfc7517[JSON Web Key specification].
[[_token_introspection_endpoint]] [[_token_introspection_endpoint]]
===== Introspection Endpoint ===== Introspection Endpoint
@ -72,7 +72,7 @@ The certificate endpoint returns the public keys enabled by the realm, encoded a
The introspection endpoint is used to retrieve the active state of a token. In other words, you can use it to validate an access or refresh token. The introspection endpoint is used to retrieve the active state of a token. In other words, you can use it to validate an access or refresh token.
It can only be invoked by confidential clients. It can only be invoked by confidential clients.
For more details on how to invoke on this endpoint, see https://tools.ietf.org/html/rfc7662[OAuth 2.0 Token Introspection specification]. For more details on how to invoke on this endpoint, see https://datatracker.ietf.org/doc/html/rfc7662[OAuth 2.0 Token Introspection specification].
===== Dynamic Client Registration Endpoint ===== Dynamic Client Registration Endpoint
.... ....
@ -92,7 +92,7 @@ https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dyn
The token revocation endpoint is used to revoke tokens. Both refresh tokens and access tokens are supported by this endpoint. The token revocation endpoint is used to revoke tokens. Both refresh tokens and access tokens are supported by this endpoint.
For more details on how to invoke on this endpoint, see https://tools.ietf.org/html/rfc7009[OAuth 2.0 Token Revocation specification]. For more details on how to invoke on this endpoint, see https://datatracker.ietf.org/doc/html/rfc7009[OAuth 2.0 Token Revocation specification].
===== Device Authorization Endpoint ===== Device Authorization Endpoint
.... ....
@ -101,7 +101,7 @@ For more details on how to invoke on this endpoint, see https://tools.ietf.org/h
The device authorization endpoint is used to obtain a device code and a user code. It can only be invoked by confidential clients. The device authorization endpoint is used to obtain a device code and a user code. It can only be invoked by confidential clients.
For more details on how to invoke on this endpoint, see https://tools.ietf.org/html/rfc8628[OAuth 2.0 Device Authorization Grant specification]. For more details on how to invoke on this endpoint, see https://datatracker.ietf.org/doc/html/rfc8628[OAuth 2.0 Device Authorization Grant specification].
[[_backchannel_authentication_endpoint]] [[_backchannel_authentication_endpoint]]
===== Backchannel Authentication Endpoint ===== Backchannel Authentication Endpoint
@ -119,7 +119,7 @@ Also please refer to other places of {project_name} documentation like <<_client
If you need to manually validate access tokens issued by {project_name} you can invoke the <<_token_introspection_endpoint,Introspection Endpoint>>. If you need to manually validate access tokens issued by {project_name} you can invoke the <<_token_introspection_endpoint,Introspection Endpoint>>.
The downside to this approach is that you have to make a network invocation to the {project_name} server. This can be slow and possibly overload the The downside to this approach is that you have to make a network invocation to the {project_name} server. This can be slow and possibly overload the
server if you have too many validation requests going on at the same time. {project_name} issued access tokens are https://tools.ietf.org/html/rfc7519[JSON Web Tokens (JWT)] digitally signed and encoded using https://tools.ietf.org/html/rfc7515[JSON Web Signature (JWS)]. server if you have too many validation requests going on at the same time. {project_name} issued access tokens are https://datatracker.ietf.org/doc/html/rfc7519[JSON Web Tokens (JWT)] digitally signed and encoded using https://datatracker.ietf.org/doc/html/rfc7515[JSON Web Signature (JWS)].
Because they are encoded in this way, this allows you to locally validate access tokens using the public key of the issuing realm. You can either hard code the Because they are encoded in this way, this allows you to locally validate access tokens using the public key of the issuing realm. You can either hard code the
realm's public key in your validation code, or lookup and cache the public key using the <<_certificate_endpoint, certificate endpoint>> with the Key ID (KID) embedded within the realm's public key in your validation code, or lookup and cache the public key using the <<_certificate_endpoint, certificate endpoint>> with the Key ID (KID) embedded within the
JWS. Depending what language you code in, there are a multitude of third party libraries out there that can help you with JWS validation. JWS. Depending what language you code in, there are a multitude of third party libraries out there that can help you with JWS validation.
@ -172,7 +172,7 @@ For a client to be permitted to use the Resource Owner Password Credentials gran
This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 specification. 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. For more details refer to the https://datatracker.ietf.org/doc/html/rfc6749#section-4.3[Resource Owner Password Credentials Grant] chapter in the OAuth 2.0 specification.
====== Example using CURL ====== Example using CURL
@ -199,7 +199,7 @@ for example be useful for background services that applies changes to the system
This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 specification. 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. For more details refer to the https://datatracker.ietf.org/doc/html/rfc6749#section-4.4[Client Credentials Grant] chapter in the OAuth 2.0 specification.
===== Device Authorization Grant ===== Device Authorization Grant
@ -210,7 +210,7 @@ Then the application provides the user with the user code and the verification U
The application repeatedly polls {project_name} until {project_name} completes the user authorization. The application repeatedly polls {project_name} until {project_name} completes the user authorization.
If user authentication is complete, the application obtains the device code. Then the application uses the device code along with its credentials to obtain an Access Token, Refresh Token and ID Token from {project_name}. If user authentication is complete, the application obtains the device code. Then the application uses the device code along with its credentials to obtain an Access Token, Refresh Token and ID Token from {project_name}.
For more details refer to the https://tools.ietf.org/html/rfc8628[OAuth 2.0 Device Authorization Grant specification]. For more details refer to the https://datatracker.ietf.org/doc/html/rfc8628[OAuth 2.0 Device Authorization Grant specification].
[[_client_initiated_backchannel_authentication_grant]] [[_client_initiated_backchannel_authentication_grant]]
===== Client Initiated Backchannel Authentication Grant ===== Client Initiated Backchannel Authentication Grant

2
securing_apps/topics/overview/supported-protocols.adoc
View file

@ -4,7 +4,7 @@
==== OpenID Connect ==== OpenID Connect
link:https://openid.net/connect/[OpenID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0]. link:https://openid.net/connect/[OpenID Connect] (OIDC) is an authentication protocol that is an extension of link:https://datatracker.ietf.org/doc/html/rfc6749[OAuth 2.0].
While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization
protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define an protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define an
identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way. identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way.

4
securing_apps/topics/token-exchange/token-exchange.adoc
View file

@ -23,7 +23,7 @@ to impersonate a user. Here's a short summary of the current capabilities of {p
* A client can exchange an external token for a {project_name} token. * A client can exchange an external token for a {project_name} token.
* A client can impersonate a user * A client can impersonate a user
Token exchange in {project_name} is a very loose implementation of the link:https://tools.ietf.org/html/rfc8693[OAuth Token Exchange] specification at the IETF. Token exchange in {project_name} is a very loose implementation of the link:https://datatracker.ietf.org/doc/html/rfc8693[OAuth Token Exchange] specification at the IETF.
We have extended it a little, ignored some of it, and loosely interpreted other parts of the specification. It is We have extended it a little, ignored some of it, and loosely interpreted other parts of the specification. It is
a simple grant type invocation on a realm's OpenID Connect token endpoint. a simple grant type invocation on a realm's OpenID Connect token endpoint.
@ -78,7 +78,7 @@ NOTE: We currently only support OpenID Connect and OAuth exchanges. Support f
A successful response from an exchange invocation will return the HTTP 200 response code with a content type that A successful response from an exchange invocation will return the HTTP 200 response code with a content type that
depends on the `requested-token-type` and `requested_issuer` the client asks for. OAuth requested token types will return depends on the `requested-token-type` and `requested_issuer` the client asks for. OAuth requested token types will return
a JSON document as described in the link:https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16[OAuth Token Exchange] specification. a JSON document as described in the link:https://datatracker.ietf.org/doc/html/draft-ietf-oauth-token-exchange-16[OAuth Token Exchange] specification.
[source,json] [source,json]
---- ----

2
server_admin/topics/authentication/webauthn.adoc
View file

@ -113,7 +113,7 @@ The configurable items and their description follow.
For more details, see https://www.w3.org/TR/webauthn/#dictionary-pkcredentialentity[WebAuthn Specification]. For more details, see https://www.w3.org/TR/webauthn/#dictionary-pkcredentialentity[WebAuthn Specification].
|Signature Algorithms |Signature Algorithms
|It tells the WebAuthn authenticator which signature algorithms to use for the https://www.w3.org/TR/webauthn/#public-key-credential[Public Key Credential] that can be used for signing and verifying the https://www.w3.org/TR/webauthn/#authentication-assertion[Authentication Assertion]. Multiple algorithms can be specified. If no algorithm is specified, https://tools.ietf.org/html/rfc8152#section-8.1[ES256] is adapted. The default setting is ES256. This is an optional configuration item that is applied to the operation of registering a WebAuthn authenticator. |It tells the WebAuthn authenticator which signature algorithms to use for the https://www.w3.org/TR/webauthn/#public-key-credential[Public Key Credential] that can be used for signing and verifying the https://www.w3.org/TR/webauthn/#authentication-assertion[Authentication Assertion]. Multiple algorithms can be specified. If no algorithm is specified, https://datatracker.ietf.org/doc/html/rfc8152#section-8.1[ES256] is adapted. The default setting is ES256. This is an optional configuration item that is applied to the operation of registering a WebAuthn authenticator.
For more details, see https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialparameters[WebAuthn Specification]. For more details, see https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialparameters[WebAuthn Specification].
|Relying Party ID |Relying Party ID

6
server_admin/topics/authentication/x509.adoc
View file

@ -181,7 +181,7 @@ This option only affects the two User Identity Sources _Match SubjectDN using re
If you setup a new {project_name} instance it is recommended to enable this option. Leave this option disabled to remain beckward compatible with existing {project_name} instances. If you setup a new {project_name} instance it is recommended to enable this option. Leave this option disabled to remain beckward compatible with existing {project_name} instances.
`Enable Serial Number hexadecimal representation` (optional):: `Enable Serial Number hexadecimal representation` (optional)::
An option to use hexadecimal representation of the Serial Number. See link:https://tools.ietf.org/html/rfc5280#section-4.1.2.2[RFC5280, Section-4.1.2.2]. Serial Number with sign bit set to 1 should be left padded with 00 octet. E.g. Serial number with decimal value _161_, or _a1_ in hexadecimal representation according to RFC5280 must be encoded as _00a1_. More details can be found: link:https://tools.ietf.org/html/rfc5280#appendix-B[RFC5280, appendix-B]. An option to use hexadecimal representation of the Serial Number. See link:https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.2[RFC5280, Section-4.1.2.2]. Serial Number with sign bit set to 1 should be left padded with 00 octet. E.g. Serial number with decimal value _161_, or _a1_ in hexadecimal representation according to RFC5280 must be encoded as _00a1_. More details can be found: link:https://datatracker.ietf.org/doc/html/rfc5280#appendix-B[RFC5280, appendix-B].
`A regular expression` (optional):: `A regular expression` (optional)::
Defines a regular expression to use as a filter to extract the certificate identity. The regular expression must contain a single group. Defines a regular expression to use as a filter to extract the certificate identity. The regular expression must contain a single group.
@ -211,10 +211,10 @@ Defines whether to check the certificate revocation status using Online Certific
Allows to override a value of the OCSP responder URI in the certificate. Allows to override a value of the OCSP responder URI in the certificate.
`Validate Key Usage` (optional):: `Validate Key Usage` (optional)::
Verifies whether the certificate's KeyUsage extension bits are set. For example, "digitalSignature,KeyEncipherment" will verify if bits 0 and 2 in the KeyUsage extension are asserted. Leave the parameter empty to disable the Key Usage validation. See link:https://tools.ietf.org/html/rfc5280#section-4.2.1.3[RFC5280, Section-4.2.1.3]. The server will raise an error only when flagged as critical by the issuing CA and there is a key usage extension mismatch. Verifies whether the certificate's KeyUsage extension bits are set. For example, "digitalSignature,KeyEncipherment" will verify if bits 0 and 2 in the KeyUsage extension are asserted. Leave the parameter empty to disable the Key Usage validation. See link:https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3[RFC5280, Section-4.2.1.3]. The server will raise an error only when flagged as critical by the issuing CA and there is a key usage extension mismatch.
`Validate Extended Key Usage` (optional):: `Validate Extended Key Usage` (optional)::
Verifies one or more purposes as defined in the Extended Key Usage extension. See link:https://tools.ietf.org/html/rfc5280#section-4.2.1.12[RFC5280, Section-4.2.1.12]. Leave the parameter empty to disable the Extended Key Usage validation. The server will raise an error only when flagged as critical by the issuing CA and there is a key usage extension mismatch. Verifies one or more purposes as defined in the Extended Key Usage extension. See link:https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12[RFC5280, Section-4.2.1.12]. Leave the parameter empty to disable the Extended Key Usage validation. The server will raise an error only when flagged as critical by the issuing CA and there is a key usage extension mismatch.
`Bypass identity confirmation`:: `Bypass identity confirmation`::
If set, X.509 client certificate authentication will not prompt the user to confirm the certificate identity and will automatically sign in the user upon successful authentication. If set, X.509 client certificate authentication will not prompt the user to confirm the certificate identity and will automatically sign in the user upon successful authentication.

14
server_admin/topics/clients/client-oidc.adoc
View file

@ -58,7 +58,7 @@ This defines the type of the OIDC client.
_confidential_:: _confidential_::
Confidential access type is for server-side clients that need to perform a browser login and require a client secret when they turn an access code into an access token, Confidential access type is for server-side clients that need to perform a browser login and require a client secret when they turn an access code into an access token,
(see https://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details). This type should be used for server-side applications. (see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details). This type should be used for server-side applications.
_public_:: _public_::
Public access type is for client-side clients that need to perform a browser login. With a client-side application there is no way to keep a secret safe. Instead it is very important to restrict access by configuring correct redirect URIs for the client. Public access type is for client-side clients that need to perform a browser login. With a client-side application there is no way to keep a secret safe. Instead it is very important to restrict access by configuring correct redirect URIs for the client.
@ -151,7 +151,7 @@ In the following cases, {project_name} will verify the client sending the access
* A UserInfo request is sent to UserInfo endpoint with a holder-of-key access token * A UserInfo request is sent to UserInfo endpoint with a holder-of-key access token
* A logout request is sent to Logout endpoint with a holder-of-key refresh token * A logout request is sent to Logout endpoint with a holder-of-key refresh token
Please see https://tools.ietf.org/html/draft-ietf-oauth-mtls-08#section-3[Mutual TLS Client Certificate Bound Access Tokens] in the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens for more details. Please see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-08#section-3[Mutual TLS Client Certificate Bound Access Tokens] in the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens for more details.
WARNING: None of the keycloak client adapters currently support holder-of-key token verification. WARNING: None of the keycloak client adapters currently support holder-of-key token verification.
Instead, keycloak adapters currently treat access and refresh tokens as bearer tokens. Instead, keycloak adapters currently treat access and refresh tokens as bearer tokens.
@ -169,12 +169,12 @@ The administrator can select the following three options:
* S256 : {project_name} applies to the client PKCE whose code challenge method is S256. * S256 : {project_name} applies to the client PKCE whose code challenge method is S256.
* plain : {project_name} applies to the client PKCE whose code challenge method is plain. * plain : {project_name} applies to the client PKCE whose code challenge method is plain.
Please see https://tools.ietf.org/html/rfc7636[RFC 7636 Proof Key for Code Exchange by OAuth Public Clients] for more details. Please see https://datatracker.ietf.org/doc/html/rfc7636[RFC 7636 Proof Key for Code Exchange by OAuth Public Clients] for more details.
[[_jwe-id-token-encryption]] [[_jwe-id-token-encryption]]
*Signed and Encrypted ID Token Support* *Signed and Encrypted ID Token Support*
{project_name} can encrypt ID token according to the https://tools.ietf.org/html/rfc7516[Json Web Encryption (JWE)] specification. The administrator can determine whether encrypting ID token or not per client. This feature is disabled as default. {project_name} can encrypt ID token according to the https://datatracker.ietf.org/doc/html/rfc7516[Json Web Encryption (JWE)] specification. The administrator can determine whether encrypting ID token or not per client. This feature is disabled as default.
The key for encrypting ID token is called Content Encryption Key (CEK). {project_name} and a client need to negotiate which CEK is used and how to deliver it. The way to do so is called Key Management Mode. The key for encrypting ID token is called Content Encryption Key (CEK). {project_name} and a client need to negotiate which CEK is used and how to deliver it. The way to do so is called Key Management Mode.
@ -182,19 +182,19 @@ JWE specification determines 5 types of Key Management Mode. {project_name} supp
In Key Encryption, the client generates a key pair of asymmetric cryptography. The public key is used to encrypt CEK. {project_name} generates CEK per ID token, encrypts the ID token by this generated CEK and encrypts this CEK by this client's public key. The client decrypts this encrypted CEK by their private key, and decrypt the ID token by decrypted CEK. Therefore, any party other than the client is not able to decrypt ID token. In Key Encryption, the client generates a key pair of asymmetric cryptography. The public key is used to encrypt CEK. {project_name} generates CEK per ID token, encrypts the ID token by this generated CEK and encrypts this CEK by this client's public key. The client decrypts this encrypted CEK by their private key, and decrypt the ID token by decrypted CEK. Therefore, any party other than the client is not able to decrypt ID token.
The client needs to pass their public key for encrypting CEK onto {project_name}. {project_name} supports downloading public keys from the URL the client provides. The client needs to provide their public keys according to https://tools.ietf.org/html/rfc7517[Json Web Keys (JWK)] specification. The way to do so is defined in `Signed JWT` of <<_client-credentials, Confidential Client Credentials>>. The detailed procedure is as follows: The client needs to pass their public key for encrypting CEK onto {project_name}. {project_name} supports downloading public keys from the URL the client provides. The client needs to provide their public keys according to https://datatracker.ietf.org/doc/html/rfc7517[Json Web Keys (JWK)] specification. The way to do so is defined in `Signed JWT` of <<_client-credentials, Confidential Client Credentials>>. The detailed procedure is as follows:
* open the client's `Keys` tab * open the client's `Keys` tab
* toggle `JWKS URL` to ON * toggle `JWKS URL` to ON
* input the client's public key providing URL on `JWKS URL` textbox * input the client's public key providing URL on `JWKS URL` textbox
Key Encryption's algorithms are defined in the https://tools.ietf.org/html/rfc7518#section-4.1[Json Web Algorithm (JWA)] specification. {project_name} supports RSAES-PKCS1-v1_5(RSA1_5), RSAES OAEP using default parameters (RSA-OAEP), and RSAES OAEP 256 using SHA-256 and MFG1 (RSA-OAEP-256). The detailed procedure to select this algorithm is as follows: Key Encryption's algorithms are defined in the https://datatracker.ietf.org/doc/html/rfc7518#section-4.1[Json Web Algorithm (JWA)] specification. {project_name} supports RSAES-PKCS1-v1_5(RSA1_5), RSAES OAEP using default parameters (RSA-OAEP), and RSAES OAEP 256 using SHA-256 and MFG1 (RSA-OAEP-256). The detailed procedure to select this algorithm is as follows:
* open the client's `Settings` tab * open the client's `Settings` tab
* open `Fine Grain OpenID Connect Configuration` * open `Fine Grain OpenID Connect Configuration`
* select `RSA1_5`, `RSA-OAEP`, or `RSA-OAEP-256` from `ID Token Encryption Key Management Algorithm` pulldown menu * select `RSA1_5`, `RSA-OAEP`, or `RSA-OAEP-256` from `ID Token Encryption Key Management Algorithm` pulldown menu
ID token encryption algorithms by CEK are also defined in the https://tools.ietf.org/html/rfc7518#section-5.1[JWA] specification. {project_name} supports AES_CBC_HMAC_SHA2 algorithms and AES GCM algorithms. The detailed procedure to select this algorithm is as follows: ID token encryption algorithms by CEK are also defined in the https://datatracker.ietf.org/doc/html/rfc7518#section-5.1[JWA] specification. {project_name} supports AES_CBC_HMAC_SHA2 algorithms and AES GCM algorithms. The detailed procedure to select this algorithm is as follows:
* open the client's `Settings` tab * open the client's `Settings` tab
* open `Fine Grain OpenID Connect Configuration` * open `Fine Grain OpenID Connect Configuration`

2
server_admin/topics/clients/oidc/confidential.adoc
View file

@ -74,6 +74,6 @@ The validator checks also the certificate's Subject DN field with configured reg
use cases, it is sufficient to accept all certificates. In that case, you can use `(.*?)(?:$)` expression. use cases, it is sufficient to accept all certificates. In that case, you can use `(.*?)(?:$)` expression.
There are two ways for {project_name} to obtain the Client ID from the request. The first option is the `client_id` There are two ways for {project_name} to obtain the Client ID from the request. The first option is the `client_id`
parameter in the query (described in Section 2.2 of the https://tools.ietf.org/html/rfc6749[OAuth 2.0 Specification]). parameter in the query (described in Section 2.2 of the https://datatracker.ietf.org/doc/html/rfc6749[OAuth 2.0 Specification]).
The second option is to supply `client_id` as a form parameter. The second option is to supply `client_id` as a form parameter.

2
server_admin/topics/clients/oidc/service-accounts.adoc
View file

@ -32,7 +32,7 @@ For example the POST invocation to retrieve a service account can look like this
grant_type=client_credentials grant_type=client_credentials
---- ----
The response would be this https://tools.ietf.org/html/rfc6749#section-4.4.3[standard JSON document] from the OAuth 2.0 specification. The response would be this https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.3[standard JSON document] from the OAuth 2.0 specification.
[source] [source]
---- ----

2
server_admin/topics/sso-protocols/docker.adoc
View file

@ -12,7 +12,7 @@ The link:https://docs.docker.com/registry/spec/auth/token/[Docker API documentat
NOTE: This flow assumes that a `docker login` command has already been performed NOTE: This flow assumes that a `docker login` command has already been performed
* The flow begins when the Docker client requests a resource from the Docker registry. If the resource is protected and no auth token is present in the request, the Docker registry server will respond to the client with a 401 + some information on required permissions and where to find the authorization server. * The flow begins when the Docker client requests a resource from the Docker registry. If the resource is protected and no auth token is present in the request, the Docker registry server will respond to the client with a 401 + some information on required permissions and where to find the authorization server.
* The Docker client will construct an authentication request based on the 401 response from the Docker registry. The client will then use the locally cached credentials (from a previously run `docker login` command) as part of a link:https://tools.ietf.org/html/rfc2617[HTTP Basic Authentication] request to the {project_name} authentication server. * The Docker client will construct an authentication request based on the 401 response from the Docker registry. The client will then use the locally cached credentials (from a previously run `docker login` command) as part of a link:https://datatracker.ietf.org/doc/html/rfc2617[HTTP Basic Authentication] request to the {project_name} authentication server.
* The {project_name} authentication server will attempt to authenticate the user and return a JSON body containing an OAuth-style Bearer token. * The {project_name} authentication server will attempt to authenticate the user and return a JSON body containing an OAuth-style Bearer token.
* The Docker client will get the bearer token from the JSON response and use it in the Authorization header to request the protected resource. * The Docker client will get the bearer token from the JSON response and use it in the Authorization header to request the protected resource.
* When the Docker registry receives the new request for the protected resource with the token from the {project_name} server, the registry validates the token and grants access to the requested resource (if appropriate). * When the Docker registry receives the new request for the protected resource with the token from the {project_name} server, the registry validates the token and grants access to the requested resource (if appropriate).

6
server_admin/topics/sso-protocols/oidc.adoc
View file

@ -2,7 +2,7 @@
=== OpenID Connect === OpenID Connect
link:https://openid.net/connect/[OpenID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0]. link:https://openid.net/connect/[OpenID Connect] (OIDC) is an authentication protocol that is an extension of link:https://datatracker.ietf.org/doc/html/rfc6749[OAuth 2.0].
While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization
protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define an protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define an
identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way. identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way.
@ -57,7 +57,7 @@ client. HTML5/JavaScript clients always have to be _public_ clients because the
manner. Again, this is ok so long as you use HTTPS and strictly enforce redirect URI registration. This guide goes more detail manner. Again, this is ok so long as you use HTTPS and strictly enforce redirect URI registration. This guide goes more detail
into this in the <<_clients, Managing Clients>> chapter. into this in the <<_clients, Managing Clients>> chapter.
{project_name} also supports the optional https://tools.ietf.org/html/rfc7636[Proof Key for Code Exchange] specification. {project_name} also supports the optional https://datatracker.ietf.org/doc/html/rfc7636[Proof Key for Code Exchange] specification.
===== Implicit Flow ===== Implicit Flow
@ -336,7 +336,7 @@ You can also find these endpoints under "OpenID Endpoint Configuration" in your
/realms/{realm-name}/protocol/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. This is the URL endpoint for the User Info service described in the OIDC specification.
/realms/{realm-name}/protocol/openid-connect/revoke:: /realms/{realm-name}/protocol/openid-connect/revoke::
This is the URL endpoint for OAuth 2.0 Token Revocation described in https://tools.ietf.org/html/rfc7009[RFC7009]. This is the URL endpoint for OAuth 2.0 Token Revocation described in https://datatracker.ietf.org/doc/html/rfc7009[RFC7009].
/realms/{realm-name}/protocol/openid-connect/certs:: /realms/{realm-name}/protocol/openid-connect/certs::
This is the URL endpoint for the JSON Web Key Set (JWKS) containing the public keys used to verify any JSON Web Token (jwks_uri) This is the URL endpoint for the JSON Web Key Set (JWKS) containing the public keys used to verify any JSON Web Token (jwks_uri)
/realms/{realm-name}/protocol/openid-connect/auth/device:: /realms/{realm-name}/protocol/openid-connect/auth/device::

2
server_admin/topics/threat.adoc
View file

@ -3,6 +3,6 @@
This chapter discusses possible security vulnerabilities any authentication server could have and how {project_name} This chapter discusses possible security vulnerabilities any authentication server could have and how {project_name}
mitigates those vulnerabilities. mitigates those vulnerabilities.
A good list of potential vulnerabilities and what security implementations should do to mitigate them can be found in A good list of potential vulnerabilities and what security implementations should do to mitigate them can be found in
the https://tools.ietf.org/html/rfc6819[OAuth 2.0 Threat Model] document and its most recent extension https://tools.ietf.org/html/draft-ietf-oauth-security-topics-15[OAuth 2.0 Security Best Current Practice] put out by the IETF. the https://datatracker.ietf.org/doc/html/rfc6819[OAuth 2.0 Threat Model] document and its most recent extension https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-15[OAuth 2.0 Security Best Current Practice] put out by the IETF.
Many of those vulnerabilities are discussed here. Many of those vulnerabilities are discussed here.

2
server_admin/topics/threat/audience-limit.adoc
View file

@ -2,5 +2,5 @@
=== Limit Token Audience === Limit Token Audience
In environments where the level of trust among services is low, it is a good practice to limit the audiences on the token. The In environments where the level of trust among services is low, it is a good practice to limit the audiences on the token. The
motivation behind this is described in the https://tools.ietf.org/html/rfc6819#section-5.1.5.5[OAuth2 Threat Model] document and motivation behind this is described in the https://datatracker.ietf.org/doc/html/rfc6819#section-5.1.5.5[OAuth2 Threat Model] document and
more details are in the <<_audience, Audience Support section>>. more details are in the <<_audience, Audience Support section>>.

2
server_admin/topics/threat/clickjacking.adoc
View file

@ -7,7 +7,7 @@ When a user clicks a visible button, they are actually clicking a button (such a
An attacker can steal a user's authentication credentials and access their resources. An attacker can steal a user's authentication credentials and access their resources.
By default, every response by {project_name} sets some specific browser headers that can prevent this from happening. By default, every response by {project_name} sets some specific browser headers that can prevent this from happening.
Specifically, it sets https://tools.ietf.org/html/rfc7034[X-FRAME_OPTIONS] and http://www.w3.org/TR/CSP/[Content-Security-Policy]. Specifically, it sets https://datatracker.ietf.org/doc/html/rfc7034[X-FRAME_OPTIONS] and http://www.w3.org/TR/CSP/[Content-Security-Policy].
You should take a look at the definition of both of these headers as there is a lot of fine-grain browser access you can control. You should take a look at the definition of both of these headers as there is a lot of fine-grain browser access you can control.
In the admin console you can specify the values these headers will have. Go to the `Realm Settings` left menu item and In the admin console you can specify the values these headers will have. Go to the `Realm Settings` left menu item and
click the `Security Defenses` tab and make sure you are on the `Headers` sub-tab. click the `Security Defenses` tab and make sure you are on the `Headers` sub-tab.

6
server_development/topics/auth-spi.adoc
View file

@ -1183,12 +1183,12 @@ For more details about {project_name} adapter and OAuth2 flows see link:{adapter
Actually {project_name} has 2 default implementations of client authentication: Actually {project_name} has 2 default implementations of client authentication:
Traditional authentication with client_id and client_secret:: Traditional authentication with client_id and client_secret::
This is default mechanism mentioned in the https://openid.net/specs/openid-connect-core-1_0.html[OpenID Connect] or https://tools.ietf.org/html/rfc6749[OAuth2] specification and {project_name} supports it since it's early days. This is default mechanism mentioned in the https://openid.net/specs/openid-connect-core-1_0.html[OpenID Connect] or https://datatracker.ietf.org/doc/html/rfc6749[OAuth2] specification and {project_name} supports it since it's early days.
The public client needs to include `client_id` parameter with its ID in the POST request (so it's defacto not authenticated) and the confidential client needs to include `Authorization: Basic` header with the clientId and clientSecret used as username and password. The public client needs to include `client_id` parameter with its ID in the POST request (so it's defacto not authenticated) and the confidential client needs to include `Authorization: Basic` header with the clientId and clientSecret used as username and password.
Authentication with signed JWT:: Authentication with signed JWT::
This is based on the https://tools.ietf.org/html/rfc7523[JWT Bearer Token Profiles for OAuth 2.0] specification. This is based on the https://datatracker.ietf.org/doc/html/rfc7523[JWT Bearer Token Profiles for OAuth 2.0] specification.
The client/adapter generates the https://tools.ietf.org/html/rfc7519[JWT] and signs it with his private key. The client/adapter generates the https://datatracker.ietf.org/doc/html/rfc7519[JWT] and signs it with his private key.
The {project_name} then verifies the signed JWT with the client's public key and authenticates client based on it. The {project_name} then verifies the signed JWT with the client's public key and authenticates client based on it.
See the demo example and especially the `examples/preconfigured-demo/product-app` for the example application showing See the demo example and especially the `examples/preconfigured-demo/product-app` for the example application showing

2
server_installation/topics/operating-mode/crossdc.adoc
View file

@ -746,7 +746,7 @@ The potential issue is, that in some cases, there may be just some a short netwo
How bad are these inconsistencies? Usually only means that a user will need to re-authenticate. How bad are these inconsistencies? Usually only means that a user will need to re-authenticate.
When using the `WARN` policy, it may happen that the single-use cache, which is provided by the `actionTokens` cache and which handles that particular key is really single use, but may "successfully" write the same key twice. But, for example, the OAuth2 specification link:https://tools.ietf.org/html/rfc6749#section-10.5[mentions] that code must be single-use. With the `WARN` policy, this may not be strictly guaranteed and the same code could be written twice if there is an attempt to write it concurrently in both sites. When using the `WARN` policy, it may happen that the single-use cache, which is provided by the `actionTokens` cache and which handles that particular key is really single use, but may "successfully" write the same key twice. But, for example, the OAuth2 specification link:https://datatracker.ietf.org/doc/html/rfc6749#section-10.5[mentions] that code must be single-use. With the `WARN` policy, this may not be strictly guaranteed and the same code could be written twice if there is an attempt to write it concurrently in both sites.
If there is a longer network outage or split-brain, then with both `FAIL` and `WARN`, the other site will be taken offline after some time and failures as described in <<onoffline>>. With the default 1 minute timeout, it is usually 1-3 minutes until all the involved caches are taken offline. After that, all the operations will work fine from an end user perspective. If there is a longer network outage or split-brain, then with both `FAIL` and `WARN`, the other site will be taken offline after some time and failures as described in <<onoffline>>. With the default 1 minute timeout, it is usually 1-3 minutes until all the involved caches are taken offline. After that, all the operations will work fine from an end user perspective.
You only need to manually restore the site when it is back online as mentioned in <<onoffline>>. You only need to manually restore the site when it is back online as mentioned in <<onoffline>>.

2
upgrading/topics/keycloak/changes.adoc
View file

@ -184,7 +184,7 @@ logs in.
==== Non-standard token introspection endpoint removed ==== Non-standard token introspection endpoint removed
In previous versions, Keycloak advertized two introspection endpoints: `token_introspection_endpoint` and `introspection_endpoint`. In previous versions, Keycloak advertized two introspection endpoints: `token_introspection_endpoint` and `introspection_endpoint`.
The latter is the one defined by https://tools.ietf.org/html/rfc8414#section-2[RFC-8414]. The former, previously deprecated, The latter is the one defined by https://datatracker.ietf.org/doc/html/rfc8414#section-2[RFC-8414]. The former, previously deprecated,
has now been removed. has now been removed.
=== Migrating to 9.0.1 === Migrating to 9.0.1