Documentation for RP-Initiated Logout refactoring (#1443)
* Documentation for RP-Initiated Logout refactoring Closes #1442 * Added warning about backwards compatibility switch removal in the future
This commit is contained in:
Marek Posolda
GitHub
parent
36368d40c9
commit
044945bed4
4 changed files with 80 additions and 9 deletions
|
|
@ -4,18 +4,29 @@
|
|||
|
||||
Recovery Codes as another way to do two-factor authentication is now available as a preview feature.
|
||||
|
||||
== OpenID Connect Logout Improvements
|
||||
|
||||
Some fixes and improvements were made to make sure that {project_name} is now fully compliant with all the OpenID Connect logout specifications:
|
||||
|
||||
* OpenID Connect RP-Initiated Logout 1.0
|
||||
* OpenID Connect Front-Channel Logout 1.0
|
||||
* OpenID Connect Back-Channel Logout 1.0
|
||||
* OpenID Connect Session Management 1.0
|
||||
|
||||
For more details, see link:{adminguide_link}#_oidc-logout[{adminguide_name}].
|
||||
|
||||
== Step-up authentication
|
||||
|
||||
{project_name} now supports Step-up authentication. This feature was added in Keycloak 17 and it was further polished in this version.
|
||||
|
||||
For more details, take a look at link:{adminguide_link}#_step-up-flow[{adminguide_name}].
|
||||
For more details, see link:{adminguide_link}#_step-up-flow[{adminguide_name}].
|
||||
|
||||
Thanks to https://github.com/CorneliaLahnsteiner[Cornelia Lahnsteiner] and https://github.com/romge[Georg Romstorfer] for the contribution.
|
||||
|
||||
== WebAuthn improvements
|
||||
|
||||
{project_name} now supports WebAuthn id-less authentication. This feature allows that WebAuthn Security Key will identify the user during authentication as long as the
|
||||
security key supports Resident Keys. For more details, take a look at link:{adminguide_link}#_webauthn_loginless[{adminguide_name}].
|
||||
security key supports Resident Keys. For more details, see link:{adminguide_link}#_webauthn_loginless[{adminguide_name}].
|
||||
Thanks to https://github.com/vanrar68[Joaquim Fellmann] for the contribution.
|
||||
|
||||
There are more WebAuthn improvements and fixes in addition to that.
|
||||
|
|
|
|||
|
|
@ -3,12 +3,17 @@
|
|||
[[_java_adapter_logout]]
|
||||
You can log out of a web application in multiple ways.
|
||||
For Jakarta EE servlet containers, you can call `HttpServletRequest.logout()`. For other browser applications, you can redirect the browser to
|
||||
`\http://auth-server{kc_realms_path}/{realm-name}/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri`, which logs you out if you have an SSO session with your browser.
|
||||
`\http://auth-server{kc_realms_path}/{realm-name}/protocol/openid-connect/logout`, which logs the user out if that user has an SSO session with his browser. The actual logout is done once
|
||||
the user confirms the logout. You can optionally include parameters such as `id_token_hint`, `post_logout_redirect_uri` and others as described in the
|
||||
https://openid.net/specs/openid-connect-rpinitiated-1_0.html[OpenID Connect RP-Initiated Logout]. As a result, that logout does not need to be explicitly confirmed
|
||||
by the user.
|
||||
|
||||
If you want to avoid logging out of an external identity provider as part of the logout process, you can supply the parameter `$$initiating_idp$$`, with the value being
|
||||
the identity (alias) of the identity provider in question. This parameter is useful when the logout endpoint is invoked as part of single logout initiated by the external identity provider.
|
||||
The parameter `initiating_idp` is the supported parameter of the {project_name} logout endpoint in addition to the parameters described in the RP-Initiated Logout specification.
|
||||
|
||||
When using the `HttpServletRequest.logout()` option the adapter executes a back-channel POST call against the {project_name} server passing the refresh token.
|
||||
If the method is executed from an unprotected page (a page that does not check for a valid token) the refresh token can be unavailable and, in that case,
|
||||
the adapter skips the call. For this reason, using a protected page to execute `HttpServletRequest.logout()` is recommended so that current tokens are always
|
||||
taken into account and an interaction with the {project_name} server is performed if needed.
|
||||
|
||||
If you want to avoid logging out of an external identity provider as part of the logout process, you can supply the parameter `$$initiating_idp$$`, with the value being
|
||||
the identity (alias) of the identity provider in question. This is useful when the logout endpoint is invoked as part of single logout initiated by the external identity provider.
|
||||
|
|
|
|||
|
|
@ -312,9 +312,10 @@ User Resolver Provider is provided as SPI provider so that users of {project_nam
|
|||
|
||||
==== OIDC Logout
|
||||
|
||||
OIDC has three different specifications relevant to logout mechanisms, all of these are currently in draft status:
|
||||
OIDC has four specifications relevant to logout mechanisms. These specifications are in draft status:
|
||||
|
||||
. https://openid.net/specs/openid-connect-session-1_0.html[Session Management]
|
||||
. https://openid.net/specs/openid-connect-rpinitiated-1_0.html[RP-Initiated Logout]
|
||||
. https://openid.net/specs/openid-connect-frontchannel-1_0.html[Front-Channel Logout]
|
||||
. https://openid.net/specs/openid-connect-backchannel-1_0.html[Back-Channel Logout]
|
||||
|
||||
|
|
@ -325,15 +326,21 @@ Again since all of this is described in the OIDC specification we will only give
|
|||
This is a browser-based logout. The application obtains session status information from {project_name} at a regular basis.
|
||||
When the session is terminated at {project_name} the application will notice and trigger it's own logout.
|
||||
|
||||
===== Frontchannel Logout
|
||||
===== RP-Initiated Logout
|
||||
|
||||
This is also a browser-based logout where the logout starts by redirecting the user to a specific endpoint at {project_name}.
|
||||
This redirect usually happens when the user clicks the `Log Out` link on the page of some application, which previously used {project_name} to authenticate the user.
|
||||
|
||||
Once the user is redirected to the logout endpoint, {project_name} is going to send logout requests to
|
||||
clients to let them to invalidate their local user sessions, and potentially redirect the user to some URL
|
||||
once the logout process is finished.
|
||||
once the logout process is finished. The user might be optionally requested to confirm the logout in case that `id_token_hint` parameter was not used
|
||||
or the client referenced in the ID Token from `id_token_hint` has `Consent Required` enabled.
|
||||
|
||||
Depending on the client configuration, logout requests can be sent to clients through the front-channel or through the back-channel.
|
||||
Depending on the client configuration, logout requests can be sent to clients through the front-channel or through the back-channel. For the frontend browser clients, which rely on the
|
||||
Session Management described in the previous section, {project_name} does not need to send any logout requests to them; these clients automatically detect that SSO session
|
||||
in the browser is logged out.
|
||||
|
||||
===== Frontchannel Logout
|
||||
|
||||
To configure clients to receive logout requests through the front-channel, look at the <<_front-channel-logout, Front-Channel Logout>> client setting. When using this method, consider the following:
|
||||
|
||||
|
|
|
|||
|
|
@ -18,3 +18,51 @@ the migration. Consider these possible actions:
|
|||
insert into CLIENT_SCOPE_CLIENT (CLIENT_ID, SCOPE_ID, DEFAULT_SCOPE) select CLIENT.ID as CLIENT_ID, CLIENT_SCOPE.ID as SCOPE_ID, true as DEFAULT_SCOPE
|
||||
from CLIENT_SCOPE, CLIENT where CLIENT_SCOPE.REALM_ID='test' and CLIENT_SCOPE.NAME='acr' and CLIENT.REALM_ID='test' and CLIENT.PROTOCOL='openid-connect';
|
||||
```
|
||||
|
||||
= OpenID Connect Logout
|
||||
|
||||
Previous versions of {project_name} had supported automatic logout of the user and redirecting to the application by opening logout endpoint URL such as
|
||||
`http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri`. While that implementation was easy to use, it had potentially negative impact
|
||||
on performance and security. The new version has better support for logout based on the OpenID Connect RP-Initiated Logout specification. The parameter `redirect_uri` is no longer supported; also,
|
||||
in the new version, the user needs to confirm the logout. It is possible to omit the confirmation and do automatic redirect to the application when you include parameter `post_logout_redirect_uri`
|
||||
together with the parameter `id_token_hint` with the ID Token used for login.
|
||||
|
||||
The existing deployments are affected in the following ways:
|
||||
|
||||
- If your application directly uses links to logout endpoint with the `redirect_uri` parameter, you may be required to change this as described above.
|
||||
Consider either removing the `redirect_uri` parameter entirely or replacing it with the `id_token_hint` and `post_logout_redirect_uri` parameters.
|
||||
- If you use java adapters and your application does logout by call `httpServletRequest.logout()`, you are not affected because this call uses the backchannel variant of the logout endpoint
|
||||
and that one was not changed.
|
||||
- If you use the latest javascript adapter, you are also not affected. However if your application uses an older version of the JavaScript adapter, you are affected as this
|
||||
adapter uses the variant of the logout endpoint with the deprecated `redirect_uri` parameter. In this case, you may need to upgrade to the latest version of the JavaScript adapter.
|
||||
The same applies for the Node.js adapter.
|
||||
|
||||
There is a backwards compatibility option, which allows your application to still use the old format of the `redirect_uri` parameter.
|
||||
|
||||
ifeval::["{kc_dist}" == "quarkus"]
|
||||
You can enable this parameter when you start the server by entering the following command:
|
||||
|
||||
```
|
||||
bin/kc.[sh|bat] --spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true start
|
||||
```
|
||||
endif::[]
|
||||
|
||||
ifeval::["{kc_dist}" == "wildfly"]
|
||||
You can enable this parameter by including the following configuration in the `standalone-*.xml` file
|
||||
|
||||
[source,bash,subs=+attributes]
|
||||
----
|
||||
<spi name="login-protocol">
|
||||
<provider name="openid-connect" enabled="true">
|
||||
<properties>
|
||||
<property name="legacy-logout-redirect-uri" value="true"/>
|
||||
</properties>
|
||||
</provider>
|
||||
</spi>
|
||||
----
|
||||
endif::[]
|
||||
|
||||
With this configuration, you can still use the format with the `redirect_uri` parameter. Note the confirmation screen will be needed if the `id_token_hint` is omitted.
|
||||
|
||||
WARNING: The backwards compatibility switch will be removed in some future version - probably Keycloak 21. You are encouraged to update your clients as soon as possible
|
||||
as described above rather than rely on this switch.
|
||||
|
|
|
|||
Loading…
Reference in a new issue