Merge pull request #89 from bcgov/docs/devhub-documentation

DevHub Documentation v1
bcgov · Jul 29, 2024 · 53aecf3 · 53aecf3
2 parents 54a6e40 + e0ae817
commit 53aecf3
Show file tree

Hide file tree

Showing 14 changed files with 128 additions and 73 deletions.
diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml
@@ -1,40 +1,39 @@
 name: Build TechDocs with DevHub TechDocs Publish Action
 
 on:
-    workflow_dispatch:
-    push:
-        branches: [ main ]
-        paths:
-            - "mkdocs.yml"
-            - "docs/*"
-            - "catalog-info.yaml"
-    pull_request:
-        branches: [ main ]
-        paths:
-            - "mkdocs.yml"
-            - "docs/*"
-            - "catalog-info.yaml"
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - "mkdocs.yml"
+      - "docs/*"
+      - "catalog-info.yaml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "mkdocs.yml"
+      - "docs/*"
+      - "catalog-info.yaml"
 
 jobs:
-    test_techdocs_build_job:
-        runs-on: ubuntu-latest
-
-        name: A job to build and publish techdocs content
-        steps:
-            -   name: Checkout
-                uses: actions/checkout@v4
-                with:
-                    fetch-depth: '0'
-            -   name: Build TechDocs
-                uses: bcgov/devhub-techdocs-publish@stable
-                id: build_and_publish
-                with:
-                    publish: 'false' # publishing disabled initially - content will be built, but not published. repositories need to be granted access to TechDocs secrets explicitly by the DevEx team before publishing would work, so we disable to prevent the workflow from failing.
-# the parameters below can be uncommented when publishing is enabled and secrets have been exposed to the repo
-#                    production:  ${{ github.ref == 'refs/heads/main' && 'true' || 'false' }} # example of only pushing to prod DevHub when changes that triggered the job are in main branch
-#                    bucket_name: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
-#                    s3_access_key_id: ${{ secrets.TECHDOCS_AWS_ACCESS_KEY_ID }}
-#                    s3_secret_access_key: ${{ secrets.TECHDOCS_AWS_SECRET_ACCESS_KEY }}
-#                    s3_region: ${{ secrets.TECHDOCS_AWS_REGION }}
-#                    s3_endpoint: ${{ secrets.TECHDOCS_AWS_ENDPOINT }}
+  test_techdocs_build_job:
+    runs-on: ubuntu-latest
 
+    name: A job to build and publish techdocs content
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: "0"
+      - name: Build TechDocs
+        uses: bcgov/devhub-techdocs-publish@stable
+        id: build_and_publish
+        with:
+          publish: "true" # publishing disabled initially - content will be built, but not published. repositories need to be granted access to TechDocs secrets explicitly by the DevEx team before publishing would work, so we disable to prevent the workflow from failing.
+          # the parameters below can be uncommented when publishing is enabled and secrets have been exposed to the repo
+          production: ${{ github.ref == 'refs/heads/main' && 'true' || 'false' }} # example of only pushing to prod DevHub when changes that triggered the job are in main branch
+          bucket_name: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
+          s3_access_key_id: ${{ secrets.TECHDOCS_AWS_ACCESS_KEY_ID }}
+          s3_secret_access_key: ${{ secrets.TECHDOCS_AWS_SECRET_ACCESS_KEY }}
+          s3_region: ${{ secrets.TECHDOCS_AWS_REGION }}
+          s3_endpoint: ${{ secrets.TECHDOCS_AWS_ENDPOINT }}
diff --git a/docs/about-us.md b/docs/about-us.md
@@ -2,6 +2,6 @@
 
 ## Suggested Content
 
-Introduce your team or project for a more in-depth understanding for your users
-
+Learn more about Digital Trust initiatives in the BC provincial Government at https://digital.gov.bc.ca/digital-trust/home/
 
