--- title: Customize OAuth 2.0 description: 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. component: pingam version: 8.1 page_id: pingam:am-oauth2:customizing-oauth2-scopes canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/customizing-oauth2-scopes.html keywords: ["OAuth 2.0", "Customization", "Federation", "Scripting", "Java"] page_aliases: ["oauth2-guide:customizing-oauth2-scopes.adoc"] section_ids: supported_plugin_points: Supported plugin points use-custom-oauth2-plugin: How to build and use a custom OAuth 2.0 plugin use-custom-scripted-oauth2-plugin: Customize with a script create-scripted-oauth2-plugin: Create or modify an OAuth 2.0 plugin script configure-scripted-oauth2-plugin: Configure AM to use an OAuth 2.0 plugin script use-custom-java-oauth2-plugin: Customize with Java create-java-oauth2-plugin: Create and deploy a Java OAuth 2.0 plugin configure-java-oauth2-plugin: Configure AM to use a Java OAuth 2.0 plugin --- # Customize OAuth 2.0 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](modifying-access-tokens-scripts.html) | Modify the OAuth2 access token before the token is persisted or returned to the client. | | [Authorize endpoint data provider](plugins-auth-endpoint-data-provider.html) | Return additional data from an authorization request. | | [Scope evaluation](plugins-scope-evaluation.html) | Evaluate and return an OAuth2 access token's scope information. | | [Scope validation](plugins-scope-validation.html) | Customize the set of requested scopes for authorize, access token, refresh token and back channel authorize requests. | | [OIDC claims](plugins-user-info-claims.html) | 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 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. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Learn about OAuth 2.0 and OIDC scripts from the following resources:- In the AM admin UI, go to Realms > *realm name* > Scripts to view the default template scripts. You can also find them in [Sample scripts](../am-scripting/sample-scripts.html). - Find information about the available bindings in [OAuth 2.0 / OIDC scripting API](../am-scripting/oauth2-scripting-api.html). - Find an example of a scripted implementation in [Access token modification](modifying-access-tokens-scripts.html). | 1. To use a script, follow these steps: 1. [Create or modify an OAuth 2.0 plugin script](#create-scripted-oauth2-plugin). 2. [Configure AM to use the OAuth 2.0 plugin script](#configure-scripted-oauth2-plugin). 2. Try your changes. #### 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: * [Use the AM admin UI](../am-scripting/manage-scripts-console.html) or * [Perform a REST call using the /scripts endpoint](../am-scripting/manage-scripts-rest.html). For more information, refer to [Scripting](../am-scripting/preface.html). #### Configure AM to use an OAuth 2.0 plugin script After creating your plugin script, you must configure AM to use the plugin. 1. 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 ID* > OAuth2 Provider Overrides and select Enable OAuth2 Provider Overrides. 2. Set the `Plugin Type` attribute to `SCRIPTED`. 3. 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, refer to the [OAuth2 provider configuration](../setup/services-configuration.html#global-oauth-oidc-plugins) and [Client overrides](oauth2-register-client.html#configure-oauth2-oidc-client-overrides). | 4. Save your changes. ### Customize with Java 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, refer to the Javadoc for the `org.forgerock.oauth2.core.plugins` package. * To view the sample and custom classes, refer to 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](#create-java-oauth2-plugin) 2. [Configure AM to use a Java OAuth 2.0 plugin](#configure-java-oauth2-plugin) 3. Try your changes. * To step through an example of a Java implementation, refer to the [Scope evaluation](plugins-scope-evaluation.html). #### Create and deploy a Java OAuth 2.0 plugin 1. 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 PingAM?](https://support.pingidentity.com/s/article/How-do-I-access-and-build-the-sample-code-provided-for-PingAM) in the *Knowledge Base*. 2. Copy the built JAR file to the `/WEB-INF/lib` folder where you deployed AM. 3. Restart AM or the container in which it runs. #### Configure AM to use a Java OAuth 2.0 plugin After creating your plugin, you must configure AM to use the plugin. 1. 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 ID* > OAuth2 Provider Overrides. 2. Set the `Plugin Type` attribute to `JAVA`. 3. 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. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Find information about setting plugin configuration in the [OAuth2 provider configuration](../setup/services-configuration.html#global-oauth-oidc-plugins) and [Client overrides](oauth2-register-client.html#configure-oauth2-oidc-client-overrides). | 4. Save your changes.