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 OAuth Server > Authorization Server Settings 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 PingFederate.

    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.