+For any questions or requests that are not answered in the documentation or on the Digital trust website, feel free to log an issue in this repository and/or send an email at the addresses listed [here](https://digital.gov.bc.ca/digital-trust/contact).
diff --git a/docs/configuration.md b/docs/configuration.md
diff --git a/docs/getting-started.md b/docs/getting-started.md
diff --git a/docs/index.md b/docs/index.md
@@ -2,13 +2,24 @@
 
 Technical and non-technical documentation for Digital Trust and Verifiable Credentials
 
-**This file is the homepage of your documentation. It is mandatory and must not be deleted.**
+## About DITP
 
-## Suggested content
+The Digital Trust and Identity Program is part of the Cybersecurity and Digital Trust team at the Province of British Columbia.
 
-* Clearly define the purpose and functionality of your service, project, or application 
-  * Leverage [Service Definition](https://github.com/BCDevOps/openshift-wiki/blob/0ff5d39f767e89b1b8fac8ccda9901b3e18a672a/docs/OCP/ServiceDefinition.md) structure that exists for several services already 
-* Highlight key features and advantages
-* Emphasize main functionalities
-* How to get support
+Our focus is building tools to enable Digital Trust and supporting partners/adopter in their journey to improve their business processes and implement new ones that leverage this technology.
 
+## Patterns
+
+There are three main patterns that can be leveraged in the Digital trust space, follow the links to learn more:
+
+- [Verifier](patterns/verifier.md): verifies and consumes credentials issued by a third-party authority.
+- [Issuer](patterns/issuer.md): defines a new credential schema and is responsible for issuing and revoking credentials.
+- [Access](patterns/access.md): similar to the verifier pattern, it's used to obtain authorization to resources on the web.
+
+## Solutions
+
+Depending on which pattern you are looking to implement, the following solutions will provide a foundation to get started:
+
+- [VC-AuthN and SSO](solutions/vc-authn-sso.md): a solution that allows the use of Digital Credentials in an OIDC authentication flow. As an identity Provider service integrated with the [Pathfinder SSO Service](https://developer.gov.bc.ca/docs/default/component/css-docs) it provides a lightweight, standard approach to web application authentication that does not require deep knowledge of Digital trust patterns and tools.
+- [Traction](solutions/traction-overview.md): a Software-As-A-Service Enterprise agent service based on [Aries Cloudagent Python](https://github.com/hyperledger/aries-cloudagent-python), it provides streamlined onboarding for new adopters wanting to have full control over their Digital trust processes, from receiving and presenting Digital credentials to acting as a verifier or even an issuer.
+- [OrgBook BC](https://orgbook.gov.bc.ca): a repository of credentials for publicly available information. It contains information about entities registered as businesses in BC (data from BC registries), as well as [other permit/license credentials from different organizations](https://orgbook.gov.bc.ca/about/orgbook-data).
diff --git a/docs/patterns/access.md b/docs/patterns/access.md
@@ -0,0 +1,3 @@
+# Access
+
+## Work In Progress
diff --git a/docs/patterns/issuer.md b/docs/patterns/issuer.md
@@ -0,0 +1,3 @@
+# Issuer
+
+## Work In Progress
diff --git a/docs/patterns/verifier.md b/docs/patterns/verifier.md
@@ -0,0 +1,3 @@
+# Verifier
+
+## Work In Progress
diff --git a/docs/solutions/orgbook-bc.md b/docs/solutions/orgbook-bc.md
@@ -0,0 +1,22 @@
+# OrgBook BC
+
+[OrgBook BC](https://orgbook.gov.bc.ca) is a public repository of credentials representing public information. The foundational credential for OrgBook is a company registration credential issued by [BC Registries](https://www.bcregistry.gov.bc.ca). Credentials are also issued for relevant events such as name changes, amalgamations, etc.
+
+Third party issuers can issue credentials such as licenses and permits to OrgBook and bind them to the relevant receiving entity for public discovery and consumption.
+
+## Accessing OrgBook Data
+
+There are two ways of accessing data stored in OrgBook:
+
+- The user interface allows the search and discovery of credentials from a web UI. This is useful for end-users trying to gather information about a known entity.
+- The [OrgBook API](https://orgbook.gov.bc.ca/api)
+
+The API is openly accessible (for reasonably/fair use) and allows systems to integrate with OrgBook to look-up company registration records and associated data.
+
+The swagger interface provides an easy way to discover the API endpoints, and there are [API docs](https://bcgov.github.io/orgbook-bc-api-docs) with code snippets providing examples for common use cases.
+
+## Becoming an Issuer
+
+If you have a good candidate for a credential to be publicly issued to an organization (such as a license or permit), you can become an issuer and integrate and push the information to OrgBook.
+
+The current version of OrgBook is in evolution, the best way to get the conversation started is by [contacting us](../about-us.md).
diff --git a/docs/solutions/traction-becoming-an-issuer.md b/docs/solutions/traction-becoming-an-issuer.md
diff --git a/docs/solutions/traction-overview.md b/docs/solutions/traction-overview.md
@@ -0,0 +1,3 @@
+# Traction
+
+## Work In Progress
diff --git a/docs/solutions/vc-authn-sso.md b/docs/solutions/vc-authn-sso.md
@@ -0,0 +1,24 @@
+# VC-AuthN SSO
+
+[VC-AuthN OIDC](https://github.com/bcgov/vc-authn-oidc) is an identity provider compatible with the OpenID Connect protocol, that uses Verifiable credentials as authentication method.
+
+The service is composed of an agent ([ACA-Py](https://github.com/hyperledger/aries-cloudagent-python)) that is responsible for the secure communication and exchange nd credentials, and a controller that "drives" the agent to build authentication requests and translate them into the OIDC protocol.
+
+## Getting Started
+
+The easiest way to get started with verifiable credential authentication is to request access to the `Digital Credential` identity provider in the [Pathfinder SSO](https://developer.gov.bc.ca/docs/default/component/css-docs) service.
+
+Once the identity provider is enabled, integration with your application is as simple as connecting it with a Keycloak client that can talk to the new IdP.
+
+There are, however, a couple of things specific to VC-AuthN that your service will need to determine and keep in mind:
+
+- You will need to choose a **presentation request configuration**: this is the setting that tells VC-AuthN which credentials you are requiring and want to obtain information from to allow access to your system. Once you have determined the `id` of the configuration you want to use, you will need to add a query parameter to your OIDC authentication request to indicate it to VC-AuthN: `pres_req_conf_id=my-chosen-config-id`.
+  - Existing presentation configurations can be discovered [here](https://vc-authn-oidc-dev.apps.silver.devops.gov.bc.ca/ver_configs/explorer). If no existing configuration meets your application requirements, you can [contact us](../about-us.md) to explore options.
+- Upon successful authentication, your application should check that the JWT includes a `pres_req_conf_id` attribute with the same value as the value that was provided to generate the authentication request. If this is not true, the authentication request could have been manually modified/hijacked.
+- A successful authentication will return a JWT with attributes coming from the credentials stored in an object: `vc_presented_attributes`. Claims will be nested in this object and not presented at the top level.
+
+## Limitations
+
+VC-AuthN has a different approach to "traditional" identity providers, and it does not store a user database. For this reason, and because there may be any combination of credentials in an authentication request, it is not possible for the IdP to provide a unique identifier to recognize returning users.
+
+The consuming applications (clients) are therefore responsible for reconciling user access requests to the same user by using the attributes exposed as part of the proof-request or by other mechanism.
diff --git a/docs/tips-and-tricks.md b/docs/tips-and-tricks.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,16 +1,24 @@
-site_name: "Digital identity and Trust Program Documentation"
+site_name: "Digital Identity and Trust Program Documentation"
 site_description: "Technical and non-technical documentation for Digital Trust and Verifiable Credentials"
 docs_dir: "docs"
 repo_url: "https://github.com/bcgov/DITP"
 edit_uri: edit/main/docs
 nav:
-    - Introduction: index.md
-    - Getting started: getting-started.md
-    - Configuration: configuration.md
-    - Tips and tricks: tips-and-tricks.md
-    - About us: about-us.md
+      - Introduction: index.md
+      - Digital Trust Patterns:
+              - Overview: pattern-overview.md
+              - Access Pattern: patterns/access.md
+              - Verifier Pattern: patterns/verifier.md
+              - Issuer Pattern: patterns/issuer.md
+      - Solutions:
+              - VC-AuthN and SSO: vc-authn-sso.md
+              - Traction:
+                      - Overview: traction-overview.md
+                      - Becoming an Issuer: traction-becoming-an-issuer.md
+              - OrgBook BC: orgbook-bc.md
+      - Need Help?: need-help.md
 plugins:
-    - techdocs-core
-    - git-revision-date-localized
+      - techdocs-core
+      - git-revision-date-localized
 markdown_extensions:
-    - md_in_html
+      - md_in_html