Revoke access tokens that are bound to an SSO session when that session is invalid. #2943

AfraHussaindeen · 2025-10-01T03:28:17Z

Proposed changes in this pull request

$Subject
Changes :
- Add support to revoke access tokens that are bound to an SSO session when that session becomes invalid.
- Revocation is triggered when session invalidation is detected during one of the following:
  • Introspection API call
  • Resource access API call
  • Refresh token grant flow
- Address the issue where, even after the associated SSO session has expired, a new access token can still be generated using a refresh token.
Resolves,
- Proactively Revoke SSO-Bound Tokens on Session Expiration During Introspection wso2/product-is#25875
- Refresh Grant Flow Issues with SSO Session-Bound Tokens wso2/product-is#25876

Flows Tested

Opaque Token | Revoke token config enabled

 Opaque Token | Revoke token config disabled

Root organization user in a root org app.
- Token Introspection
- Protected API Call (e.g., SCIM)
- Refresh Grant Flow

JWT Token | Revoke config enabled and disabled

Root organization user in a root org app.
- Refresh Grant Flow

Note: In all the above flows, when revokeTokensWhenIdPSessionTerminated is enabled, the corresponding access token now gets revoked as expected.

Behavior Comparison

Scenario / Flow	Previous Behavior	Current Behavior (With Fix)
Token Introspection	`json { "active": false }`	Same as previous.
Protected API Call (e.g., SCIM)	`json { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "Authorization failure. Authorization information was invalid or missing from your request.", "status": 401 }`	Same as previous.
Refresh Grant Flow	A new access token was issued using the refresh token	`json { "error_description": "Token binding validation failed. Token is not bound to an active SSO session.", "error": "invalid_grant" }`

Developer Checklist (Mandatory)

Complete the Developer Checklist in the related product-is issue to track any behavioral change or migration impact.

Checklist (for reviewing)

General

Is this PR explained thoroughly? All code changes must be accounted for in the PR description.
Is the PR labeled correctly?

Functionality

Are all requirements met? Compare implemented functionality with the requirements specification.
Does the UI work as expected? There should be no Javascript errors in the console; all resources should load. There should be no unexpected errors. Deliberately try to break the feature to find out if there are corner cases that are not handled.

Code

Do you fully understand the introduced changes to the code? If not ask for clarification, it might uncover ways to solve a problem in a more elegant and efficient way.
Does the PR introduce any inefficient database requests? Use the debug server to check for duplicate requests.
Are all necessary strings marked for translation? All strings that are exposed to users via the UI must be marked for translation.

Tests

Are there sufficient test cases? Ensure that all components are tested individually; models, forms, and serializers should be tested in isolation even if a test for a view covers these components.
If this is a bug fix, are tests for the issue in place? There must be a test case for the bug to ensure the issue won’t regress. Make sure that the tests break without the new code to fix the issue.
If this is a new feature or a significant change to an existing feature? has the manual testing spreadsheet been updated with instructions for manual testing?

Security

Confirm this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.
Are all UI and API inputs run through forms or serializers?
Are all external inputs validated and sanitized appropriately?
Does all branching logic have a default case?
Does this solution handle outliers and edge cases gracefully?
Are all external communications secured and restricted to SSL?

Documentation

Are changes to the UI documented in the platform docs? If this PR introduces new platform site functionality or changes existing ones, the changes should be documented.
Are changes to the API documented in the API docs? If this PR introduces new API functionality or changes existing ones, the changes must be documented.
Are reusable components documented? If this PR introduces components that are relevant to other developers (for instance a mixin for a view or a generic form) they should be documented in the Wiki.

...ain/java/org/wso2/carbon/identity/oauth2/token/bindings/impl/SSOSessionBasedTokenBinder.java

...arbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/util/OAuth2TokenUtil.java

...so2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/util/OAuth2Util.java

...y.oauth/src/main/java/org/wso2/carbon/identity/oauth2/validators/TokenValidationHandler.java

wso2-engineering

AI Agent Log Improvement Checklist

⚠️ Warning: AI-Generated Review Comments

The log-related comments and suggestions in this review were generated by an AI tool to assist with identifying potential improvements. Purpose of reviewing the code for log improvements is to improve the troubleshooting capabilities of our products.
Please make sure to manually review and validate all suggestions before applying any changes. Not every code suggestion would make sense or add value to our purpose. Therefore, you have the freedom to decide which of the suggestions are helpful.

