Review

Signed-off-by: Chris Chinchilla <chris@kilt.io>
KILTprotocol · Jun 10, 2024 · 8af6141 · 8af6141
1 parent 42d7947
commit 8af6141
Show file tree

Hide file tree

Showing 5 changed files with 105 additions and 96 deletions.
diff --git a/docs/develop/08_opendid/03_opendid_service.md b/docs/develop/08_opendid/03_opendid_service.md
@@ -18,43 +18,45 @@ Before running the `opendid-setup` container, set two environment variables:
 
 1. `SEED` to provide an account with funds (minimum of 3 KILT) for the DID generation.
 
-```bash
-export SEED="dont try this seed its completely made up for this nice example"
-```
+    ```bash
+    export SEED="dont try this seed its completely made up for this nice example"
+    ```
 
 2. `ENDPOINT`
 
-Set to "spiritnet" if the account is on the spiritnet production network.
+    Set to "spiritnet" if the account is on the spiritnet production network.
 
-```bash
-export ENDPOINT="spiritnet"
-```
+    ```bash
+    export ENDPOINT="spiritnet"
+    ```
 
-Set to "peregrine" if the account is on the peregrine test network.
+    Set to "peregrine" if the account is on the peregrine test network.
 
-```bash
-export ENDPOINT="peregrine"
-```
+    ```bash
+    export ENDPOINT="peregrine"
+    ```
 
-Then run the setup with the following command:
+    Then run the setup with the following command:
 
-```bash
-docker run --rm -it -e "ENDPOINT=${ENDPOINT}" -v $(pwd):/data docker.io/kiltprotocol/opendid-setup:latest "${SEED}"
-```
+    ```bash
+    docker run --rm -it -e "ENDPOINT=${ENDPOINT}" -v $(pwd):/data docker.io/kiltprotocol/opendid-setup:latest "${SEED}"
+    ```
 
 The command generates a set of new mnemonics and then derives a DID from them and generates multiple files into the current directory:
 
 1. `config.yaml` The configuration file used by the OpenDID service.
 2. `did-secrets.json` This file contains the public and secret keys in the DID Document.
 
-Keep a secure backup of this file as it contains all the secret keys.
+    :::warning
+    Keep a secure backup of this file as it contains all the secret keys.
+    :::
 
 3. `did-document.json` contains the DID Document generated by this setup.
 
-:::danger
-You only need the `config.yaml` to run the OpenDID service.
-This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access.
-:::
+    :::danger
+    You only need the `config.yaml` to run the OpenDID service.
+    This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access.
+    :::
 
 The container generates sensible defaults in the `config.yaml` file, but here are some values you might want to change:
 
@@ -81,7 +83,7 @@ The container generates sensible defaults in the `config.yaml` file, but here ar
 
 When you've made changes to the `config.yaml` file, you can run the OpenDID service.
 
-1.  Specify the runtime through the `RUNTIME` environment variable:
+1. Specify the runtime through the `RUNTIME` environment variable:
 
     Set to `"spiritnet"` for production KILT
 
