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].
|
||||
====
|
||||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ 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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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+"]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -113,6 +113,6 @@ See <<_client_scopes_linking, Client Scopes Linking section>> for more details.
|
|||
+
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -111,7 +111,7 @@ This feature is used by clients who want to initiate the authentication flow by
|
|||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -113,7 +113,7 @@ This is used by clients who want to initiate the authentication flow by communic
|
|||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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,7 +9,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 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.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_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
|
||||
|
|
@ -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,7 +13,7 @@ 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
|
||||
|
|
@ -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