[OPENAM-8440] Pluggable OAuth2 Access Token Format Created: 25/Feb/16  Updated: 22/Nov/18  Resolved: 22/Nov/18

Status: Closed
Project: OpenAM
Component/s: oauth2
Affects Version/s: 13.0.0, 13.5.0, 13.5.1, 14.0.0, 14.1.0, 14.1.1, 14.5.0, 14.5.1, 5.5.1
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: Simon Moffatt Assignee: Unassigned
Resolution: Duplicate Votes: 7
Labels: Backlog
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
is duplicated by OPENAM-11445 Request to Customize OAuth2 Access To... Closed
relates to OPENAM-11445 Request to Customize OAuth2 Access To... Closed
is related to OPENAM-10362 Allow encryption in JWT payload for O... Closed
Epic Link: OAuth 2.0 Improvements
Support Ticket IDs:


The current OAuth2 access_token is not pluggable - it's a stateful proprietary opaque token type.

Ideally the access_token format should be pluggable based on implementation. For example, the ability to leverage a JWT format, with an additional scriptable component to control attributes within the JWT similar to the scriptable OIDC id_token.

Comment by Andy Hall [ 07/Apr/16 ]

Simon Moffatt We plan to offer a stateful or stateless OAuth token based on realm config.

Can you provide an example use case for wanting this pluggable format too?

Comment by Miguel Fernandez [X] (Inactive) [ 09/Jan/17 ]

Hi guys,

I am using stateless OAuth2 access tokens (JWT encoded) as they were included in OpenAM 13.5. This is working for me.

However, I miss the ability to leverage the JWT format that @SimonMoffatt mentioned allowing a scriptable component to control which attributes to include inside the JWT token (in the payload section) - similar to the scriptable OIDC id_token. Has there been any progress in this regard?

The use case scenario is that we need to add additional attributes in the payload section of the JWT token (for my current scenario could be a set of attributes for someone else any other). The reason is that with OAuth2 you only have 1 token (an access token), not an access token + an additional identity token (like OIDC).
If we do not want to use a "Token Info endpoint" that returns the information of the token (and it is becoming more and more frequent to code OAuth2 tokens as JWT, for instance Spring Framework offers this feature - what you called stateless - so the Resource Servers can validate an access token directly) we need to be able to add extra fields to the OAuth2 access token (the JWT-encoded token in these case).
A very clear particular case is: we want to use OAuth2 stateless tokens (JWT-encoded), we do NOT want the Resource Servers to access the "Token Info Endpoint" (whatever the reason - there are important ones, starting with performance) but the Resource Servers apart from validating the access token (correct client id, not expired, scopes and so on) will want to apply authorization rules based on user roles (this is out of the scope of OAuth2 spec). As you do not count on a "Token Info Endpoint" returning the information related to the OAuth2 access token and the extra information / fields you want to include (the roles) the OAuth2 JWT-encoded token needs to include the roles.

For instance, the decoded "payload" section of the example JWT message would look like this including the "ROLES" attribute:

  "sub": "testuser",
  "auditTrackingId": "33f90234-f66f-4f54-b25d-f939b0d68aac",
  "iss": "http://openam.test:8080/openam/oauth2/oauth_test",
  "tokenName": "access_token",
  "token_type": "Bearer",
  "authGrantId": "9654c941-b707-4255-b576-a5ac9b416499",
  "aud": "poc-spa-client",
  "nbf": 1483360956,
  "scope": [
  "realm": "/oauth_employees",
  "exp": 1483364556,
  "iat": 1483360956,
  "expires_in": 3600000,
  "jti": "0bd8fde9-b595-4527-9ae8-535e073bf9c2"

In summary, customizing the JWT payload for OAuth2 stateless tokens is necessary for those systems that use plain OAuth2 (with only an access token), not OIDC.
In most of the cases the OAuth2 stateless feature could not be used unless you can add extra information in the JWT token (as the Resource Servers are 'stateless' and need to obtain this information from the access token).

The issue seems a bit old, from last April. Has there been any progress in this direction?

Thanks and Regards,

Comment by Miguel Fernandez [X] (Inactive) [ 12/Jan/17 ]


There is another JIRA issue opened related to some posible improvements for OAuth2 stateless (JWT) tokens here:


I wanted to related them if you want to consider all the proposed improvements together but I was not able to do it.

Thanks and Regards,


Comment by Bernhard Thalmayr [ 23/Apr/18 ]

This is needed for all kind of use cases.

Comment by Andy Hall [ 22/Nov/18 ]

When resolving OPENAM-11445 we should take into account the data in this ticket also.

Generated at Sun Sep 27 23:18:33 UTC 2020 using Jira 7.13.12#713012-sha1:6e07c38070d5191bbf7353952ed38f111754533a.