✅ Before merging this pull request:

Review all AI-generated comments for accuracy and relevance.
Complete and verify the table below. We need your feedback to measure the accuracy of these suggestions and the value they add. If you are rejecting a certain code suggestion, please mention the reason briefly in the suggestion for us to capture it.

Comment	Accepted (Y/N)	Reason
#### Log Improvement Suggestion No: 6
#### Log Improvement Suggestion No: 7
#### Log Improvement Suggestion No: 8
#### Log Improvement Suggestion No: 9
#### Log Improvement Suggestion No: 10
#### Log Improvement Suggestion No: 11
#### Log Improvement Suggestion No: 12
#### Log Improvement Suggestion No: 13
#### Log Improvement Suggestion No: 14
#### Log Improvement Suggestion No: 15
#### Log Improvement Suggestion No: 16
#### Log Improvement Suggestion No: 17

codecov · 2025-10-02T04:47:42Z

Codecov Report

❌ Patch coverage is 73.80952% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.24%. Comparing base (5c2841f) to head (c25aeb2).
⚠️ Report is 10 commits behind head on master.

Files with missing lines	Patch %	Lines
...uth2/token/handlers/grant/RefreshGrantHandler.java	69.23%	6 Missing and 6 partials ⚠️
...tity/oauth2/validators/TokenValidationHandler.java	69.56%	4 Missing and 3 partials ⚠️
...oken/bindings/impl/SSOSessionBasedTokenBinder.java	87.50%	1 Missing and 1 partial ⚠️
...auth2/token/bindings/impl/AbstractTokenBinder.java	80.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #2943      +/-   ##
============================================
- Coverage     57.28%   57.24%   -0.04%     
- Complexity     9251     9275      +24     
============================================
  Files           669      669              
  Lines         51972    52317     +345     
  Branches      11637    11669      +32     
============================================
+ Hits          29770    29948     +178     
- Misses        18024    18153     +129     
- Partials       4178     4216      +38

