From ffe5a9a46080652379450963be15a2dc755fb32d Mon Sep 17 00:00:00 2001 From: Melissa Henderson <57110301+melissahenderson@users.noreply.github.com> Date: Thu, 4 Jan 2024 08:34:21 -0500 Subject: [PATCH] docs: Some updates for issue #338 (#406) --- docs/src/content/docs/introduction/grants.mdx | 28 +---- .../src/content/docs/introduction/op-flow.mdx | 104 ++++++++++++------ .../partials/diagram-interactive-grant.mdx | 27 +++++ 3 files changed, 103 insertions(+), 56 deletions(-) create mode 100644 docs/src/partials/diagram-interactive-grant.mdx diff --git a/docs/src/content/docs/introduction/grants.mdx b/docs/src/content/docs/introduction/grants.mdx index 512cdcb4..b124b8db 100644 --- a/docs/src/content/docs/introduction/grants.mdx +++ b/docs/src/content/docs/introduction/grants.mdx @@ -2,6 +2,8 @@ title: Grant negotiation and authorization --- +import Interactive from '/src/partials/diagram-interactive-grant.mdx' + import { CodeBlock, LinkOut, @@ -99,28 +101,4 @@ Open Payments requires the use of an identity provider (IdP) during an - -{/* prettier-ignore */} ->Authorization server (AS): Sends interactive grant request - Authorization server (AS)-->>Client instance: 200 returns interact redirect uri and continue uri - Client instance->>Authorization server (AS): Navigates to interact redirect uri - Authorization server (AS)->>Authorization server (AS): Starts interaction and sets session - Authorization server (AS)-->>Client instance: 302 temporary redirect to identity provider
uri with grant info in query string - Client instance->>Identity provider (IdP): Redirects to identity provider - Identity provider (IdP)->>Identity provider (IdP): Resource owner (e.g. client end-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 url
(defined in initial grant request)
secured with unique hash and
interact_ref in query string - Identity provider (IdP)->>Client instance: Follows redirect - Client instance->>Client instance: Verifies hash - Client instance->>Authorization server (AS): Sends grant continuation request with
interact_ref in body to continue uri - Authorization server (AS)->>Client instance: 200 returns grant access token -`} -/> - - + diff --git a/docs/src/content/docs/introduction/op-flow.mdx b/docs/src/content/docs/introduction/op-flow.mdx index 44901602..151f1fe9 100644 --- a/docs/src/content/docs/introduction/op-flow.mdx +++ b/docs/src/content/docs/introduction/op-flow.mdx @@ -2,90 +2,135 @@ title: Open Payments flow --- -import { MermaidWrapper, Mermaid } from '@interledger/docs-design-system' +import { + MermaidWrapper, + Mermaid, + LinkOut +} from '@interledger/docs-design-system' +import Interactive from '/src/partials/diagram-interactive-grant.mdx' -This page describes the Open Payments flow at a high level. The sequence diagrams are for illustrative purposes and are not an exact representation of the flow. +This page describes the Open Payments flows at a high level. The sequence diagrams are for illustrative purposes and might not be an exact representation of a given flow. -## Basic flow +## Get account details -In this flow, assume the client's end-user is the payer and that the client already has the payer's OP-enabled account details (e.g, wallet address). - -1. The client, acting on behalf of the end-user, retrieves public information about the payee’s OP-enabled account by making a call to the payee's wallet address. The client receives an authorization server URL to use when requesting grants. +A client can retrieve public details about an Open Payments-enabled account by issuing a GET request to the account's wallet address. Details include the asset code and scale of the underlying account and the authorization server endpoint to call for grant requests. >PAW: GET wallet address - PAW->>C: 200 Wallet address found, returns public info incl. auth server + C->>WA: GET wallet address url (e.g. https://wallet.example.com/alice) + WA->>C: 200 wallet address found, return public account details `} /> -2. The client requests/receives a grant from the payee's authorization server to create an `incoming-payment` resource. The client then sends a request to the payee-side resource server to create the resource. When created, the resource server returns unique payment details the client will use to address one or more payments to the payee. +## Basic payment flow + +### Assumptions + +- The client's end-user is the payer. +- The client already has the payer's OP-enabled account details and is able to send payments on behalf of the payer. +- The client has issued a GET request to the payee's wallet address and received the authorization server and resource server URLs. + +### Incoming payment + +The client first requests/receives a grant from the payee's authorization server to create an `incoming-payment` resource. The client then sends a request to the payee-side resource server to create the resource. When created, the resource server returns unique payment details the client will use to address one or more payments to the payee. authorization server + participant RS as Payee-side
resource server C->>AS: Grant request (POST) with type=incoming-payment AS->>C: 200 OK, returns access token C->>RS: Create incoming payment resource (POST) - RS->>C: 201 Incoming payment created + RS->>C: 201 Incoming payment resource created `} /> -3. The client requests/receives a grant from the end-user's authorization server to create a `quote` resource. The client then sends a request to the end-user's resource server to create the resource. When created, the resource server returns, among other things, a quote `id` and the amount it will cost to make the payment. +### Quote + +The client requests/receives a grant from the end-user's authorization server to create a `quote` resource. The client then sends a request to the end-user's resource server to create the resource. When created, the resource server returns, among other things, a quote `id` and the amount it will cost to make the payment. authorization server + participant RS as Payer-side
resource server C->>AS: Grant request (POST) with type=quote AS->>C: 200 OK, returns access token C->>RS: Create quote resource (POST) - RS->>C: 201 Quote created + RS->>C: 201 Quote resource created + +`} +/> + + + +### Outgoing payment + +Before an outgoing payment resource can be created on the end-user's account, Open Payments requires the client to send an interactive grant request to the authorization server. + +An interactive grant requires explicit consent be collected from the end-user before an access token is issued. While the client must facilitate the interaction, the end-user's authorization server and identity provider are responsible for the interface and collecting consent. + +After consent is obtained, the client requests permission to continue the grant request in order to obtain an access token. + + + +Once an access token is acquired, the client can request the creation of the outgoing-payment resource. The setup of the payment is complete and the Open Payments flow ends after the resource is created. + + + +resource server + + C->>RS: Create outgoing payment resource (POST) + RS->>C: 201 Outgoing payment resource created `} /> -4. The client requests an interactive grant from the end-user's authorization server to create an `outgoing-payment` resource. An interactive grant requires that explicit consent from the end-user be collected before an access token is issued. While the client must facilitate the interaction, the end-user's authorization server and [identity provider](/introduction/grants/#identity-providers) are responsible for the interface and collecting consent. +## Get transaction history + +To provide an end-user with their transaction history, the client can retrieve a list of the user's incoming (received) payments and outgoing (sent) payments. >AS: Grant request (POST) with type=outgoing-payment, interact object - AS->>C: 200 OK, returns interaction instructions - C->>AS: Sends end-user to redirect URI to initiate interaction flow + C->>RS: Get list of incoming/outgoing payments
with wallet-address={url of wallet address} + RS->>C: 200 OK `} /> -5. After consent is obtained, the client requests/receives permission to continue the grant request and create the `outgoing-payment` resource. When created, the setup of the payment is complete and the Open Payments flow ends. +Similarly, the client can provide the end-user with details about a specific incoming or outgoing payment. @@ -93,13 +138,10 @@ In this flow, assume the client's end-user is the payer and that the client alre graph={`sequenceDiagram participant C as Client - participant AS as Authorization server - participant IDP as Identity provider + participant RS as Resource server - C->>AS: Grant continuation request (POST) - AS->>C: 200 Success with access token - C->>AS: Create outgoing payment (POST) - AS->>C: 201 Outgoing payment created + C->>RS: Get incoming/outgoing payment with
id={url identifying incoming/outgoing payment} + RS->>C: 200 Payment found `} /> diff --git a/docs/src/partials/diagram-interactive-grant.mdx b/docs/src/partials/diagram-interactive-grant.mdx new file mode 100644 index 00000000..f48ba459 --- /dev/null +++ b/docs/src/partials/diagram-interactive-grant.mdx @@ -0,0 +1,27 @@ +import { MermaidWrapper, Mermaid } from '@interledger/docs-design-system' + + + +{/* prettier-ignore */} +>Authorization server (AS): Sends interactive grant request + Authorization server (AS)-->>Client instance: 200 returns interact redirect uri and continue uri + Client instance->>Authorization server (AS): Navigates to interact redirect uri + Authorization server (AS)->>Authorization server (AS): Starts interaction and sets session + Authorization server (AS)-->>Client instance: 302 temporary redirect to identity provider
uri with grant info in query string + Client instance->>Identity provider (IdP): Redirects to identity provider + Identity provider (IdP)->>Identity provider (IdP): Resource owner (e.g. client end-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 url
(defined in initial grant request)
secured with unique hash and
interact_ref in query string + Identity provider (IdP)->>Client instance: Follows redirect + Client instance->>Client instance: Verifies hash + Client instance->>Authorization server (AS): Sends grant continuation request with
interact_ref in body to continue uri + Authorization server (AS)->>Client instance: 200 returns grant access token +`} +/> + +