Customize OAuth2.0 using JavaScript extensions

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

Supported extensions

The following table describes the extensible features of an 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 Identity Cloud scripting environment runs scripts that you create and manage using the Identity Cloud admin UI.

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

Access token modification

In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select your script in the Access Token Modification Script drop-down.

Authorize endpoint data provider

In the AM admin UI, 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

In the AM admin UI, 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

In the AM admin UI, 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

In the AM admin UI, 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. In the AM admin UI, 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 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 Identity Cloud can access. For details, refer to AMIdentity.
`logger`	Write a message to the Identity Cloud debug log. Always present in all extension scripts. In Identity Cloud, this corresponds to the `am-core` log source. The logger identifier takes the form `scripts.script-type.script-id`. For details, refer to Debug.
`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 Identity Cloud can access.

For details, refer to AMIdentity.

logger

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

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

The logger identifier takes the form scripts.script-type.script-id.

For details, refer to Debug.

scriptName

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

session

The user’s session object.

For details, refer to SSOToken.