Flag	Coverage Δ
unit	`40.89% <73.80%> (+0.15%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

...so2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/util/OAuth2Util.java

Thumimku · 2025-10-02T05:41:34Z

.../src/main/java/org/wso2/carbon/identity/oauth2/token/handlers/grant/RefreshGrantHandler.java

        }

+        // Validate SSO session bound token.
+        if (OAuth2Constants.TokenBinderType.SSO_SESSION_BASED_TOKEN_BINDER.equals(oAuthAppDO.getTokenBindingType())) {


this check should comes as last logic, after checking for isPresent and isValidTokenBinding method

I intentionally placed the code block earlier because, within the isValidTokenBinding method [1], we cannot perform token revocation—at that point we don’t have access to the access token details.

By executing the session check before the token binding validation, we ensure that the session validity is verified regardless of whether the validateTokenBinding configuration is enabled. As a result, the subsequent binding reference validation will only be executed if the session is confirmed to be valid.

If we were to do it the other way around—relying solely on isValidTokenBinding [1]—then the session context would be checked there. If invalid, it would simply return false. At that point, before throwing the exception, we would still need to perform token revocation. But this would mean re-checking the session context, because we cannot conclusively say that the false result was due to session invalidation—it might have been triggered by some other reason.

That’s why I decided to proceed with the current approach. Please correct me if my understanding is off.

[1] https://github.com/AfraHussaindeen/identity-inbound-auth-oauth/blob/e15d74de0792f246d69dfce9fe6e65625b4695b6/components/org.wso2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/token/bindings/impl/SSOSessionBasedTokenBinder.java#L143

…lid.

Copilot

Pull Request Overview

This pull request implements token revocation for access tokens bound to SSO sessions when those sessions become invalid. The changes add support for automatically revoking access tokens when session invalidation is detected during introspection API calls, resource access API calls, and refresh token grant flows.

Key changes include:

Moved SSO session validation logic from TokenValidationHandler to OAuth2Util for reusability
Added automatic token revocation when bound SSO sessions become invalid
Enhanced refresh token grant flow to validate SSO session binding before issuing new tokens

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
TokenValidationHandlerTest.java	Updated test to use new OAuth2Util method for SSO session validation
OAuth2UtilTest.java	Added comprehensive test coverage for new SSO session validation and token binding methods
TokenValidationHandler.java	Refactored to use OAuth2Util.isTokenBoundToActiveSSOSession method
OAuth2Util.java	Added utility methods for token binding validation, SSO session checks, and token revocation
RefreshGrantHandler.java	Enhanced to validate SSO session binding during refresh token flow
SSOSessionBasedTokenBinder.java	Refactored validation logic to use OAuth2Util helper method
AbstractTokenBinder.java	Simplified token binding validation by using OAuth2Util helper method

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

.../src/main/java/org/wso2/carbon/identity/oauth2/token/handlers/grant/RefreshGrantHandler.java

...so2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/util/OAuth2Util.java

jenkins-is-staging · 2025-10-07T05:04:06Z

PR builder started
Link: https://github.com/wso2/product-is/actions/runs/18302578864

jenkins-is-staging · 2025-10-07T05:53:34Z

PR builder completed
Link: https://github.com/wso2/product-is/actions/runs/18302578864
Status: success

jenkins-is-staging

Approving the pull request based on the successful pr build https://github.com/wso2/product-is/actions/runs/18302578864

piraveena · 2025-10-07T10:05:14Z

...so2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/util/OAuth2Util.java

+    private static void revokeAccessToken(AccessTokenDO accessTokenDO) throws IdentityOAuth2Exception {
+
+        if (log.isDebugEnabled()) {
+            log.debug("Revoking token: " + accessTokenDO.getTokenId() + " for consumer key: " +


Are we logging tokenId in other logs? can you check?

Yes in several places. For an example refer

identity-inbound-auth-oauth/components/org.wso2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth/listener/OAuthCacheRemoveListener.java

Line 56 in 57c49b3

"identifier: " + accessTokenDO.getTokenId());

piraveena · 2025-10-07T10:15:21Z

...so2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/util/OAuth2Util.java

+     * @param cookieName              Cookie name
+     * @return Token binding value
+     */
+    public static Optional<String> getTokenBindingValue(OAuth2AccessTokenReqDTO oAuth2AccessTokenReqDTO,


Does this need to be a public util method or should go under session binder? Are we using this method in different places?

This is utilized in SSOSessionBasedTokenBinder and AbstractTokenBinder

...y.oauth/src/main/java/org/wso2/carbon/identity/oauth2/validators/TokenValidationHandler.java

...so2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/util/OAuth2Util.java

...y.oauth/src/main/java/org/wso2/carbon/identity/oauth2/validators/TokenValidationHandler.java

piraveena · 2025-10-08T08:16:54Z

.../src/main/java/org/wso2/carbon/identity/oauth2/token/handlers/grant/RefreshGrantHandler.java

+            if (!OAuth2Util.isTokenBoundToActiveSSOSession(tokenBinding, validationDataDO.getAccessToken(), oAuthAppDO,
+                    validationDataDO.getAuthorizedUser())) {
+                log.debug("Token is not bound to an active SSO session.");
+                throw new IdentityOAuth2Exception("Token binding validation failed. Token is not bound to an " +


This is a behavioural change.

jenkins-is-staging · 2025-10-08T23:05:57Z

PR builder started
Link: https://github.com/wso2/product-is/actions/runs/18360361622

jenkins-is-staging · 2025-10-08T23:52:48Z

PR builder completed
Link: https://github.com/wso2/product-is/actions/runs/18360361622
Status: success

jenkins-is-staging

Approving the pull request based on the successful pr build https://github.com/wso2/product-is/actions/runs/18360361622

piraveena · 2025-10-09T04:21:13Z

...y.oauth/src/main/java/org/wso2/carbon/identity/oauth2/validators/TokenValidationHandler.java

+                        .revokeAccessToken(revokeRequestDTO, accessTokenDO);
+            }
+        } catch (InvalidOAuthClientException | IdentityOAuth2Exception | UserIdNotFoundException e) {
+            log.error("Error while revoking SSO session bound access token.", e);


Why we are logging it without throwing the error to upper level. Do we need to handle these errors gracefully?

The intention was that a failure to revoke the token should not interrupt the introspection flow. To avoid interrupting the introspection flow, the exception for a failed token revocation is deliberately not thrown.

LGTM

AfraHussaindeen mentioned this pull request Oct 1, 2025

Proactively Revoke SSO-Bound Tokens on Session Expiration During Introspection wso2/product-is#25875

Closed

9 tasks