Supporting reference access/refresh tokens

[tnorimat]

Description

Currently, Keycloak only supports a self-contained token. How about supporting also reference token?

Discussion: #19649

I have already implemented PoC codes for it the by following the specifications and confirmed that they work well as I expected.

How to manage the cache holding relationship between a self-contained token and a reference token

• Keycloak does not hold such the cache by itself. A user of Keycloak who wants to use a reference token needs to prepare the cache. Keycloak only defines I/F with the cache.

Target tokens

• an access token and a refresh token returned from Token endpoint (excluding an access token returned in an authorization response by OIDC Hybrid flow).

Keycloak -> a client - converting a self-contained token to a reference token:

1. Generating and returning an access/refresh token:

• Endpoint: Token endpoint
• Protocol flow: Authorization code flow, Device authorization flow, OIDC Backchannel authentication flow (CIBA)

2. Re-generating and returning an access/refresh token:

• Endpoint: Token endpoint
• Protocol flow: Token refresh

A client/resource server -> Keycloak - converting a reference token to a self-contained token:

1. Receiving a token refresh request:

• Endpoint: Token endpoint
• Token: a refresh token
• Protocol flow: Token refresh

2. Receiving a token introspect request:

• Endpoint: Token Introspection endpoint
• Token: an access token, a refresh token
• Protocol flow: Token introspection

3. Receiving a UserInfo request:

• Endpoint: UserInfo endpoint
• Token: an access token
• Protocol flow: UserInfo request

4. Receiving a token revoke request:

• Endpoint: Token revocation endpoint
• Token: an access token, a refresh token
• Protocol flow: Token revoke request

5. Receiving a backchannel logout (legacy) request:

• Endpoint: Logout endpoint
• Token: a refresh token
• Protocol flow: Backchannel logout (legacy, not OIDC for logout compliant)

How to convert a self-contained token to a reference token and vise versa:

• Abstract class of client policies' executor (SPI provider)

How to generate a reference token

• Concrete class of client policies' executor (SPI provider), so a user of Keycloak can customize it.

How to define and implement I/F an external cache holding relationship between a self-contained token and a reference token:

• Concrete class of client policies' executor (SPI provider), so a user of Keycloak can customize it.

Actual reference implementation of such the I/F with the cache:

• I/F: REST API
  • bind and store the relationship between a self-contained token and a reference token
    • Request (application/json): a reference token, a self-contained token
    • Method: POST
    • Response
      • 204 No Content
      • 400 Bad Request
      • 500 Internal Server Error
  • get the self-contained token bound with the reference token
    • Request: the reference token
    • Method: GET
    • Response (application/json)
      • 200 OK: the self-contained token
      • 400 Bad Request
      • 500 Internal Server Error

Actual reference implementation of a reference token

• Format: "jti" claim value of a self-contained token

Discussion

#19649

Motivation

• Privacy: Some use cases require not including sensitive data like Personal Identifiable Information (PII) in an access token.
• Confidentiality: Not disclosing information which a resource server only need to know to 3rd party entities like clients.
• Security requirement: Some use cases requires a reference token as their requirement.

Details

• Cache: Keycloak does not implement such the cache by itself. Instead of it, Keycloak defines I/F with the cache and a user of Keycloak prepares it implementing the I/F, which burdens a user of Keycloak who want to use a reference token. However, Keycloak itself and other user who uses a self-contained token as usual are not affected by supporting a reference token.
• Non-invasive way: a reference token is realized by client policies, which means that Keycloak's body codes and other user who uses a self-contained token as usual are not affected by supporting a reference token.
• Flexibility: by using client policies, it is easy to specify which clients use a reference token. Namely, we can select using a reference token or a self-contained token per client.
• Flexibility: a user of Keycloak can implement their own I/F with the cache as a SPI provider.

[tnorimat]

By incorporating the discussion, I will take another way by #21186 .

[tnorimat]

close it because we could take other ways described the issue to do it.