@@ -95,20 +97,19 @@ When you've made changes to the `config.yaml` file, you can run the OpenDID serv
     export RUNTIME="peregrine"
     ```
 
-2.  Run the `docker.io/kiltprotocol/opendid` docker image .
+2. Run the `docker.io/kiltprotocol/opendid` docker image.
 
-```bash
-docker run -d --rm \
-    -v $(pwd)/config.yaml:/app/config.yaml \
-    -v $(pwd)/checks:/app/checks \
-    -e "RUNTIME=${RUNTIME}" \
-    -p 3001:3001 \
-    docker.io/kiltprotocol/opendid:latest
-```
+    ```bash
+    docker run -d --rm \
+        -v $(pwd)/config.yaml:/app/config.yaml \
+        -v $(pwd)/checks:/app/checks \
+        -e "RUNTIME=${RUNTIME}" \
+        -p 3001:3001 \
+        docker.io/kiltprotocol/opendid:latest
+    ```
 
 3. Open the login page at _http://localhost:3001_.
 
 ## Next steps
 
 With configuration in place and a service running, next you need to [integrate OpenDID into an application](./04_integrate_opendid.md) so that a user can use the login page.
-
diff --git a/docs/develop/08_opendid/04_integrate_opendid.md b/docs/develop/08_opendid/04_integrate_opendid.md
@@ -77,16 +77,16 @@ The OpenDID service returns the `id_token` in the response body serialized as a
 In full-stack applications, calling the `token` endpoint is usually done through the back end to improve security.
 :::
 
-The `id_token` is a JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. Yout can be verified using the JWT public key, for example, by the backend of the Web app.
+The `id_token` is a JSON web token (JWT) signed by the JWT key-pair specified in the `config.yaml` file of the OpenDID service. 
+You can verify this using the JWT public key, for example, by the back end of the Web app.
 
-## Implicit Flow
+## Implicit flow
 
-Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query
-parameters:
+Initiate the flow by redirecting to the **GET** `/api/v1/authorize` endpoint on the OpenDID Service and setting the following query parameters:
 
 -   `response_type`: set value to `id_token` to indicate Implicit Flow.
 -   `client_id`: The client ID set in the config.yaml file.
--   `redirect_uri`: OpenDID will redirect to this URL after authentication.
+-   `redirect_uri`: OpenDID redirects to this URL after authentication.
 -   `scope`: set value to `openid`.
 -   `state`: set to a secure random number.
 -   `nonce`: optional value, set to a secure random number.
@@ -103,7 +103,7 @@ GET /api/v1/authorize?
     nonce=ia7sa06ungxdfzaqphk2 HTTP/1.1
 ```
 
-After successful authentication, OpenDID will redirect back to the provided `redirect_uri` with `id_token` and `state`
+After successful authentication, OpenDID redirects back to the provided `redirect_uri` with `id_token` and `state`
 **fragment components**.
 
 **Example**:

