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.

To use an external web application for consent approval, configure the Consent User Interface setting in System > OAuth Settings > Authorization Server Settings. Select the External option and then configure the External Consent IdP Adapter and External Consent Scopes Attribute settings accordingly.

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 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 before returning them to PingFederate.

    This allows the web application to override authorization decisions.

  • Return the list of approved scopes to PingFederate in a secure manner.

Handling of approved scopes

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 the validation passes, PingFederate adds the approved scopes to the access token. Otherwise, PingFederate returns the invalid_scope error to the client.

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 returned by the trusted web application to the access token, regardless of whether the returned scopes 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.