Customize OAuth2.0 using JavaScript extensions

PingOne Advanced Identity Cloud lets you script extensions in JavaScript to customize OAuth 2.0 authorization server functionality, such as modifying access tokens or customizing how PingOne Advanced Identity Cloud processes scopes.

Supported extensions

The following table describes the extensible features of an PingOne Advanced Identity Cloud OAuth 2.0 authorization server.

Feature	Extension options	Samples
Access tokens	Modify the OAuth 2.0 access token before the token is persisted or returned to the client.	oauth2-access-token-modification.js
Authorize endpoint data provider	Return additional data from an authorization request.	oauth2-authorize-endpoint-data-provider.js
Scope evaluation	Evaluate and return an OAuth 2.0 access token’s scope information.	oauth2-evaluate-scope.js
Scope validation	Customize the requested scopes for authorization, access token, refresh token, and backchannel authorization requests.	oauth2-validate-scope.js
OpenID Connect 1.0 (OIDC) claims	Fetch the resource owner’s information based on an issued access token.	oidc-claims-extension.js

Feature

Extension options

Samples

Access tokens

Modify the OAuth 2.0 access token before the token is persisted or returned to the client.

oauth2-access-token-modification.js

Authorize endpoint data provider

Return additional data from an authorization request.

oauth2-authorize-endpoint-data-provider.js

Scope evaluation

Evaluate and return an OAuth 2.0 access token’s scope information.

oauth2-evaluate-scope.js

Scope validation

Customize the requested scopes for authorization, access token, refresh token, and backchannel authorization requests.

oauth2-validate-scope.js

OpenID Connect 1.0 (OIDC) claims

Fetch the resource owner’s information based on an issued access token.

oidc-claims-extension.js

Use extensions

The PingOne Advanced Identity Cloud scripting environment runs scripts that you create and manage using the Advanced Identity Cloud admin UI.

After creating a script, configure the OAuth 2.0 provider service to use it.

Access token modification

Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select your script in the Access Token Modification Script drop-down.

Authorize endpoint data provider

Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select SCRIPTED in the Authorize Endpoint Data Provider Plugin Type drop-down.
Select your script in the Authorize Endpoint Data Provider Script drop-down.

Scope evaluator

Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select SCRIPTED in the Scope Evaluation Plugin Type drop-down.
Select your script in the Scope Evaluation Provider Script drop-down.

Scope validator

Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select SCRIPTED in the Scope Validation Plugin Type drop-down.
Select your script in the Scope Validation Provider Script drop-down.

User info claims

Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select your script in the OIDC Claims Script drop-down.

For reference information, refer to OAuth2 provider plugins.

It is also possible to configure extensions in client profiles. Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > OAuth2 Provider Overrides.

Common OAuth 2.0 extension bindings

An extension script has access to bindings, objects that PingOne Advanced Identity Cloud injects into the script execution context.

Some extension scripts have access to the following bindings. For additional bindings, refer to the comments in the sample scripts.

Binding Information

Binding	Information
`accessToken`	The OAuth 2.0 access token. For details, refer to AccessToken.
`httpClient`	An HTTP client for making external HTTP requests. Always present in all extension scripts.
`identity`	An identity PingOne Advanced Identity Cloud can access. For details, refer to AMIdentity.
`logger`	Write a message to the PingOne Advanced Identity Cloud debug log. Always present in all extension scripts. In Advanced Identity Cloud, this corresponds to the `am-core` log source. Logger names use the format: scripts.<context>.<script UUID>.(<script name>); for example, `scripts.OIDC_CLAIMS.36863ffb-40ec-48b9-94b1-9a99f71cc3b5.(OIDC Claims Script). For information about debug logs, refer to Get audit and debug logs.
`scriptName`	The display name of the script. Always present in all extension scripts.
`session`	The user’s session object. For details, refer to SSOToken.

accessToken

The OAuth 2.0 access token.

For details, refer to AccessToken.

httpClient

An HTTP client for making external HTTP requests. Always present in all extension scripts.

identity

An identity PingOne Advanced Identity Cloud can access.

For details, refer to AMIdentity.

logger

Write a message to the PingOne Advanced Identity Cloud debug log. Always present in all extension scripts.

In Advanced Identity Cloud, this corresponds to the am-core log source.

Logger names use the format: scripts.<context>.<script UUID>.(<script name>); for example, `scripts.OIDC_CLAIMS.36863ffb-40ec-48b9-94b1-9a99f71cc3b5.(OIDC Claims Script).

For information about debug logs, refer to Get audit and debug logs.

scriptName

The display name of the script. Always present in all extension scripts.

session

The user’s session object.

For details, refer to SSOToken.