PingAM 7.5.1

Scalable OAuth 2.0 clients

Deployments that have a high number of OAuth 2.0 clients can typically lead to out-of-memory issues. To register and manage clients in a scalable way and reduce the impact on system performance, configure AM to support scalable clients and use the /realm-config/agents/OAuth2Client endpoint to filter query results.

Enable scalable clients

Before you create a high number of clients, configure AM for scalable clients:

  1. Add the advanced server property org.forgerock.am.scalableAgents.enabled and set to true.

    How do I configure advanced server properties?

    1. In the AM admin UI:

      • To configure properties for all instances of the AM environment, go to Configure > Server Defaults > Advanced.

      • To configure properties for a particular instance, go to Deployment > Servers > Server Name > Advanced.

    2. Configure the properties:

      • To add a property, scroll to the end of the page and enter a property name and value in the text fields. Click add ().

      • To edit an existing property, find the property and click the pencil () button. When you are finished, click the tick () button.

    3. Save your changes.

  2. Save your changes. There is no need to restart AM.

Optimise searching

To optimise filtered queries that are performed directly in DS, apply the following indexes to prevent unindexed searches:

  1. For queries that filter on ID, add an equality index and a substring index for the ou attribute. For example:

    dsconfig delete-backend-index \
--backend-name cfgStore \
--index-name ou \
--hostname localhost \
--port 4444 \
--bindDn uid=admin \
--bindPassword password \
--trustAll \
--no-prompt;

dsconfig create-backend-index \
--backend-name cfgStore \
--index-name ou \
--set index-type:equality \
--set index-type:substring \
--hostname localhost \
--port 4444 \
--bindDn uid=admin \
--bindPassword password \
--trustAll \
--no-prompt;

  2. For queries that filter on client attributes, add an equality index and a substring index for the sunKeyValue attribute. For example:

    dsconfig create-backend-index \
--backend-name cfgStore \
--index-name sunKeyValue \
--set index-type:equality \
--set index-type:substring \
--hostname localhost \
--port 4444 \
--bindDn uid=admin \
--bindPassword: password \
--trustAll \
--no-prompt;

  3. For queries that filter on client type, add a big equality index for the sunserviceID attribute. For example:

    dsconfig create-backend-index \
--backend-name cfgStore \
--index-name sunserviceID \
--set index-type:big-equality \
--hostname localhost \
--port 4444 \
--bindDn uid=admin \
--bindPassword password \
--trustAll \
--no-prompt;

  4. After you have applied the indexes, rebuild the indexes. For example:

    rebuild-index \
--rebuildAll \
--baseDN ou=am-config \
--hostname localhost \
--port 4444 \
--bindDn uid=admin \
--bindPassword password \
--trustAll \
--no-prompt;

Filter and page client searches

When you have enabled scalable clients, you can use this endpoint to query clients and return filtered and paged results.

To filter searches, use the _queryFilter parameter with a JSON pointer to narrow results.

For example, to return all clients with an ID that contains 5256:

$ curl \
--request GET \
--header "Accept-API-Version: resource=2.0" \
--header "iplanetDirectoryPro: AQIC5wM…​3MTYxOA..*" \
"https://openam.example.com:8443/openam/json/realms/root/realm-config/agents/OAuth2Client?_queryFilter=_id+co+5256&_pageSize=10"

To update a particular client in the AM admin UI:

  1. Perform one or more REST queries to narrow search results and find the specific client _id.

  2. Go to Applications > OAuth 2.0 > Clients and select any client.

  3. Update the URL in the browser with your client ID, for example:

    https://openam.example.com:8443/openam/ui-admin/#realms/%2Falpha/applications-oauth2-clients/clients/edit/myClientID

  4. Enter or refresh the page.

Learn more about filtering query requests in the REST API.

Querying large numbers of clients returns the first 1000 results. To return all results, specify the _pagedResultsCookie parameter to use a cookie to page through the results:

  1. Perform an initial query with _pageSize=10 to retrieve the cookie (pagedResultsCookie).

    The resource version must be set as 2.0 in the header.

    For example:

    $ curl \
--request GET \
--header "Accept-API-Version: resource=2.0" \
--header "iplanetDirectoryPro: AQIC5wM…​3MTYxOA..*" \
"https://openam.example.com:8443/openam/json/realms/root/realm-config/agents/OAuth2Client?_queryFilter=true&_pageSize=10"
{
  "result": [
   …​
  ],
  "resultCount": 10,
  "pagedResultsCookie": "eyAiZGVmY…​QiIHB",
  "totalPagedResultsPolicy": "ESTIMATE",
  "totalPagedResults": "500000",
  "remainingPagedResults": -1
}

    The results include an estimated number of results.

  2. Now you can specify the cookie as a parameter to page through the results:

    $ curl \
--request GET \
--header "Accept-API-Version: resource=2.0" \
--header "iplanetDirectoryPro: AQIC5wM…​3MTYxOA..*" \
"https://openam.example.com:8443/openam/json/realms/root/realm-config/agents/OAuth2Client?_pagedResultsCookie=eyAiZGVmY…​QiIHB_queryFilter=true&_pageSize=10"
{
  "result": [
   …​
  ],
  "resultCount": 10,
  "pagedResultsCookie": "eyAiZGVmY…​QiIHB",
  "totalPagedResultsPolicy": "ESTIMATE",
  "totalPagedResults": "500000",
  "remainingPagedResults": -1
}

  3. Continue paging through results until pagedResultsCookie is null, indicating the end of the response.

Advanced settings

The following table describes advanced properties for scalable clients. Only update these settings if you are advised to fine-tune performance.

Advanced server property Description Default value

org.forgerock.am.scalableAgents.searchSizeLimit

Limit the number of results returned when searching for clients using the REST API (UI).

1000

org.forgerock.am.scalableAgents.searchTimeLimit.seconds

Sets a timeout for long-running searches.

5

org.forgerock.am.scalableAgents.cacheSizeLimit

Limits the number of cached clients. Clients are cached when created or subsequently read.

-1 (indicates no limit)

org.forgerock.am.scalableAgents.cacheExpireAfter.seconds

Sets the amount of time to keep clients in the cache.

30