Identity provider (IdP)

An identity provider (IdP) is a system or service that stores and manages user identity information, authentication, and consent. Examples of IdPs include OpenID Connect and Okta.

Integration with an IdP is required if you plan to support outgoing payments via Open Payments. The Open Payments standard requires interactive outgoing payment grant requests, which precede outgoing payment requests. In an interactive grant request, explicit interaction by an individual (e.g., the client’s end-user) is required to approve the grant. An example of an interaction is an end-user tapping Approve in an app to authorize a payment.

Your IdP will:

• Authenticate requests from clients, such as mobile apps, to create quotes and payments on Rafiki’s backend
• Facilitate interactions with the client’s end-user to gather consent

Note

We provide Ory Kratos, a cloud-based user management system, for the identity and user management of your Rafiki Admin users. Kratos is for internal use only and cannot be used as your client-facing IdP.

Interactions and consent

Before an outgoing payment is created via Open Payments, an outgoing payment grant must be issued.

Outgoing payment grant requests must be interactive. This means the request requires explicit interaction, often from the a client’s end-user, to gather consent (permission) before creating the outgoing payment. The interaction is facilitated by your IdP.

Your IdP:

1. Provides an interface to gather consent (for example, a consent screen)
2. Sends the interaction choice (accept/deny) to your authorization server
3. Sends a request to your authorization server to finish the interaction
4. Redirects the user after the interaction is complete

Authorization server

The purpose of an Open Payments authorization server is to grant permission to clients to access the Open Payments APIs. These APIs are used to create incoming payments, quotes, and outgoing payments against an account holder’s account.

Rafiki’s auth service provides you with a reference implementation of an Open Payments authorization server. You can use the service as an alternative to developing your own in-house service.

The authorization server extends an HTTP API for your IdP to use to start and finish interactions, collect authorization, get information about a grant, and communicate whether an end-user has authorized a grant. The API’s endpoints are described below.

Environment variables

The following backend variables must be configured on your authorization server.

Variable	Helm value name	Default	Description	Required
IDENTITY_SERVER_URL	auth.identityServer.domain	N/A	Your IdP server’s URL where your authorization server will direct clients to so end-users can complete the interaction and authorize a grant.	Y
IDENTITY_SERVER_SECRET	auth.identityServer.secret	N/A	A shared secret between your authorization and IdP servers that your authorization server will use to secure its IdP-related endpoints. When your IdP sends requests to your authorization server, your IdP must provide the secret via an x-idp-secret header.	Y
INCOMING_PAYMENT_INTERACTION	auth.interaction.incomingPayment	false	Indicates whether incoming payments grant requests are interactive.	Y
INTERACTION_EXPIRY_SECONDS	auth.interactionExpirySeconds	600	The time in seconds for which a user can interact with a grant request	Y
INTERACTION_PORT	auth.port.interaction	3009	The port number for the interaction endpoints	Y
INTROSPECTION_PORT	auth.port.introspection	3007	The port number of your Open Payments authorization token introspection server	Y
LIST_ALL_ACCESS_INTERACTION	N/A	true	Specifies whether grant requests including a list-all action should require interaction. In these requests, the client asks to list resources that they themselves did not create.	Y

Manage grants

After a pending grant request is created, your IdP server can use the interaction endpoints listed below to:

• Start and finish interactions
• Collect authorization
• Get information about a grant
• Communicate whether an end-user has authorized a grant

Each interaction is identified by an id and a nonce. Both are provided as query parameters when your authorization server redirects to your IdP server.

The endpoints are appended to the IDENTITY_SERVER_URL you defined when configuring your environment variables.

Example

https://idp.wallet.example.com/interact/{id}/{nonce}

Interaction endpoints

The endpoints are called in the sequence listed below.

