Add OAuth2 Access Token Modification Script (OAUTH2_ACCESS_TOKEN_MODIFICATION)

[vharseko]

Summary

This PR introduces a fully-fledged OAuth2 Access Token Modification script type
(script context OAUTH2_ACCESS_TOKEN_MODIFICATION), analogous to ForgeRock AM 6.5.

It adds a supported extension point that allows custom claims (e.g. acr,
amr, roles, profile attributes) to be embedded directly into stateless (JWT)
OAuth 2.0 access tokens and refresh tokens at issue time — without an extra
call to /oauth2/tokeninfo.

Closes / addresses: OpenAM Discussion #1027

Background / Problem

The stateless JWT claim set is built in
StatelessTokenStore.createAccessToken(...)
directly through JwtClaimsSetBuilder with a hard-coded set of fields and no
extension point.

As a result, by design:

• The OIDC Claims Script, custom Scope Implementation Class, and
  scope-to-claim mappings are never invoked when issuing a stateless JWT
  access token (they only apply to id_token, /userinfo, /tokeninfo).
• Unlike commercial ForgeRock AM 6.5+, OpenIdentityPlatform/OpenAM had no
  Access Token Modification Script.

Users therefore could not get acr/amr/custom claims into the access token
payload without an additional /tokeninfo round-trip.

Solution

A new script context OAUTH2_ACCESS_TOKEN_MODIFICATION is executed when a
stateless access token or refresh token is issued. Claims the script adds,
modifies, or removes are merged into the token payload before signing.

The script runs in both createAccessToken and createRefreshToken, so
custom claims survive the refresh cycle.

Script bindings

Binding	Type	Description
accessToken	ScriptableAccessToken	Mutable view of the token: setField / getField / removeField
scopes	Set<String>	Granted scopes
identity	AMIdentity (nullable)	Resource owner identity
session	SSOToken (nullable)	User session if present
requestProperties	Map<String, Object>	Selected request properties (clientId, realm, grantType)
logger	Debug	OAuth2Provider debug logger

Default script (Groovy)

A safe default global script is shipped (UUID
d22f9a0c-426a-4466-b95e-d0f125b0d5fa). It propagates acr/amr and includes
commented examples (e.g. adding email). When the provider setting is
[Empty], the token is issued unchanged.

Changes

Scripting infrastructure (openam-scripting)

• ScriptConstants: new ScriptContext.OAUTH2_ACCESS_TOKEN_MODIFICATION,
  *_NAME constant, GlobalScript entry.
• ScriptingGuiceModule: StandardScriptEngineManager + named ScriptEvaluator.
• ScriptEngineConfigurator: register engine config for the new context.
• ScriptConfigurationService: usage-count handling for the new context.
• scripting.xml / scripting.properties: choice values, context sub-config
  with class whitelist, default global Groovy script.
• groovy/access-token-modification.groovy: default script + pom.xml inject.

OAuth2 (openam-oauth2 / openam-core)

• OAuth2Constants: provider setting
  forgerock-oauth2-provider-access-token-modification-script, new
  ScriptParams (accessToken, requestProperties).
• ScriptableAccessToken (new): mutable token view exposed to scripts.
• OAuth2AccessTokenModifier (new): loads & evaluates the script, builds
  bindings, returns claims to merge.
• StatelessTokenStore: invokes the modifier and merges claims in both
  createAccessToken and createRefreshToken.
• OAuth2GuiceModule: threads the new dependency into the realm-agnostic store.
• OAuth2Provider.xml / .properties / .section.properties: new provider
  attribute with scriptSelect UI type.

Upgrade / defaults

• OAuth2ProviderUpgradeHelper: registers the new attribute for upgrades.
• serviceDefaultValues.properties: GlobalAccessTokenModificationScriptId.

Documentation (openam-documentation)

• Dev Guide: chap-scripting.adoc (new API section + context list),
  chap-client-dev.adoc (language table + context values).
• Reference: chap-config-ref.adoc (provider attribute + scripting context).
• Admin Guide: chap-manage-scripts.adoc (context enum).

Tests

• StatelessTokenStoreTest: +4 tests (claims merged into access token & refresh
  token; empty result leaves token unchanged; constructor update).
• ScriptableAccessTokenTest (new): 6 tests for the binding object API.

UI impact

None required. Script contexts and the OAuth2 Provider attribute are rendered
dynamically from the service schema (ScriptsService.getAllContexts() /
getContextSchema(), and the scriptSelect attribute via ScriptChoiceValues).
OIDC_CLAIMS is likewise never hard-coded in the UI.

Backwards compatibility

Fully backwards compatible. When no script is selected ([Empty]), the token is
issued exactly as before. The feature only applies to stateless (JWT) tokens.

How to use

1. Realms → Realm → Services → OAuth2 Provider → Core.
2. Enable Use Stateless Access & Refresh Tokens.
3. Set OAuth2 Access Token Modification Script (default:
   OAuth2 Access Token Modification Script), or edit the global script under
   Realms → Realm → Scripts.

Testing

mvn -o -pl openam-oauth2 test -Dtest=StatelessTokenStoreTest,ScriptableAccessTokenTest
# Tests run: 15, Failures: 0, Errors: 0, Skipped: 0 — BUILD SUCCESS

Affected modules also compile cleanly:

mvn -o -pl openam-core,openam-scripting,openam-oauth2,openam-upgrade -am compile -DskipTests