As use cases evolves towards giving users more control over their data, it is becoming more important to provide detailed information about the requests. While scope descriptions may help, PingFederate also supports the use of an external web application to prompt for authorization consent. This approach opens up the opportunity to retrieve additional information specific to the users. For example, the web application can be written in such a way that when a client requests the read_bank_account scope, the web application retrieves the user's customer information file and gives the user the ability to choose which account (or accounts) to be made available to the client.
To use an external web application for consent approval, configure the Consent User Interface setting on the screen. (Choose the External option and then configure the External Consent IdP Adapter and External Consent Scopes Attribute settings accordingly.)
Responsibilities of the external web application
From PingFederate's point of view, delegating consent approval to an external web application means that this is a web application that PingFederate can trust. PingFederate expects this trusted web application to take on the following responsibilities:
- Retrieve from PingFederate the list of requested scopes 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 the user interface elements to approve or deny the requested scopes.
- Validate that the approved scopes found in the response from the resource owner do
not exceed the requested scopes.Important:
This validation guards against unauthorized access in the event that the response is tampered and the original approved scopes are compromised.
- As needed, modify the approved scopes prior to returning them to
This flexibility allows the web application to override authorization decisions by modifying the approved scopes before returning them to PingFederate.
- Return to PingFederate the list of approved scopes in a secure manner.
Handling of approved scopes
- Default consent user interface
- 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 do not exceed the requested scopes. If this validation passes,
PingFederate adds the approved scopes to the access token; otherwise, PingFederate
returns an error (
invalid_scope) to the client.
- External consent user interface
- When the option to use an external consent user interface is chosen, PingFederate delegates consent approval to an external web application. Because PingFederate trusts this web application, it always adds the scopes returned by the trusted web application to the access token, regardless of whether the returned scopes have already been defined in the system. That being said, 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 mapping and Token mapping.