Identity providers

Summary

An identity provider (IdP) is a system or service that manages user authentication and consent during the interactive grant process.

Open Payments requires any authorization server that issues interactive grants to integrate with an IdP. 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 ASEs

This page describes the interactive grant flow from the client developer’s perspective. If you’re implementing Open Payments at your institution, refer to Identity provider integration for the full IdP integration guide, including what your auth server must pass to the IdP, what the IdP must display to the resource owner, and how the redirect and hash mechanics work.

What happens from the client’s perspective

When you (the client) request an interactive grant for an outgoing payment, the authorization server returns an interaction URI in addition to the usual continuation URI. From there:

1. Redirect the user to the interaction URI returned by the authorization server.
2. The authorization server starts the interaction and redirects the user to the ASE’s IdP.
3. The user authenticates with their ASE and reviews the transaction details.
4. The user accepts or rejects the request at the IdP.
5. After the interaction completes, the authorization server redirects the user back to the interact.finish URI you supplied in your initial grant request, including a hash parameter and an interact_ref.
6. Verify the hash to confirm the redirect emanated from the authorization server. See Hash verification.
7. Send a Grant Continuation request to the continuation URI to obtain the access token.

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

View full diagram Download diagram