diff --git a/docs/develop/08_opendid/05_demo_project.md b/docs/develop/08_opendid/05_demo_project.md
@@ -6,10 +6,13 @@ title: Demo Project
 The example code at [demo-project](https://github.com/KILTprotocol/opendid/tree/main/demo-project) contains a minimal application that uses OpenDID.
 It's an [express](https://expressjs.com) application that exposes three things:
 
-- A login page that handles the dispatching of the user to the opendid.
-- A callback page for the openid connect flow to accept the token.
+- A login page that handles the dispatching of the user to the OpenDID service.
+- A callback page for the OpenID connect flow to accept the token.
 - A protected resource that only authenticated users can access.
 
+For the demo application to work you need a running OpenDID Service and an identity wallet (e.g. [Sporran](https://www.sporran.org/)) with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC).
+If you follow the steps in this section in order, you have all the necessary components for the demo application to run.
+
 Run the pre-configured demo application with the following command:
 
 ```bash
@@ -19,12 +22,9 @@ docker run -d -it --rm \
     docker.io/kiltprotocol/opendid-demo
 ```
 
-The demo page will run on _http://localhost:1606_.
-
-For this demo to work a running OpenDID Service is needed, an Identity Wallet (e.g. [Sporran](https://www.sporran.org/))
-with a DID and Credential issued by the required attester specified in the `config.yaml` file (Default is SocialKYC).
+The demo page runs on _http://localhost:1606_. It pre-fills the Client ID value and offers login buttons to follow the implicit or authorization code flow.
 
 :::note
-The JWT secret can be set with the `TOKEN_SECRET` environment variable inside the docker container. It must match
-the one specified in the `config.yaml` file to correctly verify the `id_token`. Default is `super-secret-jwt-secret`.
+You can set the JSON web token (JWT) secret can with the `TOKEN_SECRET` environment variable inside the docker container. It must match
+the one specified in the `config.yaml` file to correctly verify the `id_token`. The default is `super-secret-jwt-secret`.
 :::
diff --git a/docs/develop/08_opendid/06_advanced.md b/docs/develop/08_opendid/06_advanced.md
@@ -3,33 +3,32 @@ id: advanced
 title: Advanced Usage
 ---
 
-## Use dynamic client management
+## Use dynamic client management with etcd
 
-If you want to dynamically create or remove OpenID Connect clients, you can configure the service to get its configuration from an [etcd cluster](https://etcd.io).
-To do so, configure the connection parameters for the etcd cluster in the `config.yaml` file.
+To dynamically create or remove OpenID Connect clients, configure the service to get its configuration from an [etcd cluster](https://etcd.io) by adding the connection parameters for the cluster in the `config.yaml` file.
 
 ```yaml
 etcd:
-  endpoints: ["localhost:2379"]
-  user: etcd-user
-  password: my-password
-  tlsDomainName: my.etcd.cluster.example.com
-  tlsCaCert: |
-    -----BEGIN CERTIFICATE-----
-    <ca certificate data>
-    -----END CERTIFICATE-----
-  tlsClientCert: |
-    -----BEGIN CERTIFICATE-----
-    <client certificate data>
-    -----END CERTIFICATE-----
-  tlsClientKey: |
-    -----BEGIN RSA PRIVATE KEY-----
-    <client key data>
-    -----END RSA PRIVATE KEY-----
+    endpoints: ['localhost:2379']
+    user: etcd-user
+    password: my-password
+    tlsDomainName: my.etcd.cluster.example.com
+    tlsCaCert: |
+        -----BEGIN CERTIFICATE-----
+        <ca certificate data>
+        -----END CERTIFICATE-----
+    tlsClientCert: |
+        -----BEGIN CERTIFICATE-----
+        <client certificate data>
+        -----END CERTIFICATE-----
+    tlsClientKey: |
+        -----BEGIN RSA PRIVATE KEY-----
+        <client key data>
+        -----END RSA PRIVATE KEY-----
 ```
 
-All fields except `endpoints` are optional and depending on your etcd setup you might not need them.
-When everything is set up you can start putting client configurations into the etcd cluster.
+All fields except `endpoints` are optional.
+When everything is set up you can start adding client configurations into the etcd cluster.
 
 ```bash
 CLIENT_SPEC=$(cat <<EOF
@@ -50,43 +49,44 @@ CLIENT_SPEC=$(echo $CLIENT_SPEC | jq -c)
 etcdctl put /opendid/clients/new-client "${CLIENT_SPEC}"
 ```
 
-If you want to try this out you can first generate a config using the setup image as described above, add the etcd configuration and then start the service using the example script in _./scripts/start-demo-etcd.sh_.
+If you want to try this out, first generate a configuration file using the setup image as described in [the OpenDID service step](./03_opendid_service.md).
+Then add the etcd configuration and start the service using the example script in _./scripts/start-demo-etcd.sh_.
 
-### Add advanced claim checks using RHAI scripts
+## Add advanced claim checks using RHAI scripts
 
-To add custom checks that are executed on the claims of the Verifiable Credential, you can use [Rhai](https://rhai.rs) scripts.
-To try it out you have to add a `checksDirectory` entry to the client configuration in the `config.yaml` file.
+To add custom checks executed on the claims of the Verifiable Credential, use [Rhai](https://rhai.rs) scripts.
+To try it, add a `checksDirectory` entry to the client configuration in the `config.yaml` file.
 
-Example:
+**Example**:
 
 ```yaml
 ---
 clients:
-  example-client:
-    requirements:
-      - cTypeHash: "0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac"
-        trustedAttesters:
-          [
-            "did:kilt:4pehddkhEanexVTTzWAtrrfo2R7xPnePpuiJLC7shQU894aY",
-            "did:kilt:4pnfkRn5UurBJTW92d9TaVLR2CqJdY4z5HPjrEbpGyBykare",
-          ]
-        requiredProperties: ["Email"]
-    redirectUrls:
-      - http://localhost:1606/callback.html
-    checksDirectory: /app/checks
+    example-client:
+        requirements:
+            - cTypeHash: '0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac'
+              trustedAttesters:
+                  [
+                      'did:kilt:4pehddkhEanexVTTzWAtrrfo2R7xPnePpuiJLC7shQU894aY',
+                      'did:kilt:4pnfkRn5UurBJTW92d9TaVLR2CqJdY4z5HPjrEbpGyBykare',
+                  ]
+              requiredProperties: ['Email']
+        redirectUrls:
+            - http://localhost:1606/callback.html
+        checksDirectory: /app/checks
 ```
 
-Now create a directory `checks` in the same directory as the `config.yaml` file and add a file `example-check.rhai` with the following content:
+Create a `checks` directory in the same directory as the `config.yaml` file and add a `example-check.rhai` file with the following content:
 
 ```rust
-// This is a simple example of a login policy that allows only users with an email address ending with `kilt.io` to login.
+// This is an example of a simple login policy that allows only users with an email address ending with `kilt.io` to login.
 
 let SUFFIX = "kilt.io";
 
-// ID_TOKEN contains the id_token as to be send to the user from the OIDC provider
+// ID_TOKEN contains the id_token to send to the user from the OpenID connect (OIDC) provider
 let token = parse_id_token(ID_TOKEN);
 
-// We can inspect the token and especially the `pro` sub-object that contains the users claims
+// Inspect the token and the `pro` sub-object that contains the users claims
 if token.pro.Email.ends_with(SUFFIX) {
   // The user is allowed to login
   return true;
@@ -96,7 +96,7 @@ if token.pro.Email.ends_with(SUFFIX) {
 return false;
 ```
 
-You can now start the service bind-mounting the script and try it out.
+Start the service bind-mounting the script:
 
 ```bash
 docker run -d --rm \
@@ -107,9 +107,5 @@ docker run -d --rm \
     docker.io/kiltprotocol/opendid:latest
 ```
 
-:::note
-If you wish to execute the service on the Peregrine runtime, you must modify the environment variable RUNTIME to "peregrine".
-:::
-
 When you now log in with a user that has an email address ending with `kilt.io` the service allows you to log in.
-If you use a different email address, the service denies you access.
+If you use a different email address, the service denies you access.
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -41,7 +41,8 @@ module.exports = {
     announcementBar: {
       id: 'dip-announcement',
       // Use absolute links proceeded by '/docs'
-      content: 'DIP enables OpenID inspired cross-chain identity, <a href="/docs/concepts/dip/what-is-dip">help us test this new feature</a>!',
+      content:
+        'DIP enables OpenID inspired cross-chain identity, <a href="/docs/concepts/dip/what-is-dip">help us test this new feature</a>!',
       backgroundColor: '#2db528',
       textColor: '#fff',
       isCloseable: true,
@@ -98,6 +99,11 @@ module.exports = {
               docId: 'develop/dApp/welcome',
               label: 'DApp Documentation',
             },
+            {
+              type: 'doc',
+              docId: 'develop/opendid/what-is-opendid',
+              label: 'OpenDID Documentation',
+            },
           ],
         },
         {
@@ -239,7 +245,10 @@ module.exports = {
         documents: ['README.md'],
         modifyContent(filename, content) {
           if (filename.includes('README')) {
-            var trimContent = content.replace("# Decentralized Identity Provider (DIP) provider pallet", "# Provider pallet")
+            var trimContent = content.replace(
+              '# Decentralized Identity Provider (DIP) provider pallet',
+              '# Provider pallet'
+            )
             return {
               filename: '02_provider.md',
               content: trimContent,
@@ -260,7 +269,10 @@ module.exports = {
         documents: ['README.md'],
         modifyContent(filename, content) {
           if (filename.includes('README')) {
-            var trimContent = content.replace("# Decentralized Identity Provider (DIP) consumer pallet", "# Consumer pallet")
+            var trimContent = content.replace(
+              '# Decentralized Identity Provider (DIP) consumer pallet',
+              '# Consumer pallet'
+            )
             return {
               filename: '03_consumer.md',
               content: trimContent,