Grant negotiation and authorization

In Open Payments, a grant indicates a transfer, or delegation, of authorization from a resource owner (RO) to a piece of software. An RO can be a physical person, such as the software’s end user, or a process, such as predefined organizational rules. By delegating authorization, the RO allows the software to access and perform operations on protected resources on the RO’s behalf.

Open Payments leverages the Grant Negotiation and Authorization Protocol (GNAP) as the mechanism by which the piece of software, known as a client instance (or client for short), is delegated authorization to use the Open Payments API to interface with supported accounts.

GNAP vs OAuth 2.0

GNAP is being developed as the successor to OAuth 2.0 and is designed to fill many of the gaps discovered through the use of OAuth in Open Banking and other financial use cases. Appendix B in the GNAP specification outlines ways in which the protocol’s design differs from OAuth 2.0. Some examples include:

GNAP	OAuth 2.0
The client declares the different ways it can start and finish an interaction, and these can be mixed together as needed for different use cases; interactions can use a web browser, but don’t have to	The type of interaction available is fixed and dictated by the grant type; assumes the end-user has access to a web browser
Allows the entity requesting access to protected resources to be different from the resource owner, but still works in the optimized cased of them being the same party	Assumes the end-user is the same user that will interact with the authorization server to approve access; assumes the resource owner is the person who requested the grant
Allows the client to present an unknown key to the authorization server and use that key to protect the ongoing request	Requires all clients to be registered at the authorization server and use a client_id known to the authorization server
Always starts at the same endpoint at the authorization server	Different grant types start at different endpoints
A client can ask for multiple access tokens in a single grant request	A client can only ask for a single access token in a single request

Grant authorization servers

An authorization server (AS) grants delegated privileges to a client in the form of access tokens. Access tokens represent a set of access rights and/or attributes granted to the client. With the requisite access token(s), the client can access a resource server’s (RS) Open Payments API and perform allowed operations, such as creating incoming payments and listing outgoing payments, on behalf of the resource owner.

An AS is uniquely identified by its grant endpoint URI, which is an absolute URI that a client calls to initiate a grant request.

Key registries

A key registry is a list of keys associated with clients requiring access to protected Open Payments resources. Key registries are publicly exposed via a jwks.json endpoint and allows an AS to verify that a client is who it says it is.

A client must generate and add its key to its key registry before requesting a grant for the first time. For more information on key generation and registration, as well as how key registries work with authorization servers, refer to the Client keys page.

Grant requests

Before a client can access the Open Payments API, it must send a grant request to the AS. The request must contain the type of resource it wants to work with and the action(s) it wants to take on the resource. Resource types include incoming-payment, quote, and outgoing-payment. The available actions depend on type, but examples include create and read. A successful grant request results in the AS returning one or more access tokens.

The sequence of requests a client makes when setting up a payment can follow one of the paths below.

Path 1 (most common)

1. Request an incoming-payment grant from the payee’s AS
2. Send request to create an incoming payment resource to the payee’s RS
3. Request a quote grant from the payer’s AS
4. Send request to create a quote resource to the payer’s RS
5. Request an interactive outgoing-payment grant from the payer’s AS
6. Send request to create an outgoing payment resource to the payer’s RS

Path 2

1. Request an incoming-payment grant from the payee’s AS
2. Send request to create an incoming payment resource to the payee’s RS
3. Request a single interactive grant for both quote and outgoing-payment from the payer’s AS
4. Send request to create a quote resource to the payer’s RS
5. Send request to create an outgoing payment resource to the payer’s RS

Grant types

incoming-payment

A client begins the Open Payments flow by requesting an incoming payment grant from the AS on the payee side. The client can request a single grant to create multiple incoming payments for different OP-enabled accounts as long as each account belongs to the same ASE ? Account servicing entity .

Incoming payment grants are non-interactive by default, meaning interaction by an individual (typically the client’s end-user) is not required for the AS to issue an access token.

quote

After the client receives an incoming payment grant and an incoming payment resource is created on the payee’s account, the client requests a quote grant from the AS on the payer side. The client can request a single grant to create multiple quotes for different OP-enabled accounts as long as each account belongs to the same ASE ? Account servicing entity .

Quote grants are non-interactive by default, meaning interaction by an individual (typically the client’s end-user) is not required for the AS to issue an access token.

outgoing-payment

Having progressed through the incoming payment and quote portions of the Open Payments flow, the client is ready to request an outgoing payment grant from the AS on the payer side.

Open Payments requires outgoing payment grant requests to be interactive. When a grant request is interactive, it means explicit interaction by an individual (typically the client’s end user) is a required step in the delegation process.

After a successful interaction, the client must issue a Grant Continuation request so the AS knows to issue an access token.

Open Payments resource servers

A resource server (RS) provides the Open Payments API through which resources can be created or accessed on the server. GNAP doesn’t presume or require a tight coupling between an RS and an AS and it’s increasingly common for the servers to be run and managed separately.

Operations on the API by a client require the client to have a valid access token issued by a trusted AS. When the client uses its access token to call the RS, the RS examines the token to determine if the token is sufficient for the request. The means by which an RS makes this determination are outside of the scope of Open Payments. If the token is sufficient, the client is given the right to access the operation(s) and resource tied to the token.

Note

An open-source implementation of an Open Payments resource server, called Rafiki, is currently in development.

Identity providers

An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. Open Payments requires any AS that issues interactive grants ? A grant requiring explicit interaction/consent from the resource owner before an access token can be issued be integrated with an IdP.

After an interactive grant request is initiated and the AS sets the session, the AS provides the client with the IdP URI to redirect the end-user to.

sequenceDiagram
    Client instance->>Authorization server (AS): Sends interactive grant request
    Authorization server (AS)-->>Client instance: 200 returns interact redirect uri and continue uri
    Client instance->>Authorization server (AS): Navigates to interact redirect uri
    Authorization server (AS)->>Authorization server (AS): Starts interaction and sets session
    Authorization server (AS)-->>Client instance: 302 temporary redirect to identity provider 
uri with grant info in query string
    Client instance->>Identity provider (IdP): Redirects to identity provider
    Identity provider (IdP)->>Identity provider (IdP): Resource owner (e.g. client end-user) 
accepts interaction
    Identity provider (IdP)->>Authorization server (AS): Sends interaction choice
    Authorization server (AS) -->>Identity provider (IdP): 202 choice accepted
    Identity provider (IdP)->>Authorization server (AS): Requests to finish interaction
    Authorization server (AS)->>Authorization server (AS): Ends session
    Authorization server (AS)-->>Identity provider (IdP): 302 temporary redirect to finish url 
(defined in initial grant request) 
secured with unique hash and 
interact_ref in query string
    Identity provider (IdP)->>Client instance: Follows redirect
    Client instance->>Client instance: Verifies hash
    Client instance->>Authorization server (AS): Sends grant continuation request with 
interact_ref in body to continue uri
    Authorization server (AS)->>Client instance: 200 returns grant access token

View full diagram

Reference implementation

Rafiki provides a reference authorization service implementation that includes support for integration with an IdP.