Diagnosing OAuth 2.0 Refresh Token Rotation Failures

Problem & Takeaway

When an OAuth 2.0 authorization server is configured to rotate refresh tokens, every successful token refresh should issue a new refresh token and revoke the old one. If this rotation fails, users can be unexpectedly logged out or clients can keep re‑using stale tokens, creating a security hole. This guide walks you through the most common symptoms, the likely root causes, a step‑by‑step diagnostic checklist, fixes tied to each finding, and when to involve your security or vendor teams.

Recognizable Conditions

• Clients receive invalid_grant immediately after a refresh attempt.
• The same refresh token ID appears in consecutive refresh responses.
• The revocation endpoint returns HTTP 500 or never records a revocation.
• Server logs show duplicate token IDs or missing revocation entries.
• Clients log “Refresh token revoked” but still use the old token for API calls.

Root‑Cause Mapping

Symptom	Possible Root Cause
invalid_grant on refresh	Stale token state; rotation not enabled or client library outdated.
Same token returned twice	Rotation flag disabled or mis‑configured.
500 from revocation endpoint	Endpoint mis‑configured, missing credentials, or server crash.
Duplicate token IDs in logs	Token persistence layer caching bug or race condition.
Client continues to use revoked token	Client library not updated to handle new token format.

Ordered Checks

1. Verify Rotation Flag
   • Run the admin console query or API call:

     curl -X GET "https://auth.example.com/api/v1/config" \
          -H "Authorization: Bearer <admin‑token>"
     

   • Look for rotate_refresh_token: true. If false, enable it and restart the server.
   • Permissions: requires admin‑level access.
   • Risk: Changing the flag may affect existing sessions; test in staging first.
2. Simulate a Refresh Request
   • Use a test client or curl:

     curl -X POST "https://auth.example.com/oauth/token" \
          -d "grant_type=refresh_token" \
          -d "refresh_token=<old‑token>" \
          -d "client_id=<client‑id>" \
          -d "client_secret=<client‑secret>"
     

   • Check the response: it should contain a new refresh_token value and a refresh_token_expires_in field.
   • Verify the new token ID differs from the old one.
   • Risk: If the server revokes the old token immediately, ensure the client can handle the new token.
3. Inspect Server Logs
   • Search for entries around the refresh time:

     grep "refresh_token" /var/log/authserver/rotations.log | tail -n 20
     

   • Look for a log line similar to:

     INFO: Rotated token abc123 to def456; revoked abc123
     

   • If no revocation entry exists, the rotation process failed.
   • Risk: Log rotation or retention settings may hide older entries; adjust filters accordingly.
4. Validate Revocation Endpoint Health
   • Ping the endpoint:

     curl -X POST "https://auth.example.com/oauth/revoke" \
          -d "token=<some‑token>" \
          -d "client_id=<client‑id>" \
          -d "client_secret=<client‑secret>"
     

   • Expect HTTP 200 or 204. A 500 indicates server error.
   • Check that the endpoint is reachable from the server’s network namespace.
   • Risk: A mis‑configured firewall can block the call, causing rotation to fail silently.
5. Confirm Client Library Compatibility
   • Check the client’s OAuth library version. For example, in Node.js:

     npm ls simple-oauth2
     

   • Upgrade to the latest patch that supports token rotation (e.g., v3.0.0).
   • Risk: Upgrading may introduce breaking changes; review the changelog before deployment.

Fixes Tied to Findings

• Rotation flag disabled – Enable rotate_refresh_token:true via the admin API and redeploy.
• Same token returned – Verify that the server’s token storage layer invalidates the old token before issuing a new one. Clear any caching layers that may return stale data.
• 500 from revocation endpoint – Check the endpoint’s service logs for stack traces, ensure database connectivity, and verify that the endpoint has the correct permissions to delete tokens.
• Duplicate token IDs in logs – Investigate race conditions in the token persistence layer. Consider adding a unique constraint on the token ID column.
• Client using revoked token – Update the client library to one that handles rotation, or implement a fallback that stores the new token in the local session store immediately after receiving it.

Escalation Criteria

1. Repeated invalid_grant errors across multiple clients after the rotation flag is confirmed enabled.
2. Server logs show no revocation entries for successful refresh attempts.
3. Revocation endpoint consistently returns 500 errors in production.
4. Security audit flags token persistence as a potential data leakage path.

When any of these conditions are met, open a ticket with your OAuth provider or internal security team, attach relevant logs, and request a deeper investigation of the token lifecycle code.

Practical Verification Checklist

Check	Expected Result
Rotation flag set to true	Server responds with rotate_refresh_token:true
Refresh request returns new token ID	New refresh_token differs from the old one
Revocation log entry exists	Log shows revoked abc123
Revocation endpoint returns 200/204	Successful revocation
Client library handles new token	No invalid_grant after refresh

Example: End‑to‑End Refresh Test

Assume you have a test account with client_id=demo and client_secret=xyz. Replace <old‑token> with a valid token you previously obtained.

# Step 1: Refresh the token
curl -X POST "https://auth.example.com/oauth/token" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=<old‑token>" \
     -d "client_id=demo" \
     -d "client_secret=xyz"

# Step 2: Verify response
# Expected: JSON with "access_token", "refresh_token" (new), "expires_in"

# Step 3: Check revocation
curl -X POST "https://auth.example.com/oauth/revoke" \
     -d "token=<old‑token>" \
     -d "client_id=demo" \
     -d "client_secret=xyz"

After the first request, the old token should no longer be valid. A subsequent attempt to use it should return invalid_grant. Verify this by trying to call a protected API with the old token.

Diagram

Client → Refresh Token → Authorization Server → Revocation Endpoint → New Refresh Token

Limitations & Notes

• These checks assume a typical OAuth 2.0 implementation with a dedicated revocation endpoint. Custom deployments may differ.
• Always perform these diagnostics in a staging environment first to avoid accidental revocation of real user sessions.
• Token rotation is a security feature; disabling it should be done only if you have a compelling reason and a compensating control in place.