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 Open Payments outgoing payments for your users. Open Payments requires that outgoing payment grant requests, which precede outgoing payment requests, be interactive. In an interactive grant request, explicit interaction by an individual (e.g., an account holder) is required to approve the grant. An example of an interaction is an end-user tapping an Approve button 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

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

Outgoing payment grant requests must be interactive. This means the request requires explicit interaction, often from the account holder, to gather consent (permission) to create the outgoing payment. The interaction is facilitated by your IdP. Your IdP:

Provides an interface to gather consent, for example, a consent screen
Sends the interaction choice to your authorization server
Sends a request to your authorization server to finish the interaction
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 for creating 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. The server extends an API for your IdP to use to begin and finish an interaction, collect authorization, get information about a particular grant, and communicate that a user has authorized a grant. You can use the service as an alternative to developing your own in-house service.

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

Interaction endpoints

Your Open Payments authorization server 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 server.

The endpoints are tied to the IDENTITY_SERVER_URL you defined when configuring your environment variables. For example, if your identity server URL is https://idp.wallet.example.com, then to start a user interaction session, the /interact/{id}/{nonce} endpoint would be called:

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

The endpoints are called in the sequence listed in the table 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 and establishes an interactive session with your authorization server, which redirects the client’s browser session 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 defined 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. Then, your IdP server redirects to the finish endpoint. The response is served on your defined INTERACTION_PORT.

Finish interaction

Your IdP server ends the interaction and redirects 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. In case of success, the SHA-256 hash of the interaction is sent in the response along with an interact_ref that identifies the interaction on the authorization server and the URI of the grant initialization request.

The following table lists examples of the possible response types on this endpoint.

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

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

x-idp-secret is the name of a header that 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 authorization servers and its value should be a shared secret known to both entities. 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.