From 19c1c46e9569f1c74386d646cdbda9ddca275bd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emiliano=20Su=C3=B1=C3=A9?= Date: Thu, 29 Aug 2024 13:25:54 -0700 Subject: [PATCH] Added docs for patterns, endorser. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Emiliano Suñé --- docs/patterns/access.md | 17 ++++++++++++++++- docs/patterns/issuer.md | 12 +++++++++++- docs/patterns/overview.md | 8 +++++++- docs/patterns/verifier.md | 14 +++++++++++++- docs/solutions/endorser-service.md | 10 +++++++++- mkdocs.yml | 2 +- 6 files changed, 57 insertions(+), 6 deletions(-) diff --git a/docs/patterns/access.md b/docs/patterns/access.md index d533de6..c231341 100644 --- a/docs/patterns/access.md +++ b/docs/patterns/access.md @@ -1,3 +1,18 @@ # Access -## Work In Progress +In the access pattern, a system will require users to prove that they can access its functionalities by presenting information contained in one or more verifiable credentials. Depending on the needs of each integration, there are two ways to enable Digital trust Access in your application: + +- OIDC based access +- Direct access + +## OIDC Based Access + +OIDC based access is the simplest way to add Digital Trust verification capabilities to an application. It leverages [VC-AuthN OIDC](../solutions/vc-authn-sso.md) as Identity Provider and is fully integrated with the [Pathfinder SSO](https://developer.gov.bc.ca/docs/default/component/css-docs) service. It relies on the OpenID Connect authentication protocol and can generally be introduced with minor changes to your application if it already uses another OIDC identity provider to gate access (e.g.: IDIR, GitHub). + +Please refer to the [VC-AuthN OIDC](../solutions/vc-authn-sso.md) page for additional details. + +## Direct Access + +For more advanced interaction, a direct access pattern may be considered: this will provide the application with full control over the interaction teh same way as if it was a [verifier](verifier.md). + +Direct access, however, requires a significantly higher amount of work when compared to OIDC based access since the application team will be responsible for directly integrating with [Traction's](../solutions/traction-overview.md) APIs to create and process proof-requests as well as developing a custom authentication framework. diff --git a/docs/patterns/issuer.md b/docs/patterns/issuer.md index a60a01d..3264082 100644 --- a/docs/patterns/issuer.md +++ b/docs/patterns/issuer.md @@ -1,3 +1,13 @@ # Issuer -## Work In Progress +An issuer is an entity with the authority to define, issue and revoke credentials. + +Issuers create Digital Credentials that [verifiers](verifier.md) can then request and use, and often times they also are verifiers of the credentials they have issued. + +To become an issuer, you will first need to request a tenant in [Traction](../solutions/traction-overview.md). + +## Governance + +Issuers should meet the requirements set by the Governance defined by the organization they belong to, the Digital Trust team as well as the ledger chosen as trust root (where the issuer will publish its public keys and other cryptographic identifiers). + +An [endorser service](../solutions/endorser-service.md) is generally responsible for overseeing an issuer's request to publish new information to a ledger and approving/rejecting it. diff --git a/docs/patterns/overview.md b/docs/patterns/overview.md index 972e0f7..725d232 100644 --- a/docs/patterns/overview.md +++ b/docs/patterns/overview.md @@ -1,3 +1,9 @@ # Digital Trust Patterns -## Work In Progress +Digital Trust interactions generally follow one (or more) of teh following patterns: + +- [Access](access.md): when a system requires users to authenticate before they can access protected information or functionality. +- [Verifier](verifier.md): when a system needs to verify that users (or other systems) can provide a valid response to a proof-request. Proof requests could either require information to be shared, or only require proof of specific assertions such as "Are you over 19 years of age?" or "Are you authorized to submit this request?". +- [Issuer](issuer.md): when credentials with a custom set of attributes are required and existing credentials issued by another authority cannot be reused. + +For more information about these digital experiences, please explore the [Digital Trust Toolkit](https://bcgov.github.io/digital-trust-toolkit/). diff --git a/docs/patterns/verifier.md b/docs/patterns/verifier.md index d48778e..c17c890 100644 --- a/docs/patterns/verifier.md +++ b/docs/patterns/verifier.md @@ -1,3 +1,15 @@ # Verifier -## Work In Progress +A verifier is a service that requests information via a proof-request to other users and/or systems, processes the response and triggers the next steps in the interaction based on the outcome. + +A verifier can request and validate information from any issuer rooted on a [ledger](../solutions/traction-overview.md#ledgers) to which its agent has access. + +The verification process generally consists of: + +- Determining which credential or credentials would satisfy the proof-request. +- Invoking the appropriate endpoints in the agent to prepare the proof-request. +- Sending the proof request to the holder: this could happen over a previously established connection, or out-of-band. +- Receiving and processing the holder's response. +- Completing the interaction based on the outcome of the verification. + +To become a verifier, you will first need to request a tenant in [Traction](../solutions/traction-overview.md). diff --git a/docs/solutions/endorser-service.md b/docs/solutions/endorser-service.md index d105f3c..b045ad7 100644 --- a/docs/solutions/endorser-service.md +++ b/docs/solutions/endorser-service.md @@ -1,3 +1,11 @@ # Endorser Service -## Work In Progress +An Endorser Service is responsible for authorizing write transactions to each one of the ledgers supported by BCGov. An overview of the ledgers available in read/write mode can be found [here](traction-overview.md#ledgers). + +When a write operation such as publishing a new schema definition to the ledger is required, tenant administrators will need to request authorization to the Digital trust team. Each request for endorsement will be reviewed and, if the governance terms are respected, will be approved. + +!!! info "Note" + Endorsement requests in the `dev` environment will be automatically approved in order to facilitate rapid prototyping and development of new solutions. `test` an `prod`, however, will require a DITP member to review the request and approve it before the transaction can be written and completed. + +!!! warning "Endorsement is Asynchronous!" + Endorsement requests are asynchronous and may take several hours or even days to complete, especially when review by a DITP team member is required. Ensure your code does not expect an immediate endorsement request, especially when requesting new schemas or credential definitions to be published. diff --git a/mkdocs.yml b/mkdocs.yml index 6b38612..98cd706 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,7 @@ edit_uri: edit/main/docs nav: - Introduction: index.md - Digital Trust Patterns: - - Overview: overview.md + - Overview: patterns/overview.md - Access Pattern: patterns/access.md - Verifier Pattern: patterns/verifier.md - Issuer Pattern: patterns/issuer.md