Identity provider integration

When the IdP is involved

Open Payments requires an interactive grant for outgoing payments. An interactive grant cannot be approved without explicit consent from the resource owner (typically the client’s user). The ASE’s authorization server is responsible for orchestrating consent collection, but it must not collect consent itself. It delegates that to an IdP so that the resource owner authenticates against the same system that controls their underlying account.

The following diagram illustrates the full interactive grant flow, including the IdP.

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 authorization server passes to the IdP

When the authorization server forwards the resource owner to the IdP, it must pass enough information for the IdP to display a meaningful consent screen and route the decision back. The exact mechanism is an ASE implementation detail (a signed redirect URL, a short-lived consent token, a back channel call), but the information the IdP needs includes:

The grant identifier, so the IdP can return its decision to the right grant.
The resource owner identity (or whatever the IdP uses to start authentication), so the IdP can prompt the correct user to log in.
The requested access: resource types, actions, limits (debit amount, receive amount, expiry, interval for recurring access).
The client identity: at minimum a display name.
The return path to the authorization server once a decision is made.

What the IdP must display

The IdP is the only system in the flow that the resource owner is authenticated against, so it is also the only system that can credibly ask for consent. The IdP must show:

Who the client is (display name; optionally additional client attestation).
What the client is asking permission to do, in plain language (for example, “send up to $50 USD from your account”).
Any time or velocity limits attached to the request.
A clear accept/deny choice.

ASEs decide the exact UI, but the consent prompt must accurately reflect what the authorization server will encode in the resulting grant. If the IdP under-represents the requested access (for example, by omitting a interval), the grant must be denied or the access scaled down to what the user actually saw and accepted.

After the resource owner makes a choice, the IdP communicates it back to the authorization server. Common patterns:

A signed redirect from the IdP to a callback on the authorization server, carrying the grant identifier and the decision.
A back channel API call from the IdP to the authorization server.

The authorization server must verify the integrity of the incoming decision, both that it came from the ASE’s IdP and that it has not been altered. On accept, the authorization server moves the grant to approved and unlocks token issuance. On deny, the grant must be moved to a terminal denied state so that subsequent continuation requests return the appropriate error.

Redirect and hash mechanics

Once the authorization server has the IdP’s decision, it redirects the resource owner back to the client’s interact.finish URI (if one was provided in the original grant request) and includes:

An interact_ref.
A hash computed from the original nonce values and the grant URI.

The client verifies the hash to confirm that the redirect actually came from the authorization server, then calls the continuation URI to retrieve the access token. The exact hash construction is described in Security.

Reference implementation

Rafiki provides a reference

authorization service

implementation that includes support for integration with an IdP.