Consentors in Financial-Grade

Consentors in Financial-Grade



Our article answering the question What is PSD2? discusses the regulatory requirement that users must consent to the amount of money being paid, and to which party, before payment can be taken.

This article explores how to meet this requirement for an Open Banking scenario involving the following parties:

  • Banks act as Account Servicing Payment Service Providers (ASPSPs) and host API endpoints.
  • Merchants and Fintechs act as Third-Party Providers (TPPs) by supplying apps that call the above APIs.
  • Consumers act as Payment Service Users (PSUs) and use apps to access their bank accounts.

Types of Authorization Redirects

In OAuth-secured applications, authorization redirects are most commonly used during the login process. An app externalizes the authentication complexity to an Authorization Server, which issues a general-purpose access token to the application.

It is also possible to use authorization redirects to prompt for user consent. This is often necessary for high privilege operations, such as issuing a payment. In such cases, the unique security features of the Authorization Server can again be used to issue high privilege tokens.

What are Consentors?

The Consentors Developer Article explains the role of consentors and how they are configured in the Curity Identity Server:


Consentors perform additional processing during delegation and token issuance. This can include processing runtime data, capturing the user's consent via external signing systems, then recording consent in a verifiable manner.

The App2App Article explains how a merchant app can meet its Strong Customer Authentication (SCA) requirement via a Bank Login App. The same bank app would then be used to meet the User Consent requirement via a second authorization redirect. This flow typically involves the following high-level components:

Although there are quite a few components involved, all of the difficult security work is externalized. In particular, the merchant app only needs to open a system browser and form an OpenID Connect authorization redirect.

Starting a Payment Transaction

An Open Banking merchant app would typically start by asking the user to select a bank. After which, it would prompt an App2App login. The workflow then continues as illustrated below:

1. User buys productsThe user checks out an item and is asked to select the bank and account for payment.
2. Bank transaction createdThe Merchant API calls the Bank Transactions API to create a transaction in an initial state. These API to API calls use a Mutual TLS back end flow with an eIDAS client certificate.
3. Transaction ID returnedAn identifier is returned from the Bank API, which then becomes a data-sharing mechanism between the merchant and the bank.
4. Merchant App opens system browserThe merchant app opens the system browser with an OpenID Connect authentication request URL. The Transaction ID returned from the bank is appended to a ‘prefix scope’ to form a runtime scope value.
5. Merchant Authorization Server redirectThe system browser then sends a request to the Merchant Authorization Server, which will proxy to the Bank Authorization Server.
6. Redirect response returnedThe Merchant Authorization Server returns a redirect response to the system browser.
7. Bank Authorization Server redirectThe Merchant App’s system browser follows the redirect to start the consentor flow at the Bank Authorization Server.

Note that the Prefix Scope is registered in the Authorization Servers as a value such as transaction- and then assigned to OAuth clients. Any runtime identifier can be appended to the prefix to form the full scope name.

Consentor Workflow

When the authorization redirect reaches the Bank Authorization Server, the user will typically already be signed in, so authentication will be a Single Sign-On event. The consent process then executes and involves the following steps:

1. Consentor invokedThe consentor process executes when configured against the OAuth client in the Bank Authorization Server.
2. Prefix scope processedThe consentor extracts the runtime transaction ID from the prefix scope.
3. Transaction id sent to APIThe consentor calls the Transactions API with the current transaction ID.
4. Consent attributes retrievedThe consentor receives attributes for this transaction to use during the consent process.
5. Signing request createdThe consentor calls the Bank Signing Service to save data for the authenticated user, to be consented to within a short time period.
6. Redirect response returnedA URL to the bank signing app is returned to the system browser running in the Merchant app.
7. Deep link followedThe system browser follows the deep link to invoke the Bank Signing App.
8. Signing App gets signing requestsThe signing app downloads transactions waiting to be signed and presents them to the user. Most commonly, there will only be a single item.
9. User signs transactionThe user formally consents by following prompts to sign the transaction.
10. Proof of consent storedThe signed details are stored in the Bank Signing Service as verifiable proof of consent.

The handover to the signing app occurs when the Merchant App’s system browser renders an initial screen. This gives the user options for launching their mobile banking signing app, which could be installed on a separate device.

Consent Screen

