Identity Cloud

Authorize endpoint data provider

Use this extension point to add data to Identity Cloud’s response to an OAuth 2.0 authorization request.

This page demonstrates a simple script. For additional options, refer to the sample authorize endpoint extension script.

Prepare the demonstration

Start by preparing the demonstration:

Sample script

The sample adds query string parameters to the redirect URL in the OAuth 2.0 authorization response.

  1. Create the script.

    Under Native Consoles > Access Management, select Realms > alpha > Scripts > + New Script.

    Name

    Demo OAuth 2.0 authz data extension

    Script Type

    Oauth2 Authorize Endpoint Data Provider

  2. In the new script window, select Language: JavaScript and save the following script:

    (function () {
      var map = new java.util.HashMap()
    
      // Add an arbitrary query string parameter.
      map.put("key", "value")
    
      // Add the IP address if available.
      if (session) {
        map.put("ipAddress", session.getProperty("Host"))
      }
    
      return map
    }());

OAuth 2.0 client

The OAuth 2.0 client profile in this example overrides the Identity Cloud OAuth 2.0 provider settings. This lets you test the script without affecting access tokens issued to other clients.

  1. Create a public OAuth 2.0 client account.

    In the Identity Cloud admin UI, select Applications > + Add Application, and create a new Native / SPA client with the following setting:

    Client ID

    myClient

  2. Add the following settings in the client profile and save your work:

    Sign-in URLs

    https://www.example.com:443/callback

    Scopes

    access

  3. Override OAuth 2.0 provider settings for this client.

    Under Native Consoles > Access Management, select Realms > alpha > Applications > OAuth 2.0 > Clients > myClient, switch to the OAuth2 Provider Overrides tab, update the following settings and save your work:

    Enable OAuth2 Provider Overrides

    Enabled

    Authorize Endpoint Data Provider Plugin Type

    SCRIPTED

    Authorize Endpoint Data Provider Script

    Demo OAuth 2.0 authz data extension

Resource owner

An OAuth 2.0 client requests the access token on behalf of a resource owner.

Create the OAuth 2.0 resource owner account:

  1. In the Identity Cloud admin UI, select Identities > Manage > Alpha Realm - Users > + New Alpha Realm - User and fill the required fields.

  2. Record the username and password.

Test the demonstration

After preparing the demonstration, test your work using HTTP calls to REST endpoints.

The demonstration uses a partial Authorization code grant flow. It validates only the extension to the authorization endpoint and stops before exchanging the code for an access token:

  • The resource owner authenticates to obtain an SSO token.

  • The client relies on Implied Consent being enabled (default). It assumes the resource owner grants the client access.

  • The client requests the authorization code.

Follow these steps:

  1. Authenticate as the resource owner:

    curl \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'X-OpenAM-Username: <resource-owner-username>' \
    --header 'X-OpenAM-Password: <resource-owner-password>' \
    --header 'Accept-API-Version: resource=2.0, protocol=1.0' \
    'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
    {"tokenId":"<resource-owner-tokenId>","successUrl":"/enduser/?realm=/alpha","realm":"/alpha"}
  2. Request the authorization code as the client:

    curl \
    --dump-header - \
    --request POST \
    --Cookie '<session-cookie-name>=<resource-owner-tokenId>' \
    --data 'scope=access' \
    --data 'response_type=code' \
    --data 'client_id=myClient' \
    --data 'csrf=<resource-owner-tokenId>' \
    --data 'redirect_uri=https://www.example.com:443/callback' \
    --data 'state=abc123' \
    --data 'decision=allow' \
    'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize'
    ...
    location: https://www.example.com:443/callback?code=...&ipAddress=IP-address&key=value...
    ...

    The script added ipAddress=IP-address and key=value to the redirect URL in the response.

Use a validated script

Test your authorize endpoint data provider scripts as you did for the demonstration. After validating your script with OAuth 2.0 provider overrides in your test client, you can update the OAuth 2.0 provider configuration to use the script:

  1. Under Native Consoles > Access Management, select Realms > Realm Name > Services > OAuth2 Provider.

  2. Switch to the Plugins tab and edit the following settings:

    Authorize Endpoint Data Provider Plugin Type

    SCRIPTED

    Authorize Endpoint Data Provider Script

    Your script

  3. Save your work.

Available objects

Identity Cloud injects the following objects into the execution context of an OAuth 2.0 authorize endpoint data provider script:

Binding Information

httpClient

An HTTP client for making external HTTP requests.

logger

Write a message to the Identity Cloud debug log.

In Identity Cloud, this corresponds to the am-core log source.

Logger names use the format scripts.OAUTH2_AUTHORIZE_ENDPOINT_DATA_PROVIDER.<script UUID>.(<script name>).

For information about debug logs, refer to Get audit and debug logs.

scriptName

The display name of the script.

session

The user’s session object.

For details, refer to SSOToken.

Copyright © 2010-2024 ForgeRock, all rights reserved.