Method	Endpoint	Purpose
GET	/interact/{id}/{nonce}	Start user interaction session
GET	/grant/{id}/{nonce}	Look up grant information
POST	/grant/{id}/{nonce}/{choice}	Accept or reject grant
GET	/interact/{id}/{nonce}/finish	Finish user interaction
POST	/interact/{id}/{nonce}	Continue grant

We also provide an OpenAPI specification that describes the endpoints.

Start user interaction session

Called by the client to establish an interactive session with your authorization server. Also redirects the client’s browser session to your IdP consent screen.

Look up grant information

Called by your IdP server, and secured with an x-idp-secret header, to get the list of access rights the client requested from your authorization server.

The access rights are presented to the client’s end-user on the consent screen. The authorization server’s response is served on your defined INTERACTION_PORT.

Accept or reject grant

Called by your IdP server, and secured with an x-idp-secret header, to communicate the choice made by the end-user on the consent screen (accept/deny) to your authorization server.

Your IdP server then redirects to the finish endpoint. The response is served on your defined INTERACTION_PORT

Finish interaction

Called by your IdP server to end the interaction and redirect the end-user’s browser session to the URI of the grant initialization request.

The result query parameter will indicate the success or failure of the grant authorization. When successful, the SHA-256 hash of the interaction is sent in the response along with an interact_ref that identifies the interaction on your authorization server and the URI of the grant initialization request.

The following are examples of the possible response types.

Response	Description	Example
Rejected	The interaction was rejected by the end-user.	?result=grant_rejected
Invalid	The grant was not in a state where it could be accepted or rejected (e.g., grant was already approved)	?result=grant_invalid
Success	The grant was successful with the following returned in the response: A hash representing the SHA-256 hash of values provided by the client in the grant initialization request (interact.finish.nonce), and the values in the response returned from your authorization server (interact.finish). The interact_ref that identifies the interaction on your authorization server alongside the hash The URI of the grant initialization request (e.g., https://www.auth-server.com)	hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A &interact_ref=4IFWWIKYBC2PQ6U56NL1

Continue grant

Called by the client to request a grant from your authorization server if the interaction was successful (accepted). Your authorization server responds with an access token.

x-idp-secret header

The purpose of the x-idp-secret header is to secure communications between your IdP and authorization servers.

The header is used for requests to the following endpoints and its value should be a shared secret known to both entities.

• GET /grant/:id/:nonce
• POST /grant/:id/:nonce/accept
• POST /grant/:id/:nonce/reject

When your IdP server sends requests to your authorization server, your IdP must provide the secret via this header.

To set up the header, set the IDENTITY_SERVER_SECRET on your authorization server environment to a value that is also used to configure your IdP server’s requests to your authorization server.

Sequence diagram

The following diagram provides a high-level view of the flow from when a pending grant request is created through to the authorization server returning an access token to continue a successful (accepted) interaction.

The diagram is for illustrative purposes and is not an exact representation of the flow. Additional information can be found in the Open Payments documentation.

sequenceDiagram
   Client->>Authorization Server: Sends interactive outgoing payment grant request
   Authorization Server-->>Client: HTTP 200 request successful 
   Client->>Authorization Server: Starts user interaction session
   Authorization Server->>Authorization Server: Sets session
   Authorization Server-->>Client: HTTP 302 instructs client to redirect to Identity Provider
   Client->>Identity Provider: Redirects end-user's browser to the Identity Provider's consent screen
   Identity Provider->>Identity Provider: End-user accepts interaction
   Identity Provider->>Authorization Server: Provides end-user's interaction choice
   Authorization Server-->>Identity Provider: 202 HTTP choice accepted
   Identity Provider->>Authorization Server: Instructs server to finish interaction
   Authorization Server->>Authorization Server: Ends session
   Authorization Server-->>Identity Provider: 302 HTTP instructs Identity Provider to redirect to client
   Identity Provider->>Client: Redirects to Client
   Client->>Client: Verifies hash
   Client->>Authorization Server: Requests continuation of grant
   Authorization Server->>Client: 200 HTTP OK, returns access token

View full diagram