diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index fd0a5e4..2dc16aa 100644 --- 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 index ae4f37c..a45bb09 100644 --- 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 deleted file mode 100644 index 3ed2ced..0000000 --- a/docs/configuration.md +++ /dev/null @@ -1,7 +0,0 @@ -# Configuration - -## Suggested Content - -* Explain configuration/customization requirements, if necessary -* Guide on tailoring the service to specific needs -* Provide instructions for integrating with other systems if needed \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index eb25c5b..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,7 +0,0 @@ -# Getting started - -## Suggested Content -* Provide step-by-step instructions for system setup -* List prerequisites and system requirements -* Determine if visual aids are necessary for better comprehension, keeping in mind to [create accessible content](https://digital.gov.bc.ca/wcag/home/intro/) and review the [accessibility and inclusion toolkit](https://www2.gov.bc.ca/gov/content/home/accessible-government/toolkit) -* Address common issues and provide troubleshooting solutions \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 993d694..d2373e8 100644 --- 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 new file mode 100644 index 0000000..d533de6 --- /dev/null +++ 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 new file mode 100644 index 0000000..a60a01d --- /dev/null +++ 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 new file mode 100644 index 0000000..d48778e --- /dev/null +++ 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 new file mode 100644 index 0000000..739f27e --- /dev/null +++ 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 new file mode 100644 index 0000000..e69de29 diff --git a/docs/solutions/traction-overview.md b/docs/solutions/traction-overview.md new file mode 100644 index 0000000..ea3e29d --- /dev/null +++ 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 new file mode 100644 index 0000000..4b58d0d --- /dev/null +++ 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 deleted file mode 100644 index 53aea05..0000000 --- a/docs/tips-and-tricks.md +++ /dev/null @@ -1,7 +0,0 @@ -# Tips and tricks - -## Suggested Content - -* Contribute to the overall success of a development project -* Promote efficiency, code quality, collaboration, security, and adaptability -* Ensure the knowledge base required aligns with your entire audience; assess if it suits their needs \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 9d4e8c5..9c61cd6 100644 --- 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