Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added docs for patterns, endorser. #94

Merged
merged 3 commits into from
Aug 29, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion docs/patterns/access.md
Original file line number Diff line number Diff line change
@@ -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 the 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.
12 changes: 11 additions & 1 deletion docs/patterns/issuer.md
Original file line number Diff line number Diff line change
@@ -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.
8 changes: 7 additions & 1 deletion docs/patterns/overview.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
# Digital Trust Patterns

## Work In Progress
Digital Trust interactions generally follow one (or more) of the 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/).
14 changes: 13 additions & 1 deletion docs/patterns/verifier.md
Original file line number Diff line number Diff line change
@@ -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).
10 changes: 9 additions & 1 deletion docs/solutions/endorser-service.md
Original file line number Diff line number Diff line change
@@ -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, once a connection with the endorser agent is established. `test` and `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.
2 changes: 1 addition & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading