External consent user interface
As use cases evolve and give users more control over their data, it is important to provide detailed information about the requests. In addition to scope and authorization detail descriptions, PingFederate supports the use of an external web application to prompt for authorization consent.
An external web application provides the opportunity to retrieve additional information specific to the users. For example, if a client requests the read_bank_account scope, the web application can retrieve the user’s customer information file and give the user the ability to choose which accounts to be made available to the client.
Authorization details are used in a similar way as scopes. For information about authorization details, see OAuth rich authorization requests.
To use an external web application for consent approval, configure the Consent User Interface setting:
-
Go to System → OAuth Settings → Authorization Server Settings.
-
For the Consent User Interface setting, select External.
-
Select an External Consent IdP Adapter.
-
Select an External Consent Scopes Attribute, or an External Consent Authorization Details Attribute, or one of each.
Responsibilities of the external web application
Delegating consent approval to an external web application implies that PingFederate can trust the web application. PingFederate expects this trusted web application to fulfill the following responsibilities:
-
Retrieve from PingFederate the list of requested scopes and authorization details in a secure manner.
For example, when integrating the web application with PingFederate through an instance of the Reference ID Adapter, such communications occur through a direct connection between the web application and PingFederate. This back-channel connection is protected by authentication and encryption (HTTPS).
-
Provide to the resource owner the information associated with the list of requested scopes and authorization details, and the user interface elements to approve or deny them.
-
Validate that the approved scopes and authorization details found in the response from the resource owner do not exceed the requested scopes and authorization details.
This validation guards against unauthorized access in the event that the response is tampered with and the original approved scopes and authorization details are compromised.
-
As needed, modify the approved scopes and authorization details before returning them to PingFederate.
This allows the web application to override authorization decisions.
-
Return the list of approved scopes and authorization details to PingFederate in a secure manner.
Handling of approved scopes and authorization details
By default, PingFederate handles consent approval by presenting the Request for Approval page to the resource owner. Upon receipt of the response from the resource owner, PingFederate validates that the approved scopes and authorization details do not exceed those requested. If the validation passes, PingFederate adds the approved scopes and authorization details to the access token. Otherwise, PingFederate returns an invalid_scope error or invalid_authorization_details error.
When an external consent user interface is enabled, PingFederate delegates consent approval to an external web application. As PingFederate trusts this web application, it always adds the scopes and authorization details returned by the trusted web application to the access token, regardless of whether the returned scopes and authorization details have already been defined in the system. The issuance of the access token is still subject to the criteria defined in the grant mapping configuration, the token mapping configuration, or both. For more information, see Grant contract mapping and Token mapping.