Skip to content
GitHub

Identity provider integration

An interactive grant is a grant that requires explicit user interaction/consent from the resource owner before an access token can be issued. In Open Payments, an interactive grant must be issued before an outgoing payment resource can be created.

For the protocol-level overview of the IdP’s role, refer to Identity providers.

After the interactive grant request begins and the authorization server sets the session, the server provides the client with the IdP URI to which to redirect the user.

The following diagram illustrates the flow of an interactive grant.

sequenceDiagram autonumber
    Client->>Authorization server (AS): POST grant request (with interact object)
    Authorization server (AS)-->>Client: 200 OK, returns interact redirect URI and continue URI
    Client->>Authorization server (AS): Navigates to interact redirect URI
    Authorization server (AS)->>Authorization server (AS): Starts interaction and sets session
    Authorization server (AS)-->>Client: 302 temporary redirect to identity provider 
URI with grant info in query string
    Client->>Identity provider (IdP): Redirects to identity provider
    Identity provider (IdP)->>Identity provider (IdP): Resource owner (e.g. client 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 URI 
(defined in initial grant request) 
secured with unique hash and 
interact_ref in query string
    Identity provider (IdP)->>Client: Follows redirect
    Client->>Client: Verifies hash
    Client->>Authorization server (AS): POST grant continuation request with 
interact_ref in body to continue URI
    Authorization server (AS)-->>Client: 200 OK, returns grant access token

What the auth server passes to the IdP

Section titled “What the auth server passes to the IdP”

When your authorization server redirects the resource owner to your IdP, it must hand over enough context for the IdP to render a meaningful consent prompt. At minimum, this includes:

  • The grant identifier so the IdP can refer back to the specific grant when communicating the resource owner’s choice.
  • The requested permissions:
    • The resource type (outgoing-payment)
    • The actions (create)
    • Any constraints such as expiration
  • The transaction amounts:
    • The debitAmount the resource owner will be charged
    • The receiveAmount the recipient will receive
    • The asset codes/scales for both
  • The recipient identifier (typically the recipient’s wallet address) so the IdP can display who is being paid.
  • The client’s identity: the client’s wallet address (or its public key, for directed identity) so the IdP can display the requesting application.

The exact transport mechanism (signed JWT, server-to-server lookup, signed query parameters) is an implementation detail of your IdP integration.

What the IdP must display

Section titled “What the IdP must display”

Your IdP is responsible for the consent UI. It must clearly present:

  • The transaction details:
    • The amount the resource owner will be charged
    • The amount the recipient will receive
    • The recipient’s identifier.
  • The client identity, so the resource owner knows which application is making the request.
  • The scope of the grant, including any future-dated or recurring authorization the client is requesting.
  • An unambiguous accept/reject choice.

The IdP authenticates the resource owner using whatever mechanism your institution uses for online sessions (passwords, biometrics, hardware tokens). Open Payments does not prescribe the authentication method.

Section titled “How consent flows back to the auth server”

After the resource owner makes their choice, the IdP must communicate the result back to your authorization server. A typical flow:

  1. The IdP sends the resource owner’s interaction choice (accept or reject) to the authorization server.
  2. The authorization server confirms the choice has been accepted and records it on the grant record.
  3. The IdP requests to finalize the interaction.
  4. The authorization server completes the session and prepares the redirect to the client’s interact.finish URI.

Redirect and hash generation

Section titled “Redirect and hash generation”

If the client supplied an interact.finish object in its initial grant request, your authorization server redirects the resource owner’s user agent back to the client’s callback URI after the interaction completes. To allow the client to confirm that the redirect originated from your authorization server, you must include a hash parameter in the redirect.

The hash base is generated by concatenating the following values in sequence using a single newline (\n) character to separate them:

  1. nonce value sent by the client in the initial request.
  2. nonce value returned from the authorization server after the initial grant request.
  3. interact_ref returned from the authorization server in the interaction finish method.
  4. The grant endpoint uri the client used to make its initial request.

The ASCII encoding of this string is hashed with the sha-256 algorithm, which is the only hashing algorithm currently supported by Open Payments. The byte array from the hash function is then encoded using Base64 with no padding. The resultant string is the hash value you include in the redirect.

The client verifies this hash before continuing the grant. The client-side procedure is described on the Hash verification page.