User consent then occurs in the banking app, informing the user how much money is requested and who the merchant is. The user will be asked to submit a signed request to record their consent in a verifiable manner:

Signing App

This illustrates a scenario where the bank uses BankID as their signing solution, though the implementation could be changed to any other strong signing or authentication service.

The Bank Authorization Server will be notified of completion by the Signing Service. The following technical steps then occur to process the consent result and return the user to the Merchant App:

1. Bank Authorization Server notifiedThe Consentor polls the signing service and issues an authorization code when a successful response is received.
2. Signing Details StoredThe Consentor receives details from the signing service, including the user’s ID and name in that system. These details, along with the runtime transaction ID, are stored in the Bank Authorization Server’s security state.
3. Redirect response returnedThe Bank Authorization code is returned to the system browser running in the Merchant App.
4. System browser follows redirectThe system browser sends the Bank Authorization Code to the Merchant Authorization Server.
5. Security state updatedThe Merchant Authorization Server stores the Bank Authorization Code and will use it later, during token issuing.
6. System browser receives resultThe Merchant Authorization Server then issues its own authorization code.
7. System browser closesThe system browser’s work is now complete, so it closes, and the Merchant App receives the Merchant Authorization Code.
8. User returned to Merchant AppMeanwhile, the Bank Signing App returns the user to the Merchant App.

Token Issuing

The standard process of swapping authorization codes for tokens then occurs, as illustrated below. As for the App2App flow, this is handled by returning only an opaque reference token to the merchant app and saving the high privilege bank token in the merchant’s Authorization Server’s state.

1. Merchant App requests tokensThe Merchant App completes its OpenID Connect flow by swapping the authorization code for tokens.
2. Merchant Authorization Server requests tokensThe Merchant Authorization Server retrieves the Bank Authorization Code from its stored state, then sends it to the Bank Authorization Server.
3. Bank Authorization Server issues claimsThe Bank Authorization Server retrieves its stored state and issues an access token. The token claims include the runtime transaction ID and personal details received from the signing service.
4. Bank Authorization Server returns tokensThe Bank Authorization Server then returns the token to the Merchant Authorization Server.
5. Merchant Authorization Server stores stateThe Merchant Authorization Server performs its own token issuing for the Merchant API and stores the high privilege bank access token in its server state.
6. Merchant App receives an opaque access tokenThe Merchant App receives an opaque reference token which it can use to complete the transaction in the Merchant’s back end.

Completing a Payment Transaction

Finally, the merchant app can complete the transaction by sending its reference token to its own back end. The merchant API will then call the Bank Transactions API over Mutual TLS with the high privilege bank access token:

1. Merchant App completes the purchaseThe Merchant App calls its own API to complete transaction processing, using the access token received.
2. API gateway swaps tokensThe merchant’s API gateway uses the phantom token pattern to swap the reference token for a composite token.
3. Merchant API receives composite tokenThe merchant’s API receives both its own JWT and the bank access token.
4. Merchant API calls Bank APIThe bank access token is used to notify the bank to release funds.
5. Bank API verifies claimsThe bank verifies that the transaction exists as an access token claim, since each access token is only valid for one particular transaction.
6. Bank API verifies proof of consentThe bank also verifies that the signing service has recorded user proof of consent for this particular transaction.

Authorization Server Configuration

In both the merchant and bank authorization servers, two different connections will be configured; one for App2App logins and the other for Consent. In the below Curity Identity Server configuration, the Merchant configures a Bank OpenID Connect Authenticator to use for the consent redirect:

Merchant Connection

Similarly, the Bank configures an OAuth Client for a particular merchant to use for consent. The merchant client connections will be created via Dynamic Client Registration, as discussed in the What is Financial Grade? article.

Bank Connection

Video Tutorial

The below video tutorial walks through using consentors in the Curity Identity Server in a step-by-step manner. The associated Curity configuration is also available in the Consentors Github Repository.


Consentors are a mechanism to manage user consent dynamically, deal with runtime money and account details, and provide digitally verifiable proof of this consent. This enables business partners to securely interoperate and receive trusted data while ensuring that the user is in control.

Let’s Stay in Touch!

Get the latest on identity management, API Security and authentication straight to your inbox.

Keep up with our latest articles and how-tos using RSS feeds