Details on provisioning handler implementation to keep all system roles without being deleted during the provisioning process

Description:
WSO2 API Manager has the capability to configure external Identity Providers (Identity Server, Okta, Keycloak, etc) for Single-Sign-On. When Just in time provisioning is enabled, the user details will be saved in the API Manager user store and will update the user profile details during every login via the federation flow.

Hence, there is a possibility to delete the previously assigned system roles (Application/, Workflow/) during the next login attempt.

But there are flows (for application retrieval in the developer portal, etc) in which system roles are required and need to preserve in the provisioned user profile. SystemRolesRetainedProvisionHandler [1] is implemented to achieve the above requirement.

It would be better if a note can be added to the respective documentation [2], [3], etc mentioning the capability of the above handler along with details on how to enable the handler.

In order to enable the "SystemRolesRetainedProvisionHandler" in the APIM-3.2.0 version, it is required to add the below configuration in the <APIM_HOME>/repository/conf/deployment.toml file and restart the server.

[authentication.framework.extensions]
provisioning_handler = "org.wso2.carbon.identity.application.authentication.framework.handler.provisioning.impl.SystemRolesRetainedProvisionHandler"

Affected Product Version:
APIM-3.2.0

Related Issues:
https://github.com/wso2/product-apim/issues/9290

[1] https://github.com/wso2/carbon-identity-framework/blob/master/components/authentication-framework/org.wso2.carbon.identity.application.authentication.framework/src/main/java/org/wso2/carbon/identity/application/authentication/framework/handler/provisioning/impl/SystemRolesRetainedProvisionHandler.java
[2] https://apim.docs.wso2.com/en/latest/install-and-setup/setup/sso/okta-as-an-external-idp-using-oidc/
[3] https://apim.docs.wso2.com/en/latest/develop/extending-api-manager/saml2-sso/configuring-identity-server-as-idp-for-sso/