diff --git a/modules/ROOT/pages/configure-client-management-openid-task.adoc b/modules/ROOT/pages/configure-client-management-openid-task.adoc index a934cdc5..1811b7de 100644 --- a/modules/ROOT/pages/configure-client-management-openid-task.adoc +++ b/modules/ROOT/pages/configure-client-management-openid-task.adoc @@ -36,7 +36,7 @@ These are examples of client registration URLs, which are determined by your cli The time that elapses before a client provider request times out. The minimum value is five seconds. The maximum value is 20 seconds. + [NOTE] -Anypoint Platform makes an HTTP call to the configured OIDC endpoints, and if there is no response after five seconds, the HTTP call times out. +Anypoint Platform makes an HTTP call to the configured OIDC endpoints. If there is no response within the configured timeout period, the HTTP call times out. + .. Select *Advanced Settings* for these options: * *Disable server certificate validation* @@ -47,7 +47,10 @@ Disables server certificate validation if your OpenID client management instance Enables deletion of clients created with this integration. * *Enable client deletion and updates in IdP* + -To use this option, you must also select the *Enable client deletion in Anypoint Platform* option. This option enables you to update and delete external clients in the configured IdP through an outbound call made by Anypoint Platform to `{clientRegistrationUrl}/{clientID}`. The `clientRegistrationUrl` is the value you configured in *Client Registration URL*. For example: `+https://identity.example.com/oauth2/connect/register/6779ef20e75817b79602+`. +To use this option, you must also select the *Enable client deletion in Anypoint Platform* option. This option enables you to update and delete external clients in the configured IdP through an outbound call made by Anypoint Platform to `{clientRegistrationUrl}/{clientID}`. The `clientRegistrationUrl` is the value you configured in *Client Registration URL*. For example: `+https://identity.example.com/oauth2/connect/register/6779ef20e75817b79602+`. +* *Use registration credentials for client management* ++ +When enabled, Anypoint Platform automatically uses RFC 7592 registration credentials if your IdP provides them during client registration. If the IdP returns `registration_access_token` and `registration_client_uri`, these credentials are used for direct client management. Otherwise, the existing client management mechanism is used. . In *Authentication Method*, complete the information for the type of authentication to use for this client provider: * *Authorization Header* + @@ -71,10 +74,7 @@ This is the cryptographic key in PEM format used by Anypoint Platform to sign th + The client API scopes define the specific permissions granted to the token client with the scopes to register new clients. . Enter the information for the *Token Introspection Client*: -* *Client ID*: The client ID for an existing client in your IdP capable of introspection of _all_ tokens from all clients. - *** For Okta, this value is a "Confidential" client. - *** For ForgeRock, this value is a "Confidential" client. - *** For Salesforce, this value is a "Confidential" client. +* *Client ID*: The client ID for an existing client in your IdP capable of introspection of _all_ tokens from all clients. For Okta, ForgeRock, and Salesforce, this must be a Confidential client. * *Client Secret*: The client secret that corresponds to the client ID. . Enter the information for *OpenID Connect Authorization URLs*: * *Authorize URL* @@ -85,18 +85,54 @@ URL where the user authenticates and grants OpenID Connect client applications a URL that provides the user’s identity, encoded in a secure JSON Web Token. . Click *Create*. -After this is successfully configured, you can apply the OpenID Connect OAuth Token Enforcement policy to your API Gateways through API Manager. Requesting API access through API portals dynamically generates client applications in the configured IDP that acts as a token provider. +After this is successfully configured, you can use API Manager to apply the OpenID Connect OAuth Token Enforcement policy to your API Gateways. Requesting API access through API portals dynamically generates client applications in the configured IdP that acts as a token provider. [NOTE] For Okta, the Okta admin must assign the dynamically generated clients to a user or a group of users so they can receive access tokens by sending over the Client ID and Client Secret. -== Client Application Updates and Deletes +[[manage-dynamic-client-registration-and-lifecycle-updates]] +== Manage Dynamic Client Registration and Lifecycle Updates + +Anypoint Platform supports lifecycle management (create, update, and delete) of dynamically registered OAuth2 clients. When you enable the *Use registration credentials for client management* option, Anypoint Platform automatically adapts to your IdP's capabilities: + +* If your IdP returns `registration_access_token` and `registration_client_uri` (as specified in RFC 7592), Anypoint Platform persists these credentials and uses them for direct client updates and deletions through the standard RFC 7592 endpoints. For more information, see https://www.rfc-editor.org/rfc/rfc7592.html[OAuth 2.0 Dynamic Client Registration Management Protocol]. + +* If your IdP doesn't return these registration credentials, Anypoint Platform uses the existing client management mechanism, which allows you to intercept and handle update and delete requests according to your IdP's specific API requirements. + +This adaptive approach ensures that client management works regardless of whether your IdP fully implements the RFC 7592 standard. Backward compatibility is maintained for existing configurations. + +[[enable-client-management]] +=== Enable Client Management + +To enable the registration credentials option: + +. Navigate to *Access Management* and click *Client Providers*. +. Select your configured client provider. +. Under the *Advanced settings* section, select *Use registration credentials for client management*. +. Click *Save*. + +[IMPORTANT] +==== +For consistent client management behavior, create a new client provider when using the *Use registration credentials for client management* option. + +Anypoint Platform captures and saves registration credentials only for clients created after you enable this option. Clients created before enabling this option continue using the existing client management mechanism, while new clients automatically use RFC 7592 credentials if your IdP provides them. This can result in different management behaviors within the same client provider. +==== Okta or another IdP might allow client modification and deletion independently, but this isn't supported on Anypoint Platform. Instead, Anypoint Platform provides and supports hooks so you can implement API calls that are particular to your IdP. -These examples show PUT and DELETE requests that Anypoint Platform makes. +When you enable the *Use registration credentials for client management* option, Anypoint Platform uses the `registration_access_token` and `registration_client_uri` credentials if your IdP returns them during client registration. If your IdP doesn't return these credentials, Anypoint Platform uses the existing client management mechanism. -This is an example of the payload for a PUT (update) request: +* *For IdPs that support RFC 7592:* ++ +If your IdP returns `registration_access_token` and `registration_client_uri` during client registration (such as ForgeRock), Anypoint Platform automatically uses these credentials to make direct RFC 7592-compliant API calls for updates and deletions. + +* *For IdPs with custom APIs:* ++ +If your IdP doesn't return RFC 7592 registration credentials (such as Okta), you can implement custom logic by pointing the *Client Registration URL* to an application under your control. This application can intercept Anypoint Platform's outbound calls and translate them to your IdP's specific API format. + +*Example PUT (update) request that Anypoint Platform sends:* + +[source,http] ---- PUT /oauth2/connect/register/{{client_id}} Accept: application/json @@ -114,31 +150,31 @@ Authorization: Bearer access-token "client_name": "test-client-name" } ---- -* The `Authorization:` header is included as part of the request only if the `Authorization Header` under *Advanced settings* is configured. -* The `client_id` request parameter that's passed is the same as the `client_id` passed in the `PUT` request payload. -* The `token_endpoint_auth_method` passed in the payload is always `client_secret_basic`. -* Only the `Client Registration URL` and `Authorization Header` come from what is configured in OIDC *Client Provider*. -+ -[NOTE] -`client_name` in the request maps to `name` on the inbound side. + -The authorization method depends on the grant type. For example, if the grant type is `implicit`, the `id_token` and `token` are returned. -This example shows another DELETE request header: +This is an example of the DELETE request that Anypoint Platform sends: +[source,http] ---- DELETE /oauth2/connect/register/{{client_id}} Host: identity.example.com Authorization: Bearer access-token ---- -[IMPORTANT] -Neither the `PUT` nor the `DELETE` work if the call is used directly against an IdP. It's intended for interception by pointing to an application under your control, so you can implement the correct deletion and update APIs for their particular provider. +* The `Authorization:` header is included only if you configured the *Authorization Header* under Advanced settings. +* The `client_id` request parameter matches the `client_id` in the PUT request payload. +* The `token_endpoint_auth_method` is always `client_secret_basic`. +* Only the *Client Registration URL* and *Authorization Header* come from your OIDC Client Provider configuration. +* The `client_name` in the request maps to the `name` field on the inbound side. + +Your interception application receives these requests and translates them to the appropriate API calls for your specific IdP. === Update External Clients Via the API -You can use the Access Management API call `PUT /accounts/api/organizations/{orgId}/clientProviders/{clientProviderId}/clients/{clientId}` to update external clients. Use the optional `force` parameter to update Anypoint Platform internal client application records, regardless of whether the update to the external IdP is successful. Using this parameter ensures that the view Anypoint Platform has of the client application is current, even if there are issues communicating with the IdP. +You can use the Access Management API call `PUT /accounts/api/organizations/{orgId}/clientProviders/{clientProviderId}/clients/{clientId}` to update external clients. + +Use the optional `force` parameter to update Anypoint Platform's internal client application records, regardless of whether the outbound update to the external IdP (or your interception application) is successful. Using this parameter ensures that Anypoint Platform's view of the client application is current, even if there are communication issues. -If you don't use the `force` parameter, when updating an external client application via the Anypoint Platform API, Anypoint Platform first attempts to update the Identity Provider (IdP) and then updates its internal records only if the IdP update is successful. +If you don't use the `force` parameter, Anypoint Platform first attempts the outbound update (either directly to the IdP or to your interception application via the configured Client Registration URL) and then updates its internal records only if that outbound update is successful. For more information, see https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/access-management-api/minor/1.0/console/method/%237020/[Access Management API] documentation. @@ -148,7 +184,7 @@ For more information, see https://anypoint.mulesoft.com/exchange/portals/anypoin If you configure the optional *Issuer* field while setting up the OIDC Dynamic Client registration provider, Anypoint Platform autopopulates its UI with all the OIDC grant types supported by the provider, such as `client credentials`, `password`, and more. -To verify the grant types your provider supports, check the provider's discovery endpoint using `__$ISSUER__/.well-known/openid-configuration`, where `_$ISSUER_` is the issuer configured as the provider. +To verify the grant types your provider supports, check the provider's discovery endpoint using `__$ISSUER__/.well-known/openid-configuration`, where `__$ISSUER__` is the issuer configured as the provider. If the client provider supports https://datatracker.ietf.org/doc/html/rfc8414#section-3[RFC 8414, Obtaining Server Metadata] on the `__$ISSUER__/.well-known/oauth-authorization-server` endpoint, the endpoint is discovered and validated before merging grant types with `__$ISSUER__/.well-known/openid-configuration`. This process also enables the use of the Client Credentials grant type for Okta users.