OIDC RP-initiated Logout with WSO2 Identity Server
The main objective of this blog is to give an overview of OIDC RP-initiated logout and how the WSO2 Identity Server handles it.
What is OpenID Connect (OIDC)?
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server.
Why Relying Party should find the login status of a user? What is the need for OIDC Logout?
You can find an id token obtained by a OIDC relying party(RP) below. It has a set of claims.
{
"at_hash": "UOi-eK4G2-noJGCOc6wtgw",
"aud": "wObtoj21fQv3fotQHO7jOpBt7hMa",
"c_hash": "Pm5Fsk9eC9c4OsoEIaAMXg",
"sub": "admin",
"nbf": 1599973744,
"azp": "wObtoj21fQv3fotQHO7jOpBt7hMa",
"amr": [
"BasicAuthenticator"
],
"iss": "https://localhost:9443/oauth2/token",
"exp": 1599977344,
"iat": 1599973744
}idtoken has an exp claim as well. This indicates that the Expiration time on or after which the ID Token MUST NOT be accepted for processing. exp claim denotes when the JWT will expire.
The Relying Party MAY rely on `exp` claim to expire the RP session. But, it is entirely possible that the End-User might have logged out of the OpenID Provider before the expiration date.
Therefore, it is highly desirable to be able to find out the login status of the End-User at the OpenID Provider.
OpenID Connect 1.0 can use front-channel communication or back-channel communication for logout mechanism.
OpenID Connect Logout
OpenID Connect 1.0 can use front-channel communication or back-channel communication for logout mechanism.
- Front-Channel mechanism: Communication of logout request from OpenID provider (OP) to Relying Party (RP) via User Agent (web browser)
- Back-Channel mechanism: Direct communication between OpenID Provider (OP) and Relying Party (RP)
In OpenID Connect, there are 4 specs related to OIDC logout.
- OIDC RP-Initiated Logout: This spec defines how an application should invoke a logout request to an OP.
- OIDC Session Management: OIDC Session Management spec defines how to monitor the End-User’s login status at the OP
- OIDC Front-channel logout: Both the OIDC Session Management specification and the OIDC Front-Channel Logout specification use front-channel communication, which communicates logout requests from the OP to RPs via the User-Agent.
- OIDC Back-channel logout: The OIDC Back-Channel Logout specification uses direct back-channel communication between the OP and RPs being logged out
Simply we can say that RP-initiated logout is the way to invoke OIDC logout at the IDP side by an RP. But OIDC Session Management, OIDC front-channel logout, OIDC back-channel logout are logout notification mechanisms. Once the IDP’s session is terminated by RP-initiated logout, the logout notifications will be sent to all RPs in the same browser session. Those notification mechanisms can vary depends on OIDC Session Management, OIDC front-channel logout, OIDC back-channel logout
OIDC RP-initiated logout
RP-Initiated Logout specs define how an application should invoke a logout request to a OP. RP will invoke the logout endpoint of the OP(OpenID Provider) via the browser agent.
That logout request may contain the following query parameters.
Id_token_hint (RECOMMENDED). ID Token previously issued by the OP to the RP
Post_logout_redirect_uri (OPTIONAL) URL to which the RP is requesting that the End-User’s User Agent be redirected after a logout has been performed. An id_token_hint is also REQUIRED when this parameter is included.
State (OPTIONAL)Opaque value used by the RP to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri parameter. If included in the logout request, the OP passes this value back to the RP using the state parameter when redirecting the User Agent back to the RP.
According to the spec,
- When an OP receives a logout request, it will remove the end user’s session in the OP. This process is called RP-initiated logout.
- When an id_token_hint parameter is present, the OP MUST validate that it was the issuer of the ID Token.
- At the Logout Endpoint, the OP SHOULD ask the End-User whether to log out of the OP as well. If the End-User says “yes”, then the OP MUST log out the End-User.
- As part of the OP logging out the End-User, the OP uses the logout mechanism(s) registered by the RPs to notify any RPs logged in as that End-User that they are to likewise log out the End-User
- Then OP will notify other RPs in the same browser session about this logout event. How IDP does that depend on the logout mechanism (it can be back-channel logout or front-channel logout or session mgt). OP the OP should use the logout mechanism(s) registered by the RPs to notify any RPs logged in as that End-User that they are to likewise log out the End-User
How WSO2 Identity Server supports OIDC RP-initiated logout
Steps:
1. RP has to invoke OIDC logout endpoint
2. WSO2 IS Validates the logout request
3. WSO2 IS Prompts for consent
4. WSO2 IS Terminates the IDP session
5. WSO2 IS Redirects to postlogout_redirect_uri
We will look into those steps in detail.
1. RP has to invoke the OIDC logout endpoint of WSO2 Identity Server.
The logout endpoint of WSO2 Identity server is
https://<IS_SERVER_HOST>:<IS_SERVER_PORT>/oidc/logoutEx:
https://localhost:9443/oidc/logoutBy invoking this above endpoint, a RP can notify the OP to terminate the current session of the end user from the OP.
Sample request from a Relying party
GET https://localhost:9443/oidc/logout?post_logout_redirect_uri=http://localhost.com:8080/pickup-dispatch/oauth2client&id_token_hint=eyJ4NXQiOiJNell4TW1Ga09HWXdNV0kwWldObU5EY3hOR1l3WW1NNFpUQTNNV0kyTkRBelpHUXpOR00wWkdSbE5qSmtPREZrWkRSaU9URmtNV0ZoTXpVMlpHVmxOZyIsImtpZCI6Ik16WXhNbUZrT0dZd01XSTBaV05tTkRjeE5HWXdZbU00WlRBM01XSTJOREF6WkdRek5HTTBaR1JsTmpKa09ERmtaRFJpT1RGa01XRmhNelUyWkdWbE5nX1JTMjU2IiwiYWxnIjoiUlMyNTYifQ.eyJpc2siOiJjNjE2NTQyODZiZDJjMTUzY2Y4NTNkYzY2ZjExZjlmNDU5MmEwOGY0MjlhZWMwMTIyZDE2ZDJhMGQ0ZGUxM2RkIiwiYXRfaGFzaCI6IlJiVTRkLXZ1enY2ekxBdXNMWlU2dmciLCJhdWQiOiI4NUVNUkJqbnRKSHRVcDdsRTlqMjdYR0ZhN0FhIiwiY19oYXNoIjoiTHBHUUVXY0NqMnFtU181dmpiMmpvQSIsInN1YiI6ImFkbWluIiwibmJmIjoxNjIwMTM5MjE1LCJhenAiOiI4NUVNUkJqbnRKSHRVcDdsRTlqMjdYR0ZhN0FhIiwiYW1yIjpbIkJhc2ljQXV0aGVudGljYXRvciJdLCJpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0Ojk0NDNcL29hdXRoMlwvdG9rZW4iLCJleHAiOjE2MjAxNDI4MTUsImlhdCI6MTYyMDEzOTIxNSwic2lkIjoiOTJmOTkwOTYtYmY5Yi00ZTA2LTgxYTctOTYyMjE0M2U4NzdiIn0.nhQ3mN714IRMWcRg3rV3pzURrgDPD3S8Z5QQ4KZ8e_Fwa-59ZsmNbktfKXebMqcbRcdRDAujN7YewjDjbce5olUb_BUuPJ62N3du14OLB2vpNhOAWVQ7nN4qmT1MCLi1i2YzvPjETlC1OuUSe-eVah9ZRwpdbxY37G89OmA421E2Z6j7rC0V_qmTXba-5KtfnkhAUOiwouiMdyKysvq-6PlxBpjgbD2n6aMN2MP-U2X_P4kUkyzQA0Kn-RblKPuNer190Hc2fRLwnohFXwTlpI_YwYe15DosAwqiT96BtNnFqkdq_EOEraobgCSbSrtCE_JxdpD9EJfUMEtCJbdVjA&session_state=8621b67d96bf735119b3dde95587445ca32fb66e4a508f528cfa133750e90b8e.mwbhoO8BGyYo9yU6H3ae2Q&state=statexyzIn the above sample request, The relying party has passed the id_token obtained from the authentication as id_token_hint, post_logout_redirect_uri indicates to which logout endpoint, IDP has to return after successful logout and state is an opaque string that needs to be resent back to the RP.
2. WSO2 Identity Server will validate the logout request.
Once the IS receives the logout request, the Identity Server will validate the id_token_hint and post_logout_redirect_url.
How does validation happen?
- Validation of id_token_hint
client_id is sent as a claim value in id_token by the WSO2 Identity server. Once WSO2 IS receives the logout request with id_token_hint, it will get to know from which RP this logout request is sent by decoding the obtained id_token_hint attached as the query param. Also Identity Server has `opbs ` cookie to track OIDC sessions. RPs in the same sessions will share the same opbs cookie. So from the logout request, WSO2 IS, will know from which RP(from client_id in id_token_hint) and which session (from opbs cookie) this logout request is sent. So IS will find all the RPs in. the same session and sends logout notifications to those RPs.
- Validation of post_logout_redirect_uri
In order to support post_logout_url, an id_token_hint also should be attached. In WSO2 IS, you can register post_logout_url as one of the callback_url.
When post_logout_url and id_token_hint are passed, post_logout_redirect_uri will be validated using the client_id obtained from the id_token_hint. Once the post_logout_url is validated, IDP will redirect to the post_logout_redirect uri after session termination.
WSO2 IS will not perform post-logout redirection if the post_logout_redirect_uri value supplied does not exactly match one of the previously registered callback URL values.
Once the logout request validation is successful, the user will be prompted for logout consent.
3. Prompt for consent page.
When the consent screen is prompted, user has to provide consent to logout the IDP sessionn. (There is an application level configuration to skip the logout consent. If that config is enabled, consent screen will not be prompted). If the user approves the consent, the user’s session at WSO2 IS will be terminated.
If the user denies the logout consent, the user will be redirected to the post_logout_redirect_uri with any session termination at WSO2 IS side.
4. Session termination and send logout notification to RPs.
If the user provides the consent, The Identity Server cleans the user’s SSO session. IS will remove session-related cookies such as commonAuthId and opbs cookie. IS will trigger the SESSION_TERMINATION event to notify the subscribed handlers. If there are any tokens bound to the session, those tokens will be revoked.
Once the session termination is successful at the WSO2 IS side, it will trigger logout notifications to the RPs belong to the same session. Identity Server triggers a logout at other clients using OIDC session management or OIDC back-channel logout or OIDC front-channel logout (single logout). If the RP is using OIDC session management, then RPs will be notified when it invokes the `/check-session` endpoint. Logout token will be sent for the RPs who have registered OIDC Back-channel logout. (WSO2 IS does not support OIDC Front-channel log out until the latest release (IS 5.11.0))
5. Redirect to post_logout_redirect_uri.
There will be a redirection to post_logout_redirect_uri if it is passed as a query param in the logout request along with the state param(if state param is passed in the logout request)
https://localhost:9443/console/login?sp=Console&tenantDomain=carbon.super&state=statexyz
If the post_logout_redirect_uri is not passed in the logout request, then WSO2 Identity Server will return to its default logout page
Endpoint Discovery with WSO2 IS
To support OpenID Connect logout mechanisms, the RP needs to obtain the logout related endpoint URLs. These URLs are normally obtained via the OP’s Discovery response, as described in OpenID Connect Discovery 1.0.
Main endpoint specific for RP-initiated logout is end_session_endpoint.
end_session_endpoint
REQUIRED. URL at the OP to which an RP can perform a redirect to request that the End-User be logged out at the OP.
Discovery endpoint of WSO2 Identity Server-
<issuer_id>.well-known/openid-configurationSample url:
https://localhost:9443/oauth2/token/.well-known/openid-configurationWhen you invoke the Discovery endpoint of IS, you can get the OIDC logogut edpoint of the IS using end_session_endpoint value
“end_session_endpoint”: “https://localhost:9443/oidc/logout"
Encrypted id_token_hint with WSO2 IS
WSO2 IS supports encrypted id_token_hint as well.
Some Id_token may contain confidential claims. (There is no much security issues since the id_token_hint is intended only for the application)
Some application may use encrypted id_token.
Due to the above reasons, some applications may want to use encrypted id_token_hints in the logout request. In that case,
- When IS is sending id_token to the application, IS will encrypt the plain id_token with the application’s public key.
So when the application is using encrypted id_token,
- The application will decrypt the encrypted id_token using its own private key so that the application has the plain text id_token.
- When the logout is performed, the application must encrypt the plain text id_token using the WSO2 IS certificate.
- In the logout request, the application sends the encrypted id_token as the id_token_hint.
- Once it is received at the WSO2 IS, the server will decrypt the encrypted id_token from WSO2 IS’s key.
RP-initiated Federated Logout with WSO2 IS
This RP-initiated Federated logout is making use of OIDC RP-initiated logout. In this federated logout, WSO2 IS will act as a Relying party and invoke the OIDC logout endpoint of another OP. WSO2 IS supports this RP-initiated Federated logout and you can configure it in OpenID Connect Federated authenticator.
OIDC RP initiated logout with WSO2 IS ~ In Summary
1. The user initiates the logout from the client.
2. The user gets redirected to the end_session_endpoint. (oidc logout endpoint).
3. User will provide the consent to logout.
3. If the consent is yes, The Identity Server cleans the user’s SSO session. (IS will remove commonAuthId and opbs cookie)
4.Identity Server triggers a logout at other clients using OIDC session management or OIDC back-channel logout or OIDC front-channel logout (single logout).
5. After successful logout the user will return to the client using the post_logout_redirect_uri if specified.
6. If consent is no, IS will redirect to redirect to post_logout_redirect_uri if specified and config is enabled. (We have separate config to disable this. It is not mentioned in the spec how to handle this scenario).
If you pass a valid logout request, you can experience a successful logout with the WSO2 Identity Server!
References:
