Authorize endpoint data provider

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.

Sample script

OAuth2 Authorize Endpoint Data Provider Script (Legacy)

Script bindings

Java interface

org.forgerock.oauth2.core.plugins.AuthorizeEndpointDataProvider

Sample Java code

/*
 * Copyright 2021-2025 Ping Identity Corporation. All Rights Reserved
 *
 * This code is to be used exclusively in connection with Ping Identity
 * Corporation software or services. Ping Identity Corporation only offers
 * such software or services to legal entities who have entered into a
 * binding license agreement with Ping Identity Corporation.
 */

package org.forgerock.openam.examples;

import java.util.HashMap;
import java.util.Map;

import org.forgerock.oauth2.core.OAuth2Request;
import org.forgerock.oauth2.core.Token;
import org.forgerock.oauth2.core.plugins.AuthorizeEndpointDataProvider;

/**
 * Custom implementation of the Authorize Endpoint Data Provider
 * plugin interface {@link org.forgerock.oauth2.core.plugins.AuthorizeEndpointDataProvider}
 *
 * <li>
 * The {@code provide} method returns hard coded additional value.
 * </li>
 *
 */
public class CustomAuthorizeEndpointDataProvider implements AuthorizeEndpointDataProvider {

    @Override
    public Map<String, String> provide(Map<String, Token> tokens, OAuth2Request request) {
        Map<String, String> customMapping = new HashMap<String, String>();
        customMapping.put("additional", "field");
        return customMapping;
    }
}

Example authorization endpoint data provider plugin

Complete the following steps to implement an authorization endpoint data provider script that returns custom user session data:

Create a custom script
Configure AM to use the script
Create an OAuth2 client for authorization
Try the sample authorization endpoint data provider plugin

To configure AM to use a Java authorization endpoint data provider plugin, refer to Configure AM to use a Java OAuth 2.0 plugin.

Create a custom script

Create a new OAuth2 Authorize Endpoint Data Provider Script.

You can create either a Legacy or a Next Generation script.

In the script window, add the following JavaScript:

Legacy
Next-generation

(function () {
  var map = new java.util.HashMap()

  // Add an arbitrary query string parameter.
  map.put("hello", "world")

  // Add the IP address if available.
  if (session) {
    map.put("ipAddress", session.getProperty("Host"))
  }

  return map
}());

var map = {};

// Add an arbitrary query string parameter.
map.key = "value";

// Add the IP address if available.
if (session) {
    map.ipAddress = session.getProperty("Host");
}

map;

Find information about the common bindings such as logger and scriptName in Common bindings.

Find the bindings specific to scope evaluation scripts in the Scope evaluation scripting API.

Save your changes.

The script returns a static key/value pair, "hello": "world", and adds the user’s IP address from session data.

Configure AM to use the script

Perform this task to set up an OAuth2 provider to use the authorization endpoint data provider script.

Configure the provider and make sure the following properties are set:
- Authorize Endpoint Data Provider Plugin Type to SCRIPTED.
- Authorize Endpoint Data Provider Script to 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: mySecret
- 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

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM…TU3OQ*",
    "successUrl":"/am/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://am.example.com:8443/am/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%2Fam.example.com%3A8443%2Fam%2Foauth2&hello=world&state=abc123&client_id=myClient
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Content-Length: 0

As the example output indicates, the parameters injected by the authorization endpoint data provider script, ipAddress=127.0.0.1 and hello=world, are both appended to the redirect URL.

PingAM