From 85fc94084747e2792948f31f43d1bb0a82149b7b Mon Sep 17 00:00:00 2001 From: Rolson Quadras Date: Fri, 11 Feb 2022 10:25:56 -0500 Subject: [PATCH] docs: Issuer Adapter - define WACI flow and APIs - issuer integration docs Signed-off-by: Rolson Quadras --- README.md | 2 +- docs/issuer/README.md | 14 ++ docs/issuer/integration/issuer.md | 167 ++++++++++++++++++++++++ docs/issuer/issuer_adapter_overview.svg | 3 + docs/rp/integration/relying_parties.md | 15 ++- 5 files changed, 193 insertions(+), 8 deletions(-) create mode 100644 docs/issuer/README.md create mode 100644 docs/issuer/integration/issuer.md create mode 100644 docs/issuer/issuer_adapter_overview.svg diff --git a/README.md b/README.md index a912b9fb..237a6411 100644 --- 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 new file mode 100644 index 00000000..32789648 --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/issuer/integration/issuer.md b/docs/issuer/integration/issuer.md new file mode 100644 index 00000000..6939ca8c --- /dev/null +++ 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 /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. + +``` +//connect/wallet?cred=&txnID= +``` + +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. + +``` +/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 '/data' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "token": "" +}' +``` + +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 +/cb?txnID= +```` + +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 new file mode 100644 index 00000000..b4692241 --- /dev/null +++ b/docs/issuer/issuer_adapter_overview.svg @@ -0,0 +1,3 @@ + + +
User Wallet
User...
Decentralized Identifiers
Verifiable Credentials
DIDComm
Decentralized Identifiers...
DIDComm-aware RP
DIDComm-aware Issu...
Issuer Adapter
Issuer Adapter
Issuer
Issuer
OIDC
OIDCViewer does not support full SVG 1.1 diff --git a/docs/rp/integration/relying_parties.md b/docs/rp/integration/relying_parties.md index 8394f9fb..30032a63 100644 --- 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).