Authorize endpoint data provider plugin
Use this plugin to configure the OAuth2 provider to return additional data from an authorization request, such as data from the user’s session or from an external service.
To view a sample script, including the available script properties, see oauth2-authorize-endpoint-data-provider.js.
Example authorization endpoint data provider plugin
Complete the following steps to implement an authorization endpoint data provider script that returns custom user session data:
Prepare the authorization endpoint data provider script
This task decribes how to create a script to retrieve additional fields.
-
In the AM admin UI, go to Realms > Realm Name > Scripts, and click New Script.
-
Enter a unique name for your script, select
OAuth2 Authorize Endpoint Data Provider
from the Script Type drop-down list, and click Create. -
Copy the oauth2-authorize-endpoint-data-provider.js script and paste in the Script field.
-
Enable the script by removing, or commenting out as seen in this example, the following block comments surrounding the function, on lines 40 and 90:
// /* EXAMPLE ... // */
-
For the purposes of this simple test, comment out the call to add data from a third-party service:
//addAdditionalDataFromExternalService();
-
-
Save your changes.
The template authorization endpoint data provider script is now amended to return a static key/value pair, "hello": "world"
, and to get the user’s IP address from the session data.
Configure AM to use the authorization endpoint data provider script
Perform this task to set up an OAuth2 provider to use the authorization endpoint data provider script.
-
Log in to the AM admin UI as an administrator.
-
Configure the OAuth2 Provider:
-
If no provider exists for the current realm, create a new OAuth 2.0 provider:
-
Go to Realms > Realm Name > Services and click Add a Service.
-
Select OAuth2 Provider service from the drop-down list, leave the fields unchanged, and click Create.
-
-
Otherwise, go to Realms > Realm Name > Services > OAuth2 Provider.
The OAuth2 provider configuration is displayed.
For information on OAuth 2.0 provider properties, see OAuth2 Provider.
-
-
Select the Plugins tab to edit the following settings:
-
Set Authorize Endpoint Data Provider Plugin Type to
SCRIPTED
. -
Set Authorize Endpoint Data Provider Script to the name of the script you created.
-
-
Save your changes.
Create an OAuth2 client for authorization
Create an OAuth 2.0 client to use in the authorization request.
-
In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients, and click Add Client.
-
Enter the following values:
-
Client ID:
myClient
-
Client secret:
forgerock
-
Redirection URIs:
https://www.example.com:443/callback
-
Scope(s):
access|Access to your data
-
-
Click Create.
AM is now prepared for you to perform an OAuth2 authorization request to try the sample plugin.
Try the sample authorization endpoint data provider plugin
-
Log in to AM as the
demo
user, for example:$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: demo" \ --header "X-OpenAM-Password: Ch4ng31t" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…TU3OQ*", "successUrl":"/openam/console", "realm":"/alpha" }
Note the SSO token value returned as
tokenId
in the output. -
Invoke the authorization server’s /oauth2/authorize endpoint specifying the SSO token value in a cookie, and the following parameters:
-
client_id=
myClient
-
response_type=
code
-
redirect_uri=
https://www.example.com:443/callback
-
decision=
allow
-
csrf=SSO-token
For example:
$ curl --dump-header - \ --request POST \ --Cookie "iPlanetDirectoryPro=AQIC5wM…TU3OQ*" \ --data "scope=access" \ --data "response_type=code" \ --data "client_id=myClient" \ --data "csrf=AQIC5wM…TU3OQ*" \ --data "redirect_uri=https://www.example.com:443/callback" \ --data "state=abc123" \ --data "decision=allow" \ "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/authorize"
If the authorization server is able to authenticate the user and the client, it returns a successful HTTP 302 response, for example:
HTTP/1.1 302 Found Server: Apache-Coyote/1.1 X-Frame-Options: SAMEORIGIN Pragma: no-cache Cache-Control: no-store Date: Mon, 30 Jul 2018 11:42:37 GMT Accept-Ranges: bytes Location: https://www.example.com:443/callback?code=g5B3qZ8rWzKIU2xodV&ipAddress=127.0.0.1&scope=access&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&hello=world&state=abc123&client_id=myClient Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept Content-Length: 0
As seen in the example output, the parameters injected by the authorization endpoint data provider script,
ipAddress=127.0.0.1
andhello=world
, are both appended to the redirect URL. -
OAuth 2.0 authorization endpoint data provider scripting API
The following properties are available to authorization endpoint data provider scripts, in addition to the common OAuth 2.0 properties.
Show script properties
session
-
Contains a representation of the user’s session object if the request contained a session cookie.