docs: fixes #2964 and #2946 (#2977)

* docs: resolves #2964 and #2946 We know the environment variables tables are ugly. We're working on styling. * docs: removed non-idp-specific variable
interledger · Sep 17, 2024 · 46e069d · 46e069d
1 parent 86e0a96
commit 46e069d
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 23 deletions.
diff --git a/packages/documentation/src/content/docs/integration/requirements/idp.mdx b/packages/documentation/src/content/docs/integration/requirements/idp.mdx
@@ -12,7 +12,7 @@ Integration with an IdP is required if you plan to support <LinkOut href="https:
 Your IdP will:
 
 - Authenticate requests from clients, such as mobile apps, to create quotes and payments on Rafiki's backend
-- Facilitate interactions with the individual to gather consent
+- Facilitate interactions with the client's end-user to gather consent
 
 :::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 here as your IdP.
@@ -33,54 +33,65 @@ Outgoing payment grant requests must be interactive. This means the request requ
 
 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](/integration/services/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, acquire 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.
+Rafiki's [auth service](/integration/services/auth-service) provides you with a reference implementation of an Open Payments authorization server. The server extends an [API](#interaction-endpoints) 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.
 
-## Rafiki integration
+## Environment variables
 
-### Environment variables
+The following `backend` variables must be configured on your authorization server.
 
-| Variable                 | Type      | Description                                                                                                                                                                                                                                                               | Required |
-| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| `IDENTITY_SERVER_URL`    | `backend` | The URL of your IdP. This URL is where your authorization server will direct clients to so end users can complete the interaction and authorize a grant.                                                                                                                  | Y        |
-| `IDENTITY_SERVER_SECRET` | `backend` | A shared secret between your authorization server and your IdP that your authorization server will use to secure its IdP-related endpoints.<br/>When your IdP sends requests to your authorization server, your IdP must provide the secret via an `x-idp-secret` header. | Y        |
+| 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.<br/>When your IdP sends requests to your authorization server, your IdP must provide the secret via an [`x-idp-secret`](#x-idp-secret-header) 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](#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        |
 
-### IDENTITY_SERVER_URL endpoints
+## Interaction endpoints
 
-We have a number of endpoints that facilitate communication between your IdP and authorization server after a pending grant request is created.
+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.
+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                                                           |
 | ---------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------- |
 | <Badge text="GET" variant="note" size="medium"/>     | `/interact/{id}/{nonce}`        | [Start user interaction session](#start-user-interaction-session) |
 | <Badge text="GET" variant="note" size="medium"/>     | `/grant/{id}/{nonce}`           | [Look up grant information](#look-up-grant-information)           |
-| <Badge text="GET" variant="note" size="medium"/>     | `/grant/{id}/{nonce}/{choice}`  | [Accept or reject grant](#accept-or-reject-grant)                 |
-| <Badge text="GET" variant="note" size="medium"/>     | `/interact/{id}/{nonce}/finish` | [Finish user interaction](#finish-interaction)                    |
+| <Badge text="POST" variant="success" size="medium"/> | `/grant/{id}/{nonce}/{choice}`  | [Accept or reject grant](#accept-or-reject-grant)                 |
+| <Badge text="GET" variant="note" size="medium"/>     | `/interact/{id}/{nonce}/finish` | [Finish user interaction](#finish-interaction)<br />              |
 | <Badge text="POST" variant="success" size="medium"/> | `/interact/{id}/{nonce}`        | [Continue grant](#continue-grant)                                 |
 
 We also provide an <LinkOut href="https://github.com/interledger/rafiki/blob/main/packages/auth/src/openapi/specs/id-provider.yaml">OpenAPI specification</LinkOut> 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 the IdP consent screen.
+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 to retrieve a list of access rights, requested by the client, from your authorization server. The access rights are presented to the client's end-user on the consent screen. The authorization server's response is served on the `INTERACTION_PORT`, which is `3009` by default.
+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`](#x-idp-secret-header) 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`](#environment-variables).
 
 #### Accept or reject grant
 
-Your IdP communicates the choice made by the end-user on the consent screen (accept/reject) to your authorization server. Then, your IdP redirects to `GET /interact/:id/:nonce/finish`. The response is served on `INTERACTION_PORT`, which is `3009` by default.
+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`](#x-idp-secret-header) header. Then, your IdP server redirects to the `finish` endpoint. The response is served on your defined [`INTERACTION_PORT`](#environment-variables).
 
 #### Finish interaction
 
-Your IdP ends the interaction and redirects the end-user's browser session to the URI of the <LinkOut href="https://openpayments.dev/apis/auth-server/operations/post-request/">grant initialization request</LinkOut>.
+Your IdP server ends the interaction and redirects the end-user's browser session to the URI of the <LinkOut href="https://openpayments.dev/apis/auth-server/operations/post-request/">grant initialization request</LinkOut>.
 
 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 different possible response types on this endpoint.
+The following table lists examples of the possible response types on this endpoint.
 
 | Response | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Example                                                                                                                          |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
@@ -91,3 +102,15 @@ The following table lists examples of the different possible response types on t
 #### Continue grant
 
 The client requests a grant from your authorization server for an accepted interaction. Your authorization server responds with an <LinkOut href="https://openpayments.dev/apis/auth-server/operations/post-continue/">access token</LinkOut>.
+
+## 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`](#environment-variables) on your authorization server environment to a value that is also used to configure your IdP server's requests to your authorization server.
diff --git a/packages/documentation/src/content/docs/integration/services/backend-service.mdx b/packages/documentation/src/content/docs/integration/services/backend-service.mdx
@@ -7,20 +7,20 @@ import Backend from '/src/partials/backend-variables.mdx'
 
 Rafiki’s <LinkOut href="https://github.com/interledger/rafiki/tree/main/packages/backend">`backend`</LinkOut> service is the software’s main service for handling business logic and external communication. The service is responsible for:
 
-- Exposing the endpoints of the [Open Payments APIs](#open-payments) for public clients to perform account management tasks. This is the external communication piece.
+- Exposing the endpoints of the [Open Payments APIs](#open-payments) for public clients to initiate payments and look up information. This is the external communication piece.
 - Exposing an [Interledger connector](#interledger-connector) to send and receive STREAM packets with peers.
-- Enabling you to manage accounts and track balances.
-- Exposing an internal [GraphQL Backend Admin API](#graphql-backend-admin-api) for service operators to manage accounts and application settings, like peering relationships.
+- Enabling you to manage accounts and track liquidity.
+- Exposing an internal [GraphQL Backend Admin API](#graphql-backend-admin-api) for service operators to manage accounts, liquidity, and application settings, like peering relationships.
 
 ## Requirements
 
 The following are required when using the `backend` service.
 
 - A Redis database as a cache to share STREAM connection details and total amounts received across processes
 - A Postgres database, separate from the `auth` service’s database, for Open Payments resources
-- TigerBeetle or a separate Postgres database for accounting balances at the ILP layer
+- TigerBeetle or a separate Postgres database for accounting liquidity
   :::note
-  You can use the same database instance of Postgres for the `backend` service, `auth` service, and accounting balances (if not using TigerBeetle). However, separate database schemas are required within the Rafiki instance to maintain boundaries between the objects being managed.
+  You can use the same database instance of Postgres for the `backend` service, `auth` service, and accounting liquidities (if not using TigerBeetle). However, separate database schemas are required within the Rafiki instance to maintain boundaries between the objects being managed.
   :::
 
 You must also set the environment variables for the `backend` service.