Customize OAuth 2.0 with plugins

AM includes several plugin points that let you extend OAuth 2.0 authorization server functionality, such as modifying access tokens or customizing how AM processes scopes.

Supported plugin points

The following table describes the OAuth 2.0 plugin points supported in AM.

Plugin	Description
Access token modification plugin	Modify the OAuth2 access token before the token is persisted or returned to the client.
Authorize endpoint data provider plugin	Return additional data from an authorization request.
Scope evaluator plugin	Evaluate and return an OAuth2 access token’s scope information.
Scope validator plugin	Customize the set of requested scopes for authorize, access token, refresh token and back channel authorize requests.
User info claims plugin	Fetch the resource owner’s information based on an issued access token.

Plugin

Description

Access token modification plugin

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

Authorize endpoint data provider plugin

Return additional data from an authorization request.

Scope evaluator plugin

Evaluate and return an OAuth2 access token’s scope information.

Scope validator plugin

Customize the set of requested scopes for authorize, access token, refresh token and back channel authorize requests.

User info claims plugin

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

How to build and use a custom OAuth 2.0 plugin

AM supports two types of custom plugin: scripted and Java. The following sections describe how to deploy a custom plugin according to your implementation type.

Customize with a plugin script

AM provides a scripting engine and template scripts for you to extend OAuth 2.0 behavior by running scripts stored as configuration, rather than by updating code. Creating and modifying plugin scripts enables rapid development without the need to change or recompile core AM.

To view the contents of the default scripts in the AM admin UI, including the available script properties, go to Realms > Realm Name > Scripts and select the script you want to examine.
To view all the sample JavaScript and Groovy scripts, see Sample scripts.
To use a plugin script, follow these steps:
1. Create or modify an OAuth 2.0 plugin script
2. Configure AM to use an OAuth 2.0 plugin script
3. Try your changes.
To step through a worked example for a scripted implementation, see Access token modification plugin.

Create or modify an OAuth 2.0 plugin script

To create or edit a script that is saved for the current realm, or modify a default script that is available to all realms, you can either:

For more information see The Scripting Guide.

Configure AM to use an OAuth 2.0 plugin script

After creating your plugin script, you need to configure AM to use the plugin.

In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins to configure a specific OAuth 2.0 provider.

To set your plugin as the default for all new OAuth2 providers, go to Configure > Global Services > OAuth2 Provider > Plugins.

Alternatively, to configure plugins at the client level, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > OAuth2 Provider Overrides.
Set the Plugin Type attribute to SCRIPTED.
Set the Script attribute to the name of the script you want to use.

For example, for the scope validation plugin, select the name of your script from the Scope Validation Script drop-down list. This list contains all the scripts that are saved for the current realm for the particular plugin type, including the default scripts that AM provides. In the case of the scope validation plugin, the list displays all scripts of type OAuth2 Validate Scope.

For further details about setting plugin configuration, see the OAuth2 provider configuration and Client overrides.
Save your changes.

Customize with a Java plugin

Write a Java class that implements one of the org.forgerock.oauth2.core.plugins interfaces. AM provides sample code and some default implementation classes for each of the plugin interfaces.

To view the supported plugin interfaces, see the Javadoc for the org.forgerock.oauth2.core.plugins package.
To view the sample and custom classes, see the details for the individual plugin points.
To use a Java plugin, follow these steps:
1. Create and deploy a Java OAuth 2.0 plugin
2. Configure AM to use a Java OAuth 2.0 plugin
3. Try your changes.
To step through a worked example for a Java implementation, see the Scope evaluator plugin.

Create and deploy a Java OAuth 2.0 plugin

Create a custom Java class that implements the appropriate plugin interface, and package in a JAR file.

To use an existing example, download the sample code and build a JAR file by following the steps described in How do I access and build the sample code provided for AM? in the Knowledge Base.
Copy the built JAR file to the /WEB-INF/lib folder where you deployed AM.
Restart AM or the container in which it runs.

Configure AM to use a Java OAuth 2.0 plugin

After creating your plugin, you need to configure AM to use the plugin.

In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins to configure a specific OAuth 2.0 provider.

To set your plugin as the default for all new OAuth2 providers, go to Configure > Global Services > OAuth2 Provider > Plugins.

Alternatively, to configure plugins at the client level, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > OAuth2 Provider Overrides.
Set the Plugin Type attribute to JAVA.
Set the Plugin Implementation Class attribute.

For example, for the scope evaluation plugin, type the fully qualified name of your plugin class in the Scope Evaluation Plugin Implementation Class field.

For further details about setting plugin configuration, see the OAuth2 provider configuration and Client overrides.
Save your changes.

OAuth 2.0 scripting API

For information about the API available for implementing scripts, see:

Accessing HTTP Services
Debug logging
The AccessToken interface provides methods that let you view or modify the data associated with an access token.
The AMIdentity interface represents an identity that is managed by AM.
The SSOToken interface contains SSO token and authentication information, as well as session-related properties.

The following properties are common to all OAuth 2.0 scripts. See individual plugins for additional properties specific to the script type.

Show script properties

httpClient: The HTTP client for making external HTTP requests. Always present.
logger: The logger instance particular to the script type. For more information, see Debug Logging. The output log files will be prefixed by a static string denoting the script type. Always present.
scriptName: The display name of the script. Always present.

Access Management 7.2.2