docs: Issuer Adapter

- define WACI flow and APIs - issuer integration docs Signed-off-by: Rolson Quadras <[email protected]>
trustbloc · Feb 11, 2022 · 85fc940 · 85fc940
1 parent b6414e6
commit 85fc940
Show file tree

Hide file tree

Showing 5 changed files with 193 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ operations. The edge-adapter uses the capabilities provided by [Hyperledger Arie
 such as DIDComm, [W3C Verifiable Credentials(VC)](https://w3c.github.io/vc-data-model/), [W3C Decentralized Identifiers(DIDs)](https://w3c.github.io/did-core/), etc.
 
 The Adapter contains following components.
-- [Issuer Adapter](./docs/issuer/v0.1.7/README.md)
+- [Issuer Adapter](./docs/issuer/README.md)
 - [Relying Party (RP) Adapter](./docs/rp/README.md) 
 
 The TrustBloc Adapters provide support for DIDComm to go through a router using [Blinded Routing](./docs/blinded_routing.md) feature. 

diff --git a/docs/issuer/README.md b/docs/issuer/README.md
@@ -0,0 +1,14 @@
+# Issuer Adapter
+
+The Issuer Adapter enables standard REST API flows on top of DIDComm. It exposes REST APIs and 
+transparently handles the mechanics of DIDComm on behalf of issuers. Behind the scene, Issuer Adapter 
+uses [DIF Wallet And Credential Interaction with DIDComm v2](https://identity.foundation/waci-presentation-exchange/) 
+specification to communicate with Wallet.
+
+![overview](./issuer_adapter_overview.svg)
+
+## Components
+- [Issuer Adapter](../../cmd/adapter-rest)
+
+## Integration
+- [Issuer](./integration/issuer.md)
diff --git a/docs/issuer/integration/issuer.md b/docs/issuer/integration/issuer.md
@@ -0,0 +1,167 @@
+# Integration Guide for Issuers
+
+## Purpose of this document
+
+This document serves as a guide for integrating REST APIs with Issuer Adapter. Issuer Adapter acts as 
+a [OpenID Connect 1.0](https://openid.net/specs/openid-connect-core-1_0.html) client when interacting with 
+the Issuer. The reader is expected to be familiar with OIDC and the OAuth2 authorization code flow.
+
+## Flow diagram
+TODO
+
+## Steps
+Follow these steps to integrate as a Issuer:
+
+1. [Register a client/profile](#register-a-clientprofile)
+2. [Redirect the user to Adapter API](#redirect-the-user-to-adapter-api)
+3. [Handle Auth Request](#process-auth-callback)
+4. [Support Data Endpoint](#process-user-data-call)
+5. [Handle Post process redirect](#handle-success-page)
+
+### Register a Client/Profile
+
+Register a client/profile with Issuer adapter.
+
+**Request:**
+
+```jsonc
+HTTP POST <issuer-adapter-url>/profile
+
+{
+    "id": "tb-prc-issuer1",
+    "name":"TrustBloc Demo - Permanent Resident Card Issuer",
+    "url": "https://demo-issuer.sandbox.trustbloc.dev/didcomm",
+    "oidcProvider": "https://hydra.sandbox.trustbloc.dev/",
+    "scopes": [
+        "PermanentResidentCard"
+    ],
+    "supportedVCContexts": [
+        "https://w3id.org/citizenship/v1"
+    ],
+    "supportsWACI": true,
+    "linkedWallet": "https://wallet.sandbox.trustbloc.dev/waci"
+}
+```
+
+| Parameter           | Type             | Description                                                                                                                               | Required                | Default |
+|---------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|---------|
+| id                  | string           | unique profile id                                                                                                                         |                         |         |
+| name                | string           | Issuer name                                                                                                                               | Y                       |         |
+| url                 | string           | Issuer callback URL base                                                                                                                  | Y                       |         |
+| scopes              | array of strings | The list of supported scopes. See notes on [available scopes](#available-scopes) for how to discover the scopes supported by the adapter. | Y                       |         |
+| supportsWACI        | bool             | Enable WACI flow with Wallet. If this is not set, then adapter will use CHAPI flow.                                                       | N                       | false   |
+| linkedWalletURL     | string           | URL of the wallet                                                                                                                         | Y, if supportsWACI=true |         |
+| supportedVCContexts | array of strings | **DEPRECATED** this will be removed in future version. for now, send any string.                                                          |                         |         |
+
+**Response:**
+
+
+```jsonc
+HTTP 201 CREATED
+
+{
+   "id":"tb-prc-issuer2",
+   "name":"TrustBloc Demo - Permanent Resident Card Issuer",
+   "url":"https://demo-issuer.sandbox.trustbloc.dev/didcomm",
+   "supportedVCContexts":[
+      "https://w3id.org/citizenship/v1"
+   ],
+   "credentialSigningKey":"did:orb:uAAA:EiARcLmkKrStI_3_Fof6YcB6dnjIXWlKClhp-HeBb7kmRg#S7MjMEUQRconE-A5op9k3Exd9Enn8EJmfRx8baGiCvM",
+   "presentationSigningKey":"did:orb:uAAA:EiARcLmkKrStI_3_Fof6YcB6dnjIXWlKClhp-HeBb7kmRg#S7MjMEUQRconE-A5op9k3Exd9Enn8EJmfRx8baGiCvM",
+   "createdAt":"2022-02-09T18:32:27.807343657Z",
+   "supportsWACI":true,
+   "oidcProvider":"https://hydra.sandbox.trustbloc.dev/",
+   "credScopes":[
+      "PermanentResidentCard"
+   ],
+   "linkedWallet":"https://wallet.sandbox.trustbloc.dev/waci"
+}
+```
+
+### Redirect the user to Adapter API
+Invoke following url from Issuer application to start the flow.
+
+```
+<issuer-adapter-url>/<profile-id>/connect/wallet?cred=<scope>&txnID=<uuid>
+```
+
+Note:
+- `profile-id` : profile id from registration step
+- `cred`: value shoule be from scopes request param from [registration request](#register-a-clientprofile)
+
+### Process Auth Callback
+The issuer adapter calls OIDC auth endpoint of the issuer.
+
+```
+<issuer-oidc-provider-url>/oauth2/auth?access_type=offline&client_id=e507f0c6-bd60-4d51-a02f-089c570167c8&redirect_uri=https%3A%2F%2Fadapter-issuer.sandbox.trustbloc.dev%2Foidc%2Fcb&response_type=code&scope=openid+offline_access+PermanentResidentCard&state=BMC8ZeVHMMqlMUgKYTlA6GPGlAxctx2Q
+```
+
+Once auth call has been process, redirect to adapter based on `redirect_uri` value from auth call request.
+
+Note:
+- `issuer-oidc-provider-url` : oidc auth url based on `oidcProvider` in registration request.
+- `code` : oidc auth code
+
+### Process User Data call
+Invoke token endpoint to exchange code for access_token and id_token. The id_token in the response will contain the user data inside claims. The 
+use of OIDC client in programming langugae is preffered to generate the OIDC auth request.
+
+#### Request
+
+```bash
+HTTP POST
+curl --location --request POST '<issuer-url-from-profile>/data' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "token": "<code_from_auth_response>"
+}'
+```
+
+Note:
+- `issuer-url-from-profile` : this would be the `url` param set during registration.
+
+#### Respone
+
+```json
+{
+	   "data":{
+		  "id":"http://example.com/b34ca6cd37bbf23",
+		  "givenName":"JOHN",
+		  "familyName":"SMITH",
+		  "gender":"Male",
+		  "image":"data:image/png;base64,iVBORw0KGgo...kJggg==",
+		  "residentSince":"2015-01-01",
+		  "lprCategory":"C09",
+		  "lprNumber":"999-999-999",
+		  "commuterClassification":"C1",
+		  "birthCountry":"Bahamas",
+		  "birthDate":"1958-07-17"
+	   },
+	   "metadata":{
+		  "contexts":["https://trustbloc.github.io/context/vc/examples/citizenship-v1.jsonld"],
+		  "scopes":["PermanentResidentCard"],
+		  "name":"Permanent Resident Card",
+		  "description":"Permanent Resident Card for John Smith"
+	   }
+	}
+```
+
+Note:
+- `data` : this will be part of credentialSubject inside Verifiable Credential.
+
+### Handle Success Page
+
+````
+HTTP Redirect
+<issuer-url-from-profile>/cb?txnID=<txnID_from_initial_call>
+````
+
+Note:
+- `issuer-oidc-provider-url` : oidc auth url based on `oidcProvider` in registration request.
+
+## Available Scopes
+
+The scopes the Adapter supports are currently configured in a simple
+[JSON format](../../../test/bdd/fixtures/testdata/manifest-config/cmdescriptors.json)
+that is not exposed in via any other means. Consult the system administrator for the currently supported scopes before
+[registering the client](#register-a-clientprofile).
diff --git a/docs/issuer/issuer_adapter_overview.svg b/docs/issuer/issuer_adapter_overview.svg
diff --git a/docs/rp/integration/relying_parties.md b/docs/rp/integration/relying_parties.md
@@ -5,16 +5,17 @@
 This document serves as a guide for integrating [OpenID Connect 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
 client systems to the RP Adapter. The reader is expected to be familiar with OIDC and the OAuth2 authorization code flow.
 
-## Overview
+## Flow diagram
+TODO
+
+## Steps
 
 Follow these steps to integrate as a relying party:
 
-1. [Register your client](#register-oidc-client)
-2. [Redirect the user with your OIDC request](#request-end-user-credentials)
+1. [Register a client](#register-oidc-client)
+2. [Redirect the user with OIDC request](#request-end-user-credentials)
 3. Exchange auth code for the `access_token` and [parse the id_token](#id-token)
 
-## Steps
-
 ### Register OIDC Client
 
 Register OIDC client with RP adapter.
@@ -177,6 +178,6 @@ a JSON-LD document into a JWT while preserving the cryptographic security guaran
 ### Available Scopes
 
 The scopes the Adapter supports are currently configured in a simple
-[JSON format](https://github.com/trustbloc/edge-sandbox/blob/main/test/bdd/fixtures/demo/adapter-config/rp/presentationdefinitions.json)
+[JSON format](../../../test/bdd/fixtures/testdata/presentationdefinitions.json)
 that is not exposed in via any other means. Consult the system administrator for the currently supported scopes before
-[registering your client](#register-your-oidc-client).
+[registering client](#register-oidc-client).