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.

Open Payments requires any authorization server that issues interactive grants be integrated with an IdP. Interactive grants are used to gather consent. More information about interactive grants is available below.

Responsibilities of your IdP include:

• Providing an interface to gather end-user consent for a particular action
• Sending the interaction choice (approve or deny) to your authorization server
• Sending a request to your authorization server to finish the interaction
• Redirecting the user after the interaction is complete

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 IdP for Open Payments.

Interactive grants

In Open Payments, grants are used to indicate a resource owner, such as an account holder, has given a piece of software, such as a mobile app, permission (consent) to act on their behalf.

Rafiki’s implementation of an Open Payments authorization server requires that consent is collected via an interactive grant before an outgoing payments request is issued. A grant is interactive when explicit interaction by a resource owner (e.g., the software’s end user) is required to approve or deny the grant. Tapping an Approve button to authorize a payment is an example of an explicit interaction.

Interactive grants can be optional for incoming payments and quotes; however, they’re enabled by default in Rafiki (the LIST_ALL_ACCESS_INTERACTION environment variable is true). When a grant request includes a list-all action for incoming payments and quotes, the request requires interaction. The list-all action is used when the client asks to list resources that it did not create.

If LIST_ALL_ACCESS_INTERACTION is false, you can still force interactive grants for quotes by setting QUOTE_INTERACTION to true.

See the Open Payments documentation for more information on grant negotiation and authorization.

Authorization servers

Authorization servers grant permission to clients to access the Open Payments Resource APIs. This enables clients 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. We recommend you use the auth service rather than developing your own in-house solution.

The authorization server also extends an API that provides interaction endpoints for your IdP.

Environment variables

The following variables must be configured for the auth service.

Variable	Helm value name	Default	Description
IDENTITY_SERVER_URL	auth.identityServer.domain	N/A	The URL of your IdP’s server, used by the authorization server to inform an Open Payments client of where to redirect the end-user to start interactions.
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.
INCOMING_PAYMENT_INTERACTION	auth.interaction.incomingPayment	false	Indicates whether incoming payments grant requests are interactive.
INTERACTION_EXPIRY_SECONDS	auth.interactionExpirySeconds	600	The time in seconds for which a user can interact with a grant request
INTERACTION_PORT	auth.port.interaction	3009	The port number for the interaction endpoints
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.
QUOTE_INTERACTION	auth.interaction.quote	false	When true, quote grants are interactive.

Interaction endpoints

The authorization server provided by Rafiki’s auth service extends an API for your IdP server to use after a pending grant request is created.

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

The endpoints are tied to the auth server URL. For example, if your auth server URL is https://auth.wallet.example.com, then calling the /interact/{id}/{nonce} endpoint to start a user interaction session would look as follows:

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

Interaction endpoints

The endpoints are called in the sequence listed below.

Method	Endpoint	Purpose	Called by	Publicly exposed
GET	/interact/{id}/{nonce}	Start user interaction session	Open Payments client	Yes
GET	/grant/{id}/{nonce}	Look up grant information	Identity provider	No
POST	/grant/{id}/{nonce}/{choice}	Accept or reject grant	Identity provider	No
GET	/interact/{id}/{nonce}/finish	Finish user interaction	Identity provider	Yes
POST	/interact/{id}/{nonce}	Continue grant	Open Payments client	Yes

We also provide an OpenAPI specification that describes the endpoints. Note that the Continue grant endpoint is not included in the spec because it’s part of the Open Payments Auth Server API.

Start user interaction session

Called by the client to establish an interactive session with your authorization server. Your authorization server automatically redirects the request, via the URL defined in the IDENTITY_SERVER_URL variable, to your IdP consent screen.

Look up grant information

Called by your IdP server to retrieve a list of access rights, requested by the client, from your authorization server. The request is secured with an x-idp-secret header. The access rights are presented to the client’s end-user on the consent screen. The authorization server’s response is served on your configured INTERACTION_PORT.

Accept or reject grant

Your IdP server communicates the choice made by the end-user on the consent screen (accept/reject) to your authorization server. The request is secured with an x-idp-secret header. Your authorization server responds to your IdP server, acknowledging that it received the quest.

Finish interaction

Called by your IdP server to end the interaction. Your authorization server automatically redirects the end-user’s browser session to the finish endpoint on Rafiki’s auth service, which handles the interaction requests on your defined INTERACTION PORT.

The result query parameter in the response indicates the success or failure of the grant authorization. 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

When successful, the SHA-256 hash of the interaction is sent in the response to the client, along with an interact_ref that identifies the interaction on the authorization server and the URI of the grant initialization request. The client must verify the hash before it will request to continue the grant.

Continue grant

The client requests a grant from your authorization server for an accepted interaction. Your authorization server responds with an access token.

x-idp-secret header

The x-idp-secret header is specific to Rafiki’s authorization server and is used for requests to the following endpoints:

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

The header’s purpose is to secure communications between your IdP and Rafiki’s authorization server. Its value should be a shared secret known to both entities. When your IdP server sends requests to Rafiki’s authorization server, your IdP must provide the secret via this header.

Note

If you’re running your own authorization server rather than using the server provided by Rafiki, you can add security in any way you see fit. You aren’t required to use the x-idp-secret header.

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