Move oidc documentation to guides (#31627)
Closes #31329 Signed-off-by: Giuseppe Graziano <g.graziano94@gmail.com>
This commit is contained in:
Giuseppe Graziano
GitHub
parent
d91d6d18d5
commit
c3019fb2d3
27 changed files with 122 additions and 148 deletions
|
|
@ -7,4 +7,4 @@ get started with {project_name} Authorization Services:
|
|||
* {quickstartRepo_link}/tree/latest/jakarta/servlet-authz-client[Securing a JakartaEE Application in Wildfly]
|
||||
* {quickstartRepo_link}/tree/latest/spring/rest-authz-resource-server[Securing a Spring Boot Application]
|
||||
* link:https://quarkus.io/guides/security-keycloak-authorization[Securing Quarkus Applications]
|
||||
* {adapterguide_link_nodejs_adapter}[Securing Node.js Applications]
|
||||
* *Keycloak Node.js adapter* in the link:{securing_apps_link}[securing apps] section
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ please take a look at link:{upgradingguide_link_latest}[{upgradingguide_name}].
|
|||
The `SameSite` value `None` for `JSESSIONID` cookie is necessary for correct behavior of the {project_name} SAML adapter.
|
||||
Usage of a different value is causing resetting of the container's session with each request to {project_name}, when
|
||||
the SAML POST binging is used. Refer to the following steps for
|
||||
link:https://www.keycloak.org/guides#securing-apps[Keycloak SAML Galleon feature pack for WildFly and EAP] guide to keep the correct behavior. Notice, that this
|
||||
link:{securing_apps_link}[Keycloak SAML Galleon feature pack for WildFly and EAP] guide to keep the correct behavior. Notice, that this
|
||||
workaround should be working also with the previous versions of the adapter.
|
||||
|
||||
== Other improvements
|
||||
|
|
|
|||
|
|
@ -8,19 +8,6 @@ include::topics/overview/terminology.adoc[]
|
|||
|
||||
include::topics/oidc/oidc-overview.adoc[]
|
||||
|
||||
include::topics/oidc/available-endpoints.adoc[]
|
||||
|
||||
include::topics/oidc/supported-grant-types.adoc[]
|
||||
|
||||
include::topics/oidc/oidc-errors.adoc[]
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
include::topics/oidc/java/java-adapters.adoc[]
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
include::topics/oidc/java/java-adapters-product.adoc[]
|
||||
endif::[]
|
||||
|
||||
include::topics/oidc/javascript-adapter.adoc[]
|
||||
|
||||
include::topics/oidc/nodejs-adapter.adoc[]
|
||||
|
|
@ -29,12 +16,6 @@ ifeval::[{project_community}==true]
|
|||
include::topics/oidc/mod-auth-openidc.adoc[]
|
||||
endif::[]
|
||||
|
||||
include::topics/oidc/fapi-support.adoc[]
|
||||
|
||||
include::topics/oidc/oauth21-support.adoc[]
|
||||
|
||||
include::topics/oidc/recommendations.adoc[]
|
||||
|
||||
include::topics/saml/saml-overview.adoc[]
|
||||
ifeval::[{project_product}==true]
|
||||
include::topics/saml/java/java-adapters-product.adoc[]
|
||||
|
|
|
|||
|
|
@ -1,35 +0,0 @@
|
|||
=== {project_name} Java adapters
|
||||
|
||||
==== Red Hat JBoss Enterprise Application Platform
|
||||
|
||||
{project_name} does not include any adapters for Red Hat JBoss Enterprise Application Platform. However, there are
|
||||
alternatives for existing applications deployed to Red Hat JBoss Enterprise Application Platform.
|
||||
|
||||
===== 8.0 Beta
|
||||
|
||||
Red Hat Enterprise Application Platform 8.0 Beta provides a native OpenID Connect client through the Elytron OIDC client
|
||||
subsystem.
|
||||
|
||||
For more information, see the https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/8-beta/html/using_single_sign-on_with_jboss_eap/index[Red Hat JBoss Enterprise Application Platform documentation].
|
||||
|
||||
===== 6.4 and 7.x
|
||||
|
||||
Existing applications deployed to Red Hat JBoss Enterprise Application Platform 6.4 and 7.x can leverage adapters from
|
||||
Red Hat Single Sign-On 7.6 in combination with the {project_name} server.
|
||||
|
||||
For more information, see the
|
||||
https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html/securing_applications_and_services_guide/oidc#jboss_adapter[Red Hat Single Sign-On documentation].
|
||||
|
||||
|
||||
==== Spring Boot adapter
|
||||
|
||||
{project_name} does not include any adapters for Spring Boot. However, there are
|
||||
alternatives for existing applications built with Spring Boot.
|
||||
|
||||
Spring Security provides comprehensive support for OAuth 2 and OpenID Connect. For more information, see the
|
||||
https://spring.io/projects/spring-security[Spring Security documentation].
|
||||
|
||||
Alternatively, for Spring Boot 2.x the Spring Boot adapter from Red Hat Single Sign-On 7.6 can be used in combination with the {project_name} server. For more information, see the
|
||||
https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html/securing_applications_and_services_guide/oidc#spring_boot_adapter[Red Hat Single Sign-On documentation].
|
||||
|
||||
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
=== {project_name} Java adapters
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
{project_name} Java Adapters were removed from {project_name} codebase and they are not supported anymore.
|
||||
|
||||
For more details about how to integrate {project_name} with Java applications, consider looking at the
|
||||
{quickstartRepo_link}[Keycloak Quickstart GitHub Repository].
|
||||
====
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
[[_oidc]]
|
||||
== Using OpenID Connect to secure applications and services
|
||||
|
||||
This section describes how you can secure applications and services with OpenID Connect using {project_name}.
|
||||
This section describes how you can secure applications and services with OpenID Connect using {project_name}.
|
||||
|
|
|
|||
|
|
@ -16,10 +16,10 @@ ifeval::[{project_community}==true]
|
|||
endif::[]
|
||||
|
||||
===== JavaScript (client-side)
|
||||
* <<_javascript_adapter,JavaScript>>
|
||||
* JavaScript
|
||||
|
||||
===== Node.js (server-side)
|
||||
* <<_nodejs_adapter,Node.js>>
|
||||
* Node.js
|
||||
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
|
|
|
|||
|
|
@ -13,13 +13,13 @@ The authentication session usually expires after 30 minutes by default. The exac
|
|||
|
||||
As described in the previous section, a situation can involve a user who is trying to authenticate to the {project_name} server from multiple tabs of a single browser. However, when that user authenticates in one browser tab,
|
||||
the other browser tabs will automatically restart the authentication. This authentication occurs due to the small javascript available on the {project_name} login pages. The restart will typically
|
||||
authenticate the user in other browser tabs and redirect to clients because there is an SSO session now due to the fact that the user just successfully authenticated in first browser tab.
|
||||
authenticate the user in other browser tabs and redirect to clients because there is an SSO session now due to the fact that the user just successfully authenticated in first browser tab.
|
||||
Some rare exceptions exist when a user is not automatically authenticated in other browser tabs, such as for instance when using an OIDC parameter _prompt=login_ or <<_step-up-flow, step-up authentication>> requesting a stronger
|
||||
authentication factor than the currently authenticated factor.
|
||||
|
||||
In some rare cases, it can happen that after authentication in the first browser tab, other browser tabs are not able to restart authentication because the authentication session is already
|
||||
expired. In this case, the particular browser tab will redirect the error about the expired authentication session back to the client in a protocol specific way. For more details, see the corresponding sections
|
||||
of link:{adapterguide_link}#_oidc-errors[OIDC documentation] and link:{adapterguide_link}#_saml-errors[SAML documentation]. When the client application receives such an error, it can immediately resubmit the OIDC/SAML authentication request to {project_name} as
|
||||
of *OIDC documentation* in the link:{securing_apps_link}[securing apps] section and link:{adapterguide_link}#_saml-errors[SAML documentation]. When the client application receives such an error, it can immediately resubmit the OIDC/SAML authentication request to {project_name} as
|
||||
this should usually automatically authenticate the user due to the existing SSO session as described earlier. As a result, the end user is authenticated automatically in all browser tabs.
|
||||
The link:{adapterguide_link}#_javascript_adapter[{project_name} Javascript adapter], link:{adapterguide_link}#_saml[{project_name} SAML adapter], and <<_identity_broker, {project_name} Identity provider>>
|
||||
The *Keycloak JavaScript adapter* in the link:{securing_apps_link}[securing apps] section, link:{adapterguide_link}#_saml[{project_name} SAML adapter], and <<_identity_broker, {project_name} Identity provider>>
|
||||
support to handle this error automatically and retry the authentication to the {project_name} server in such a case.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ An _authentication flow_ is a container of authentications, screens, and actions
|
|||
image:images/browser-flow.png[Browser Flow]
|
||||
|
||||
===== Auth type
|
||||
The name of the authentication or the action to execute. If an authentication is indented, it is in a sub-flow. It may or may not be executed, depending on the behavior of its parent.
|
||||
The name of the authentication or the action to execute. If an authentication is indented, it is in a sub-flow. It may or may not be executed, depending on the behavior of its parent.
|
||||
|
||||
. Cookie
|
||||
+
|
||||
|
|
@ -60,12 +60,12 @@ The element does not count to mark a flow as successful.
|
|||
|
||||
====== Conditional
|
||||
|
||||
This requirement type is only set on sub-flows.
|
||||
This requirement type is only set on sub-flows.
|
||||
|
||||
* A _Conditional_ sub-flow contains executions. These executions must evaluate to logical statements.
|
||||
* If all executions evaluate as _true_, the _Conditional_ sub-flow acts as _Required_.
|
||||
* A _Conditional_ sub-flow contains executions. These executions must evaluate to logical statements.
|
||||
* If all executions evaluate as _true_, the _Conditional_ sub-flow acts as _Required_.
|
||||
* If any executions evaluate as _false_, the _Conditional_ sub-flow acts as _Disabled_.
|
||||
* If you do not set an execution, the _Conditional_ sub-flow acts as _Disabled_.
|
||||
* If you do not set an execution, the _Conditional_ sub-flow acts as _Disabled_.
|
||||
* If a flow contains executions and the flow is not set to _Conditional_, {project_name} does not evaluate the executions, and the executions are considered functionally _Disabled_.
|
||||
|
||||
==== Creating flows
|
||||
|
|
@ -118,7 +118,7 @@ AMR claim, see https://www.rfc-editor.org/rfc/rfc8176.html[RFC-8176]). When the
|
|||
image:images/config-authenticator-reference.png[Configuring an Authenticator Reference Value]
|
||||
|
||||
Two types of executions exist, _automatic executions_ and _interactive executions_. _Automatic executions_ are similar to the *Cookie* execution and will automatically
|
||||
perform their action in the flow. _Interactive executions_ halt the flow to get input. Executions executing successfully set their status to _success_. For a flow to complete, it needs at least one execution with a status of _success_.
|
||||
perform their action in the flow. _Interactive executions_ halt the flow to get input. Executions executing successfully set their status to _success_. For a flow to complete, it needs at least one execution with a status of _success_.
|
||||
|
||||
You can add sub-flows to top-level flows with the *Add sub-flow* button. The *Add sub-flow* button displays the *Create Execution Flow* page. This page is similar to the *Create Top Level Form* page. The difference is that the *Flow Type* can be *basic* (default) or *form*. The *form* type constructs a sub-flow that generates a form for the user, similar to the built-in *Registration* flow.
|
||||
Sub-flows success depends on how their executions evaluate, including their contained sub-flows. See the <<_execution-requirements, execution requirements section>> for an in-depth explanation of how sub-flows work.
|
||||
|
|
@ -343,7 +343,7 @@ claims= {
|
|||
----
|
||||
|
||||
The {project_name} javascript adapter has support for easy construct of this JSON and sending it in the login request.
|
||||
See link:{adapterguide_link_js_adapter}[Javascript adapter documentation] for more details.
|
||||
See *Keycloak JavaScript adapter* in the link:{securing_apps_link}[securing apps] section for more details.
|
||||
|
||||
You can also use simpler parameter `acr_values` instead of `claims` parameter to request particular levels as non-essential. This is mentioned
|
||||
in the OIDC specification.
|
||||
|
|
@ -382,7 +382,7 @@ and that level expired, the user is not required to re-authenticate, but `acr` i
|
|||
based solely on `long-lived browser cookie` as mentioned in the section 2 of OIDC Core 1.0 specification.
|
||||
|
||||
NOTE: During the first authentication of the user, the first configured subflow with the *Conditional - Level Of Authentication* is always executed (regardless of the requested level) as
|
||||
the user does not yet have any level. Therefore, we recommend that the first level subflow contains the minimal required authenticators for user authentication. In addition, ensure that the subflows with different values of *Conditional - Level Of Authentication* are ordered starting with the lowest as shown
|
||||
the user does not yet have any level. Therefore, we recommend that the first level subflow contains the minimal required authenticators for user authentication. In addition, ensure that the subflows with different values of *Conditional - Level Of Authentication* are ordered starting with the lowest as shown
|
||||
in the example above. For example, if you configure a subflow with level 2 and then add another subflow with level 1, the level 2 subflow will be always asked during the first authentication, which may
|
||||
not be the desired behavior.
|
||||
|
||||
|
|
@ -415,7 +415,7 @@ Usually when the user is redirected to the {project_name} from client applicatio
|
|||
that realm registration is enabled and the user clicks `Register` on the login screen. Also, if <<enabling-forgot-password,Forget password>> is enabled for the realm, the user can
|
||||
click `Forget password` on the login screen, which triggers the `Reset credentials` flow where users can reset credentials after email address confirmation.
|
||||
|
||||
Sometimes it can be useful for the client application to directly redirect the user to the *Registration* screen or to the *Reset credentials* flow. The resulting action will match the action of when the
|
||||
Sometimes it can be useful for the client application to directly redirect the user to the *Registration* screen or to the *Reset credentials* flow. The resulting action will match the action of when the
|
||||
user clicks *Register* or *Forget password* on the normal login screen. Automatic redirect to the registration or reset-credentials screen can be done as follows:
|
||||
|
||||
* When the client wants the user to be redirected directly to the registration, the OIDC client should replace the very last snippet from the OIDC login URL path (`/auth`) with `/registrations` . So the full URL
|
||||
|
|
@ -467,7 +467,7 @@ with password and OTP:
|
|||
|
||||
image:images/authentication-user-session-limits-browser.png[Authentication User Session Limits Browser Flow]
|
||||
|
||||
Regarding `Post Broker login flow`, you can add the `User Session Limits` as the only authenticator in the authentication flow as long as you have no other authenticators that you trigger after authentication with your identity provider. However, make sure that this flow is configured as `Post Broker Flow` at your identity providers. This requirement exists needed so that
|
||||
Regarding `Post Broker login flow`, you can add the `User Session Limits` as the only authenticator in the authentication flow as long as you have no other authenticators that you trigger after authentication with your identity provider. However, make sure that this flow is configured as `Post Broker Flow` at your identity providers. This requirement exists needed so that
|
||||
the authentication with Identity providers also participates in the session limits.
|
||||
|
||||
NOTE: Currently, the administrator is responsible for maintaining consistency between the different configurations. So make sure that all your flows use same the configuration
|
||||
|
|
|
|||
|
|
@ -191,7 +191,7 @@ image:images/x509-directgrant-flow-bindings.png[X509 Direct Grant Flow Bindings]
|
|||
===== Example using CURL
|
||||
|
||||
The following example shows how to obtain an access token for a user in the realm `test` with the direct grant flow. The example is using
|
||||
link:{adapterguide_link}#_resource_owner_password_credentials_flow[OAuth2 Resource Owner Password Credentials Grant] and the confidential client `resource-owner`:
|
||||
*OAuth2 Resource Owner Password Credentials Grant* in the link:{securing_apps_link}[securing apps] section and the confidential client `resource-owner`:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
|
|
@ -214,7 +214,7 @@ According to your environment, it might be needed to use more options to CURL co
|
|||
* Option `--capath` to include the whole directory containing the certificate authority path
|
||||
* Options `--cert-type` or `--key-type` in case you want to use different files than `PEM`
|
||||
|
||||
Please consult the documentation of the `curl` tool for the details if needed. If you are using other tools than `curl`,
|
||||
Please consult the documentation of the `curl` tool for the details if needed. If you are using other tools than `curl`,
|
||||
consult the documentation of your tool. However, the setup would be similar. A need exists to include keystore and truststore as well as client credentials in case you are using a confidential
|
||||
client.
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ Validation of client configurations::
|
|||
the advanced security requirements. In the future, individual client configuration settings may be replaced by Client Policies directly performing required validations.
|
||||
|
||||
Conformance to a required security standards and profiles such as FAPI and OAuth 2.1::
|
||||
The _Global client profiles_ are client profiles pre-configured in {project_name} by default. They are pre-configured to be compliant with standard security profiles like link:{adapterguide_link}#_fapi-support[FAPI] and link:{adapterguide_link}#_oauth21-support[OAuth 2.1],
|
||||
The _Global client profiles_ are client profiles pre-configured in {project_name} by default. They are pre-configured to be compliant with standard security profiles like *FAPI* and *OAuth 2.1* in the link:{securing_apps_link}[securing apps] section,
|
||||
which makes it easy for the administrator to secure their client application to be compliant with the particular security profile. At this moment, {project_name} has global
|
||||
profiles for the support of FAPI and OAuth 2.1 specifications. The administrator will just need to configure the client policies to specify which clients should
|
||||
be compliant with the FAPI and OAuth 2.1. The administrator can configure client profiles and client policies, so that {project_name} clients can be easily made compliant with various other
|
||||
|
|
@ -37,7 +37,7 @@ Conformance to a required security standards and profiles such as FAPI and OAuth
|
|||
|
||||
== Protocol
|
||||
|
||||
The client policy concept is independent of any specific protocol. {project_name} currently supports especially client profiles for the link:{adapterguide_link}#_oidc[OpenID Connect (OIDC) protocol], but there is
|
||||
The client policy concept is independent of any specific protocol. {project_name} currently supports especially client profiles for the link:{securing_apps_link}[OpenID Connect (OIDC) protocol], but there is
|
||||
also a client profile available for the link:{adapterguide_link}#_saml[SAML protocol].
|
||||
|
||||
== Architecture
|
||||
|
|
@ -80,7 +80,7 @@ Client Role::
|
|||
Applies for clients with the client role of the specified name. Typically you can create a client role of specified name to requested clients and use it as a "marker role" to make
|
||||
sure that specified client policy will be applied for requested clients.
|
||||
|
||||
NOTE: A use-case often exists for requiring the application of a particular client policy for the specified clients such as `my-client-1` and `my-client-2`. The best way to achieve this result
|
||||
NOTE: A use-case often exists for requiring the application of a particular client policy for the specified clients such as `my-client-1` and `my-client-2`. The best way to achieve this result
|
||||
is to use a *Client Role* condition in your policy and then a create client role of specified name to requested clients. This client role can be used as a "marker role" used solely
|
||||
for marking that particular client policy for particular clients.
|
||||
|
||||
|
|
@ -144,7 +144,7 @@ One of several purposes for this executor is to realize the security requirement
|
|||
|
||||
A profile consists of several executors, which can realize a security profile like FAPI and OAuth 2.1. Profile can be configured by the Admin REST API (Admin Console) together with its executors.
|
||||
Three _global profiles_ exist and they are configured in {project_name} by default with pre-configured executors compliant with the FAPI 1 Baseline, FAPI 1 Advanced, FAPI CIBA, FAPI 2 and OAuth 2.1 specifications.
|
||||
More details exist in the FAPI and OAuth 2.1 section of the link:{adapterguide_link}#_fapi-support[{adapterguide_name}].
|
||||
More details exist in the *FAPI* and *OAuth 2.1* in the link:{securing_apps_link}[securing apps] section.
|
||||
|
||||
[[_client_policy_policy]]
|
||||
=== Policy
|
||||
|
|
|
|||
|
|
@ -91,4 +91,4 @@ Using a lightweight access token in {project_name}::
|
|||
By applying `use-lightweight-access-token` executor of <<_client_policies, client policies>> to a client, the client can receive a lightweight access token instead of an access token. The lightweight access token contains a claim controlled by a protocol mapper where its setting `Add to lightweight access token`(default OFF) is turned ON. Also, by turning ON its setting `Add to token introspection` of the protocol mapper, the client can obtain the claim by sending the access token to {project_name}'s token introspection endpoint.
|
||||
|
||||
Introspection endpoint::
|
||||
In some cases, it might be useful to trigger the token introspection endpoint with the HTTP header `Accept: application/jwt` instead of `Accept: application/json`, which can be useful especially for lightweight access tokens. See the details in the link:{adapterguide_link}#_token_introspection_endpoint[Token Introspection endpoint] section.
|
||||
In some cases, it might be useful to trigger the token introspection endpoint with the HTTP header `Accept: application/jwt` instead of `Accept: application/json`, which can be useful especially for lightweight access tokens. See the details of *Token Introspection endpoint* in the link:{securing_apps_link}[securing apps] section.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ In the environment where trust among services is low, you may encounter this sce
|
|||
|
||||
. A frontend client application requires authentication against {project_name}.
|
||||
|
||||
. {project_name} authenticates a user.
|
||||
. {project_name} authenticates a user.
|
||||
|
||||
. {project_name} issues a token to the application.
|
||||
|
||||
|
|
@ -27,11 +27,11 @@ To prevent any misuse of the access token, limit the audience on the token and c
|
|||
|
||||
. A frontend application authenticates against {project_name}.
|
||||
|
||||
. {project_name} authenticates a user.
|
||||
. {project_name} authenticates a user.
|
||||
|
||||
. {project_name} issues a token to the application. The application knows that it will need to invoke an untrusted service so it places *scope=<untrusted service>* in the authentication request sent to {project_name} (see <<_client_scopes, Client Scopes section>> for more details about the _scope_ parameter).
|
||||
+
|
||||
The token issued to the application contains a reference to the untrusted service in its audience (*"audience": [ "<untrusted service>" ]*) which declares that the client uses this access token to invoke the untrusted service.
|
||||
The token issued to the application contains a reference to the untrusted service in its audience (*"audience": [ "<untrusted service>" ]*) which declares that the client uses this access token to invoke the untrusted service.
|
||||
+
|
||||
.The untrusted service serves the request to the client application but also keeps the token.
|
||||
|
||||
|
|
@ -70,7 +70,7 @@ you can use the access token issued for the confidential client to invoke the se
|
|||
|
||||
[NOTE]
|
||||
====
|
||||
If you want to ensure that the audience is not added automatically, do not configure role scope mappings directly on the confidential client. Instead, you can create a dedicated client scope that contains the role scope mappings for the client roles of your dedicated client scope.
|
||||
If you want to ensure that the audience is not added automatically, do not configure role scope mappings directly on the confidential client. Instead, you can create a dedicated client scope that contains the role scope mappings for the client roles of your dedicated client scope.
|
||||
|
||||
Assuming that the client scope is added as an optional client scope to the confidential client, the client roles and the audience will be added to the token if explicitly requested by the *scope=<trusted service>* parameter.
|
||||
====
|
||||
|
|
@ -103,16 +103,16 @@ image:images/audience_mapper.png[]
|
|||
On the confidential client:
|
||||
+
|
||||
. Click the _Client Scopes_ tab.
|
||||
. Assign *good-service* as an optional (or default) client scope.
|
||||
. Assign *good-service* as an optional (or default) client scope.
|
||||
+
|
||||
See <<_client_scopes_linking, Client Scopes Linking section>> for more details.
|
||||
|
||||
* You can optionally <<_client_scopes_evaluate, Evaluate Client Scopes>> and generate an example access token. *good-service* will be added to the audience of the generated access token if *good-service* is included in the _scope_ parameter, when you assigned it as an optional client scope.
|
||||
|
||||
* In your confidential client application, ensure that the _scope_ parameter is used. The value *good-service* must be included when you want to issue the token for accessing *good-service*.
|
||||
* In your confidential client application, ensure that the _scope_ parameter is used. The value *good-service* must be included when you want to issue the token for accessing *good-service*.
|
||||
+
|
||||
See:
|
||||
+
|
||||
** link:{adapterguide_link}#_javascript_adapter[javascript adapter section] if your application uses the javascript adapter.
|
||||
** *Keycloak JavaScript adapter* in the link:{securing_apps_link}[securing apps] section if your application uses the javascript adapter.
|
||||
|
||||
NOTE: Both the _Audience_ and _Audience Resolve_ protocol mappers add the audiences to the access token only, by default. The ID Token typically contains only a single audience, the client ID for which the token was issued, a requirement of the OpenID Connect specification. However, the access token does not necessarily have the client ID, which was the token issued for, unless the audience mappers added it.
|
||||
|
|
|
|||
|
|
@ -5,8 +5,8 @@ The *Mappers* tab contains the protocol mappers and the *Scope* tab contains the
|
|||
|
||||
.Procedure
|
||||
. Click the *Client Scopes* tab for the client.
|
||||
. Open the sub-tab *Evaluate*.
|
||||
. Select the optional client scopes that you want to apply.
|
||||
. Open the sub-tab *Evaluate*.
|
||||
. Select the optional client scopes that you want to apply.
|
||||
|
||||
This will also show you the value of the *scope* parameter. This parameter needs to be sent from the application to the {project_name} OpenID Connect authorization endpoint.
|
||||
|
||||
|
|
@ -15,7 +15,7 @@ image:images/client-scopes-evaluate.png[]
|
|||
|
||||
[NOTE]
|
||||
====
|
||||
To send a custom value for a *scope* parameter from your application, see the link:{adapterguide_link_latest}#_javascript_adapter[javascript adapter section], for javascript adapters.
|
||||
To send a custom value for a *scope* parameter from your application, see the *Keycloak JavaScript adapter* in the link:{securing_apps_link}[securing apps] section, for javascript adapters.
|
||||
====
|
||||
|
||||
All examples are generated for the particular user and issued for the particular client, with the specified value of the *scope* parameter. The examples include all of the claims and role mappings used.
|
||||
All examples are generated for the particular user and issued for the particular client, with the specified value of the *scope* parameter. The examples include all of the claims and role mappings used.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ to exchange the code for an _identity_ and _access_ and _refresh_ token. To pre
|
|||
|
||||
[NOTE]
|
||||
====
|
||||
A system is vulnerable to a stolen token for the lifetime of that token. For security and scalability reasons, access tokens are generally set to expire quickly so subsequent token requests fail. If a token expires, an application can obtain a new access token using the additional _refresh_ token sent by the login protocol.
|
||||
A system is vulnerable to a stolen token for the lifetime of that token. For security and scalability reasons, access tokens are generally set to expire quickly so subsequent token requests fail. If a token expires, an application can obtain a new access token using the additional _refresh_ token sent by the login protocol.
|
||||
====
|
||||
|
||||
[[_confidential-clients]]
|
||||
|
|
@ -33,13 +33,13 @@ _Public_ clients are secure when HTTPS is strictly enforced and redirect URIs re
|
|||
|
||||
===== Implicit Flow
|
||||
|
||||
The Implicit Flow is a browser-based protocol. It is similar to the Authorization Code Flow but with fewer requests and no refresh tokens.
|
||||
The Implicit Flow is a browser-based protocol. It is similar to the Authorization Code Flow but with fewer requests and no refresh tokens.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The possibility exists of _access_ tokens leaking in the browser history when tokens are transmitted via redirect URIs (see below).
|
||||
|
||||
Also, this flow does not provide clients with refresh tokens. Therefore, access tokens have to be long-lived or users have to re-authenticate when they expire.
|
||||
Also, this flow does not provide clients with refresh tokens. Therefore, access tokens have to be long-lived or users have to re-authenticate when they expire.
|
||||
|
||||
We do not advise using this flow. This flow is supported because it is in the OIDC and OAuth 2.0 specification.
|
||||
====
|
||||
|
|
@ -89,7 +89,7 @@ It is possible to specify that the refresh token is considered invalid once it i
|
|||
which were already used, would not be considered valid anymore by {project_name}. This is possible to set with the use of _Revoke Refresh token_ option as specified in the <<_timeouts,timeouts section>>.
|
||||
|
||||
{project_name} also supports the situation that no refresh token rotation exists. In this case, a refresh token is returned during login, but subsequent responses from refresh-token requests will not
|
||||
return new refresh tokens. This practice is recommended for instance in the link:{adapterguide_link}#_fapi-support[FAPI 2 draft specification].
|
||||
return new refresh tokens. This practice is recommended for instance in the *FAPI 2 draft specification* in the link:{securing_apps_link}[securing apps] section.
|
||||
In {project_name}, it is possible to skip refresh token rotation with the use of <<_client_policies,client policies>>. You can add executor `suppress-refresh-token-rotation` to some client
|
||||
profile and configure client policy to specify for which clients would be the profile triggered, which means that for those clients the refresh token rotation is going to be skipped.
|
||||
|
||||
|
|
@ -107,11 +107,11 @@ This is used by clients running on internet-connected devices that have limited
|
|||
This feature is used by clients who want to initiate the authentication flow by communicating with the OpenID Provider directly without redirect through the user's browser like OAuth 2.0's authorization code grant. Here's a brief summary of the protocol:
|
||||
|
||||
. The client requests {project_name} an auth_req_id that identifies the authentication request made by the client. {project_name} creates the auth_req_id.
|
||||
. After receiving this auth_req_id, this client repeatedly needs to poll {project_name} to obtain an Access Token, Refresh Token and ID Token from {project_name} in return for the auth_req_id until the user is authenticated.
|
||||
. After receiving this auth_req_id, this client repeatedly needs to poll {project_name} to obtain an Access Token, Refresh Token and ID Token from {project_name} in return for the auth_req_id until the user is authenticated.
|
||||
|
||||
An administrator can configure Client Initiated Backchannel Authentication (CIBA) related operations as `CIBA Policy` per realm.
|
||||
|
||||
Also please refer to other places of {project_name} documentation like link:{adapterguide_link}#_backchannel_authentication_endpoint[Backchannel Authentication Endpoint section] of {adapterguide_name} and link:{adapterguide_link}#_client_initiated_backchannel_authentication_grant[Client Initiated Backchannel Authentication Grant section] of {adapterguide_name}.
|
||||
Also please refer to other places of {project_name} documentation like *Backchannel Authentication Endpoint* and *Client Initiated Backchannel Authentication Grant* in the link:{securing_apps_link}[securing apps] section.
|
||||
|
||||
====== CIBA Policy
|
||||
|
||||
|
|
@ -177,10 +177,10 @@ Authentication Channel Provider is provided as SPI provider so that users of {pr
|
|||
|
||||
If a user of {project_name} user want to use the HTTP Authentication Channel Provider, they need to know its contract between {project_name} and the authentication entity consisting of the following two parts.
|
||||
|
||||
Authentication Delegation Request/Response::
|
||||
Authentication Delegation Request/Response::
|
||||
{project_name} sends an authentication request to the authentication entity.
|
||||
|
||||
Authentication Result Notification/ACK::
|
||||
Authentication Result Notification/ACK::
|
||||
The authentication entity notifies the result of the authentication to {project_name}.
|
||||
|
||||
Authentication Delegation Request/Response consists of the following messaging.
|
||||
|
|
|
|||
|
|
@ -109,11 +109,11 @@ This is used by clients running on internet-connected devices that have limited
|
|||
This is used by clients who want to initiate the authentication flow by communicating with the OpenID Provider directly without redirect through the user's browser like OAuth 2.0's authorization code grant. Here's a brief summary of the protocol:
|
||||
|
||||
. The client requests {project_name} an auth_req_id that identifies the authentication request made by the client. {project_name} creates the auth_req_id.
|
||||
. After receiving this auth_req_id, this client repeatedly needs to poll {project_name} to obtain an Access Token, Refresh Token and ID Token from {project_name} in return for the auth_req_id until the user is authenticated.
|
||||
. After receiving this auth_req_id, this client repeatedly needs to poll {project_name} to obtain an Access Token, Refresh Token and ID Token from {project_name} in return for the auth_req_id until the user is authenticated.
|
||||
|
||||
An administrator can configure Client Initiated Backchannel Authentication (CIBA) related operations as `CIBA Policy` per realm.
|
||||
|
||||
Also please refer to other places of {project_name} documentation like link:{adapterguide_link}#_backchannel_authentication_endpoint[Backchannel Authentication Endpoint section] of {adapterguide_name} and link:{adapterguide_link}#_client_initiated_backchannel_authentication_grant[Client Initiated Backchannel Authentication Grant section] of {adapterguide_name}.
|
||||
Also please refer to other places of {project_name} documentation like *Backchannel Authentication Endpoint* and *Client Initiated Backchannel Authentication Grant* in the link:{securing_apps_link}[securing apps] section.
|
||||
|
||||
====== CIBA Policy
|
||||
|
||||
|
|
@ -180,10 +180,10 @@ Authentication Channel Provider is provided as SPI provider so that users of {pr
|
|||
|
||||
If a user of {project_name} user want to use the HTTP Authentication Channel Provider, they need to know its contract between {project_name} and the authentication entity consisting of the following two parts.
|
||||
|
||||
Authentication Delegation Request/Response::
|
||||
Authentication Delegation Request/Response::
|
||||
{project_name} sends an authentication request to the authentication entity.
|
||||
|
||||
Authentication Result Notification/ACK::
|
||||
Authentication Result Notification/ACK::
|
||||
The authentication entity notifies the result of the authentication to {project_name}.
|
||||
|
||||
Authentication Delegation Request/Response consists of the following messaging.
|
||||
|
|
|
|||
|
|
@ -2,6 +2,6 @@
|
|||
=== FAPI compliance
|
||||
|
||||
To make sure that {project_name} server will validate your client to be more secure and FAPI compliant, you can configure client policies
|
||||
for the FAPI support. Details are described in the FAPI section of link:{adapterguide_link}#_fapi-support[{adapterguide_name}]. Among other things, this ensures some security best practices
|
||||
for the FAPI support. *FAPI* details are described in the link:{securing_apps_link}[securing apps] section. Among other things, this ensures some security best practices
|
||||
described above like SSL required for clients, secure redirect URI used and more of similar best practices.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,4 +2,4 @@
|
|||
=== OAuth 2.1 compliance
|
||||
|
||||
To make sure that {project_name} server will validate your client to be more secure and OAuth 2.1 compliant, you can configure client policies
|
||||
for the OAuth 2.1 support. Details are described in the OAuth 2.1 section of link:{adapterguide_link}#_oauth21-support[{adapterguide_name}].
|
||||
for the OAuth 2.1 support. *OAuth 2.1* details are described in the link:{securing_apps_link}[securing apps] section.
|
||||
|
|
|
|||
|
|
@ -125,3 +125,4 @@
|
|||
|
||||
:section: guide
|
||||
:sections: guides
|
||||
:securing_apps_link: https://www.keycloak.org/guides#securing-apps
|
||||
|
|
|
|||
|
|
@ -1,5 +1,13 @@
|
|||
:project_name: Keycloak
|
||||
:project_images: keycloak-images
|
||||
:project_doc_base_url: https://www.keycloak.org/docs/latest
|
||||
:project_doc_base_url_latest: https://www.keycloak.org/docs/{version}
|
||||
:project_dirref: KEYCLOAK_HOME
|
||||
:project_openshift_product_name: Keycloak for OpenShift
|
||||
:archivebasename: keycloak
|
||||
:authorizationguide_name: Authorization Services Guide
|
||||
:authorizationguide_name_short: Authorization Services
|
||||
:authorizationguide_link: {project_doc_base_url}/authorization_services/
|
||||
:section: guide
|
||||
:sections: guides
|
||||
:archivedownloadurl: https://github.com/keycloak/keycloak/releases/download/{version}/keycloak-{version}.zip
|
||||
|
|
@ -10,3 +18,10 @@
|
|||
:project_product: false
|
||||
:project_community: true
|
||||
:apidocs_adminrest_link: https://www.keycloak.org/docs-api/{version}/rest-api/
|
||||
:adminguide_name: Server Administration Guide
|
||||
:adminguide_name_short: Server Administration
|
||||
:adminguide_link: {project_doc_base_url}/server_admin/
|
||||
:quickstartRepo_link: https://github.com/keycloak/keycloak-quickstarts
|
||||
:quickstartRepo_name: Keycloak Quickstarts Repository
|
||||
:quickstartRepo_dir: keycloak-quickstarts
|
||||
:securing_apps_link: https://www.keycloak.org/guides#securing-apps
|
||||
|
|
|
|||
21
docs/guides/securing-apps/oidc-layers.adoc
Normal file
21
docs/guides/securing-apps/oidc-layers.adoc
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
<#import "/templates/guide.adoc" as tmpl>
|
||||
<#import "/templates/links.adoc" as links>
|
||||
|
||||
<@tmpl.guide
|
||||
title="Secure applications and services with OpenID Connect"
|
||||
priority=10
|
||||
summary="Using OpenID Connect with Keycloak to secure applications and services">
|
||||
|
||||
include::partials/oidc/available-endpoints.adoc[]
|
||||
|
||||
include::partials/oidc/supported-grant-types.adoc[]
|
||||
|
||||
include::partials/oidc/oidc-errors.adoc[]
|
||||
|
||||
include::partials/oidc/fapi-support.adoc[]
|
||||
|
||||
include::partials/oidc/oauth21-support.adoc[]
|
||||
|
||||
include::partials/oidc/recommendations.adoc[]
|
||||
|
||||
</@tmpl.guide>
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
=== Available Endpoints
|
||||
== Available Endpoints
|
||||
|
||||
As a fully-compliant OpenID Connect Provider implementation, {project_name} exposes a set of endpoints that applications
|
||||
and services can use to authenticate and authorize their users.
|
||||
|
|
@ -6,7 +6,7 @@ and services can use to authenticate and authorize their users.
|
|||
This section describes some of the key endpoints that your application and service should use when
|
||||
interacting with {project_name}.
|
||||
|
||||
==== Endpoints
|
||||
=== Endpoints
|
||||
|
||||
The most important endpoint to understand is the `well-known` configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID Connect implementation in {project_name}. The endpoint is:
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ To obtain the full URL, add the base URL for {project_name} and replace `{realm-
|
|||
|
||||
Some RP libraries retrieve all required endpoints from this endpoint, but for others you might need to list the endpoints individually.
|
||||
|
||||
===== Authorization endpoint
|
||||
==== Authorization endpoint
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/auth
|
||||
....
|
||||
|
|
@ -29,7 +29,7 @@ The authorization endpoint performs authentication of the end-user. This authent
|
|||
|
||||
For more details see the https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] section in the OpenID Connect specification.
|
||||
|
||||
===== Token endpoint
|
||||
==== Token endpoint
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/token
|
||||
....
|
||||
|
|
@ -39,7 +39,7 @@ The token endpoint is also used to obtain new access tokens when they expire.
|
|||
|
||||
For more details, see the https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] section in the OpenID Connect specification.
|
||||
|
||||
===== Userinfo endpoint
|
||||
==== Userinfo endpoint
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/userinfo
|
||||
....
|
||||
|
|
@ -48,7 +48,7 @@ The userinfo endpoint returns standard claims about the authenticated user; this
|
|||
|
||||
For more details, see the https://openid.net/specs/openid-connect-core-1_0.html#UserInfo[Userinfo Endpoint] section in the OpenID Connect specification.
|
||||
|
||||
===== Logout endpoint
|
||||
==== Logout endpoint
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/logout
|
||||
....
|
||||
|
|
@ -60,7 +60,7 @@ The user agent can be redirected to the endpoint, which causes the active user s
|
|||
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 the credentials required to authenticate the client.
|
||||
|
||||
[[_certificate_endpoint]]
|
||||
===== Certificate endpoint
|
||||
==== Certificate endpoint
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/certs
|
||||
....
|
||||
|
|
@ -68,7 +68,7 @@ The endpoint can also be invoked directly by the application. To invoke this end
|
|||
The certificate endpoint returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK). Depending on the realm settings, one or more keys can be 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]]
|
||||
===== Introspection endpoint
|
||||
==== Introspection endpoint
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/token/introspect
|
||||
....
|
||||
|
|
@ -78,13 +78,13 @@ This endpoint can only be invoked by confidential clients.
|
|||
|
||||
For more details on how to invoke on this endpoint, see https://datatracker.ietf.org/doc/html/rfc7662[OAuth 2.0 Token Introspection specification].
|
||||
|
||||
====== Introspection endpoint triggered with application/jwt header
|
||||
===== Introspection endpoint triggered with application/jwt header
|
||||
|
||||
You can invoke an introspection endpoint with the HTTP header `Accept: application/jwt` instead of `Accept: application/json`. In case of `application/jwt`, the response
|
||||
may contain the additional claim `jwt` with the full JWT access token, which can be useful especially if the token to be introspected was a link:{adminguide_link}#_using_lightweight_access_token[lightweight access token]. This requires that you enable `Support JWT claim in Introspection Response`
|
||||
on the client advanced settings, which triggers the token introspection.
|
||||
|
||||
===== Dynamic Client Registration endpoint
|
||||
==== Dynamic Client Registration endpoint
|
||||
....
|
||||
/realms/{realm-name}/clients-registrations/openid-connect
|
||||
....
|
||||
|
|
@ -95,7 +95,7 @@ For more details, see the <<_client_registration,Client Registration chapter>> a
|
|||
https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration specification].
|
||||
|
||||
[[_token_revocation_endpoint]]
|
||||
===== Token Revocation endpoint
|
||||
==== Token Revocation endpoint
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/revoke
|
||||
....
|
||||
|
|
@ -104,7 +104,7 @@ The token revocation endpoint is used to revoke tokens. Both refresh tokens and
|
|||
|
||||
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
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/auth/device
|
||||
....
|
||||
|
|
@ -114,7 +114,7 @@ The device authorization endpoint is used to obtain a device code and a user cod
|
|||
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
|
||||
....
|
||||
/realms/{realm-name}/protocol/openid-connect/ext/ciba/auth
|
||||
....
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
[[_fapi-support]]
|
||||
=== Financial-grade API (FAPI) Support
|
||||
== Financial-grade API (FAPI) Support
|
||||
|
||||
{project_name} makes it easier for administrators to make sure that their clients are compliant with these specifications:
|
||||
|
||||
|
|
@ -13,7 +13,7 @@ This compliance means that the {project_name} server will verify the requirement
|
|||
for the authorization server, which are mentioned in the specifications. {project_name} adapters do not have any specific support for the FAPI, hence the required validations on the client (application)
|
||||
side may need to be still done manually or through some other third-party solutions.
|
||||
|
||||
==== FAPI client profiles
|
||||
=== FAPI client profiles
|
||||
|
||||
To make sure that your clients are FAPI compliant, you can configure Client Policies in your realm as described in the link:{adminguide_link}#_client_policies[{adminguide_name}]
|
||||
and link them to the global client profiles for FAPI support, which are automatically available in each realm. You can use either `fapi-1-baseline` or `fapi-1-advanced` profile based on which FAPI
|
||||
|
|
@ -27,7 +27,7 @@ In case you want to use <<_backchannel_authentication_endpoint,CIBA>> in a FAPI
|
|||
There is a need to use the `fapi-1-advanced` profile, or other client profile containing the requested executors, as the `fapi-ciba` profile contains just CIBA-specific executors.
|
||||
When enforcing the requirements of the FAPI CIBA specification, there is a need for more requirements, such as enforcement of confidential clients or certificate-bound access tokens.
|
||||
|
||||
==== Open Finance Brasil Financial-grade API Security Profile
|
||||
=== Open Finance Brasil Financial-grade API Security Profile
|
||||
|
||||
{project_name} is compliant with the https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/245760001/EN+Open+Finance+Brasil+Financial-grade+API+Security+Profile+1.0+Implementers+Draft+3[Open Finance Brasil Financial-grade API Security Profile 1.0 Implementers Draft 3].
|
||||
This one is stricter in some requirements than the <<_fapi-support,FAPI 1 Advanced>> specification and hence it may be needed to configure link:{adminguide_link}#_client_policies[Client Policies]
|
||||
|
|
@ -36,13 +36,13 @@ in the more strict way to enforce some of the requirements. Especially:
|
|||
* If your client does not use PAR, make sure that it uses encrypted OIDC request objects. This can be achieved by using a client profile with the `secure-request-object` executor configured with `Encryption Required` enabled.
|
||||
* Make sure that for JWS, the client uses the `PS256` algorithm. For JWE, the client should use the `RSA-OAEP` with `A256GCM`. This may need to be set in all the link:{adminguide_link}#_oidc_clients[Client Settings] where these algorithms are applicable.
|
||||
|
||||
==== Australia Consumer Data Right (CDR) Security Profile
|
||||
=== Australia Consumer Data Right (CDR) Security Profile
|
||||
|
||||
{project_name} is compliant with the https://consumerdatastandardsaustralia.github.io/standards/#security-profile[Australia Consumer Data Right Security Profile].
|
||||
|
||||
If you want to apply the Australia CDR security profile, you need to use `fapi-1-advanced` profile because the Australia CDR security profile is based on FAPI 1.0 Advanced security profile. If your client also applies PAR, make sure that client applies RFC 7637 Proof Key for Code Exchange (PKCE) because the Australia CDR security profile requires that you apply PKCE when applying PAR. This can be achieved by using a client profile with the `pkce-enforcer` executor.
|
||||
|
||||
==== TLS considerations
|
||||
=== TLS considerations
|
||||
|
||||
As confidential information is being exchanged, all interactions shall be encrypted with TLS (HTTPS). Moreover, there are some requirements in the FAPI specification for
|
||||
the cipher suites and TLS protocol versions used. To match these requirements, you can consider configure allowed ciphers. This configuration can be done by setting
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
[[_oauth21-support]]
|
||||
=== OAuth 2.1 Support
|
||||
== OAuth 2.1 Support
|
||||
|
||||
{project_name} makes it easier for administrators to make sure that their clients are compliant with these specifications:
|
||||
|
||||
|
|
@ -9,11 +9,11 @@ This compliance means that the {project_name} server will verify the requirement
|
|||
for the authorization server, which are mentioned in the specifications. {project_name} adapters do not have any specific support for the OAuth 2.1, hence the required validations on the client (application)
|
||||
side may need to be still done manually or through some other third-party solutions.
|
||||
|
||||
==== OAuth 2.1 client profiles
|
||||
=== OAuth 2.1 client profiles
|
||||
|
||||
To make sure that your clients are OAuth 2.1 compliant, you can configure Client Policies in your realm as described in the link:{adminguide_link}#_client_policies[{adminguide_name}]
|
||||
and link them to the global client profiles for OAuth 2.1 support, which are automatically available in each realm. You can use either `oauth-2-1-for-confidential-client` profile for confidential clients or `oauth-2-1-for-public-client` profile for public clients.
|
||||
|
||||
NOTE: OAuth 2.1 specification is still a draft and it may change in the future. Hence the {project_name} built-in OAuth 2.1 client profiles can change as well.
|
||||
|
||||
NOTE: When using OAuth 2.1 profile for public clients, it is recommended to use DPoP preview feature as described in the link:{adminguide_link}#_dpop-bound-tokens[{adminguide_name}] because DPoP binds an access token and a refresh token together with the public part of a client's key pair. This binding prevents an attacker from using stolen tokens.
|
||||
NOTE: When using OAuth 2.1 profile for public clients, it is recommended to use DPoP preview feature as described in the link:{adminguide_link}#_dpop-bound-tokens[{adminguide_name}] because DPoP binds an access token and a refresh token together with the public part of a client's key pair. This binding prevents an attacker from using stolen tokens.
|
||||
|
|
@ -1,9 +1,9 @@
|
|||
|
||||
[[_oidc-errors]]
|
||||
=== {project_name} specific errors
|
||||
== {project_name} specific errors
|
||||
|
||||
{project_name} server can send errors to the client application in the OIDC authentication response with parameters `error=temporarily_unavailable` and `error_description=authentication_expired`.
|
||||
{project_name} sends this error when a user is authenticated and has an SSO session, but the authentication session expired in the current browser tab and hence the {project_name} server cannot automatically do SSO
|
||||
re-authentication of the user and redirect back to client with a successful response. When a client application receives this type of error, it is ideal to retry authentication immediately and send a new
|
||||
OIDC authentication request to the {project_name} server, which should typically always authenticate the user due to the SSO session and redirect back. For more details, see
|
||||
OIDC authentication request to the {project_name} server, which should typically always authenticate the user due to the SSO session and redirect back. For more details, see
|
||||
the link:{adminguide_link}#_authentication-sessions[{adminguide_name}].
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
=== Recommendations
|
||||
== Recommendations
|
||||
|
||||
This section describes some recommendations when securing your applications with {project_name}.
|
||||
|
||||
==== Validating access tokens
|
||||
=== Validating access tokens
|
||||
|
||||
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
|
||||
|
|
@ -11,7 +11,7 @@ Because they are encoded in this way, you can locally validate access tokens usi
|
|||
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 on what language you code in, many third party libraries exist and they can help you with JWS validation.
|
||||
|
||||
==== Redirect URIs
|
||||
=== Redirect URIs
|
||||
|
||||
When using the redirect based flows, be sure 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:
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
=== Supported Grant Types
|
||||
== Supported Grant Types
|
||||
|
||||
This section describes the different grant types available to relaying parties.
|
||||
|
||||
==== Authorization code
|
||||
=== Authorization code
|
||||
|
||||
The Authorization Code flow redirects the user agent to {project_name}. Once the user has successfully authenticated with {project_name}, an
|
||||
Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code along with its
|
||||
|
|
@ -13,11 +13,11 @@ a user agent.
|
|||
|
||||
For more details refer to the https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow] in the OpenID Connect specification.
|
||||
|
||||
==== Implicit
|
||||
=== Implicit
|
||||
|
||||
The Implicit flow works similarly to the Authorization Code flow, but instead of returning an Authorization Code, the Access Token and ID Token is
|
||||
returned. This approach 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 permit Access Tokens with a long expiration; however, that approach is not practical because it is very hard to invalidate these tokens. Alternatively, you can
|
||||
Token. This results in the need to permit Access Tokens with a long expiration; however, that approach is not practical because it is very hard to invalidate these tokens. Alternatively, you can
|
||||
require a new redirect to obtain a 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.
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ Per current https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topi
|
|||
This flow is removed from the future https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09[OAuth 2.1 specification].
|
||||
|
||||
[[_resource_owner_password_credentials_flow]]
|
||||
==== Resource Owner Password Credentials
|
||||
=== Resource Owner Password Credentials
|
||||
|
||||
Resource Owner Password Credentials, referred to as Direct Grant in {project_name}, allows exchanging user credentials for tokens.
|
||||
Per current https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#name-resource-owner-password-cre[OAuth 2.0 Security Best Practices],
|
||||
|
|
@ -60,7 +60,7 @@ It is removed from the future https://datatracker.ietf.org/doc/html/draft-ietf-o
|
|||
|
||||
For more details, see 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
|
||||
|
||||
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`:
|
||||
|
|
@ -76,7 +76,7 @@ curl \
|
|||
"http://localhost:8080{kc_realms_path}/master/protocol/openid-connect/token"
|
||||
----
|
||||
|
||||
==== Client credentials
|
||||
=== Client credentials
|
||||
|
||||
Client Credentials are used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user. For example, these credentials can
|
||||
be useful for background services that apply changes to the system in general rather than for a specific user.
|
||||
|
|
@ -87,7 +87,7 @@ This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 spec
|
|||
|
||||
For more details, see 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
|
||||
|
||||
Device Authorization Grant is used by clients running on internet-connected devices that have limited input capabilities or lack a suitable browser.
|
||||
|
||||
|
|
@ -102,7 +102,7 @@ Device Authorization Grant is used by clients running on internet-connected devi
|
|||
For more details, see 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 is used by clients who want to initiate the authentication flow by communicating with the OpenID Provider directly without redirect through the user's browser like OAuth 2.0's authorization code grant.
|
||||
|
||||
Loading…
Reference in a new issue