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 |
---|---|
Modify the OAuth2 access token before the token is persisted or returned to the client. |
|
Return additional data from an authorization request. |
|
Evaluate and return an OAuth2 access token’s scope information. |
|
Customize the set of requested scopes for authorize, access token, refresh token, and back channel authorize requests. |
|
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 scripted custom plugins that are written in JavaScript. The following sections describe how to deploy a custom plugin.
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 all the sample JavaScript and Groovy scripts, see Sample scripts.
-
To use a plugin script, follow these steps:
-
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, you can use the AM admin UI. The sample scripts provide a good starting point for you to develop your own custom implementation.
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.
-
Set the
Plugin Type
attribute toSCRIPTED
. -
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 typeOAuth2 Validate Scope
.For further details about plugin configuration, see OAuth2 Provider Plugins.
-
Save your changes.
OAuth 2.0 scripting API
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. 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.