--- title: Scalable OAuth 2.0 clients description: 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. component: pingam version: 8.1 page_id: pingam:am-oauth2:oauth2-scalable-clients canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-scalable-clients.html keywords: ["OAuth 2.0", "OpenID Connect (OIDC)", "Clients", "Setup & Configuration"] page_aliases: ["oauth2-guide:oauth2-scalable-clients.adoc"] section_ids: enable-scalable-clients: Enable scalable clients optimise-searching: Optimise searching scalable-filter-searches: Filter and page client searches scalable-advanced-settings: Advanced settings --- # 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](rest-api-oauth2-client-admin-endpoint.html) endpoint to filter query results. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * This feature requires an [external application store](../setup/setting-up-data-stores.html) when used with file-based configuration (FBC). * When enabled, you can't use the [Secret Label Identifier](oauth2-register-client.html#client-secret-label-identifier) setting if there are more than 1000 clients in a realm. | ## Enable scalable clients If you have a high number of clients, configure AM for scalable clients: 1. Add the advanced server property `org.forgerock.am.scalableAgents.enabled` and set it to `true`. > **Collapse: 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 ([icon: plus, set=fa]). > > * To edit an existing property, find the property and click the pencil ([icon: pencil-alt, set=fa]) button. When you are finished, click the tick ([icon: check, set=fa]) button. > > 3. Save your changes. 2. Save your changes. 3. Although it's not mandatory, it's best practice to restart AM after enabling scalable clients to clear out the AM cache. ## Optimise searching To optimise filtered queries that are performed directly in DS, apply the following indexes to prevent [unindexed searches](https://docs.pingidentity.com/pingds/8.1/config-guide/idx-about.html#unindexed-searches): 1. For queries that filter on ID, add an equality index and a substring index for the `ou` attribute. For example: ```bash 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: ```bash 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: ```bash 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](https://docs.pingidentity.com/pingds/8.1/config-guide/idx-config.html#rebuild-index) the indexes. For example: ```bash 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](#enable-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`: ```bash $ curl \ --request GET \ --header "Accept-API-Version: resource=2.0" \ --header "iPlanetDirectoryPro: AQIC5wM…​3MTYxOA..*" \ "https://am.example.com:8443/am/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: ```none https://am.example.com:8443/am/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](../am-rest/rest-intro.html#about-crest-query). | Querying large numbers of clients returns the first 1000 results. To return all results, specify the [`_pagedResultsCookie`](../am-rest/rest-intro.html#about-crest-query) 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: ```bash $ curl \ --request GET \ --header "Accept-API-Version: resource=2.0" \ --header "iPlanetDirectoryPro: AQIC5wM…​3MTYxOA..*" \ "https://am.example.com:8443/am/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: ```bash $ curl \ --request GET \ --header "Accept-API-Version: resource=2.0" \ --header "iPlanetDirectoryPro: AQIC5wM…​3MTYxOA..*" \ "https://am.example.com:8443/am/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](../setup/server-advanced.html) 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` |