Set up Traction Contractor Credential Issuers for CSB/CDT

[loneil]

Note: this might need some refinement, couple TBDs
Checklist here can probably become some shared documentation for this type of onboarding in the future

Tracking tasks required to set up the Court Services Branch tenants that will be used for issuing the Contractor Credential and other decisions/TODOs

There will be 2 tenants:

CDT (this writes the Schema)

• Tenant name: BC Cyber Security and Digital Trust (https://candyscan.idlab.org/tx/CANDY_DEV/domain/34741)
• Technical contacts (Contact email in Tenant) (same for all envs):
  • Wade Barnes
  • Ivan Polchenko
  • Clecio Varjao

CSB (this creates the cred def based on CDT's schema)

• Tenant name: BC Court Services (https://candyscan.idlab.org/tx/CANDY_DEV/domain/34743)
• Technical contacts (Contact email in Tenant) (same for all envs):
  • Wade Barnes
  • Clecio Varjao
  • Michael Sakuraba

Tasks for setting up Issuer Tenants:
Note these can be tested out on the sandbox environment except that would use the BCOVRIN-TEST ledger and have automatic endorsement.

• Review Traction environment docs

Development environment

For CDT Tenant

• Create request for Tenant in DEV Tenant UI.
  This requires an IDIR to onboard. Traction Innkeeper (DITP team) will approve request for tenant creation.
  Note: don't think we have devhub step by step docs on onboarding/creating a tenant? Maybe in-app and email instructions are enough.
• Get approval back to email provided once DITP team approves. Use that 1-time password to create wallet (follow links in email)
• Save the wallet key in an agreed on secure location. Do not share with anyone!
  TODO: Who should get this key/where to store?
  • Me (Wade) - We have a place we store these types of credentials.
• Log in with key and create API Key
  See Integration Documentation for some details
• Become an issuer on Candy DEV. See docs
  Not in those docs but this will require some async steps with Endorser
• Appropriate person who is the Candy Dev Endorser accepts connection
• Once connection is accepted request DID publishing
• Appropriate person who is the Candy Dev Endorser endorses that transaction and...
  Note: in these cases are we adding the DID to the allow list in the Endorser
• Complete Issuer setup
• Add any necessary webhook endpoints back to the A2A app through the Tenant UI
• Through the Tenant UI create a schema with the schema def from the governance docs and keep the schema ID

For CSB Tenant

• Do all the same steps as above except stop at the "create a schema" step, (will create a cred def based on the schema created by the CDT tenant with steps below)
• Add any necessary webhook endpoints back to the A2A app through the Tenant UI
• On the Schema Storage screen use the Add Schema From Ledger and enter the CDT schema Schema ID made by the above tenant
• Create a Cred Def from that resultant added schema
  TODO: specify tag and rev reg size

Test environment

For CDT Tenant

• Create request for Tenant in TESTTenant UI.
  This requires an IDIR to onboard. Traction Innkeeper (DITP team) will approve request for tenant creation.
• Get approval back to email provided once DITP team approves. Use that 1-time password to create wallet (follow links in email)
• Save the wallet key in an agreed on secure location. Do not share with anyone!
• Log in with key and create API Key
  See Integration Documentation for some details
• Become an issuer on Candy TEST. See docs
  Not in those docs but this will require some async steps with Endorser
• Appropriate person who is the Candy Test Endorser accepts connection
• Once connection is accepted request DID publishing
• Appropriate person who is the Candy Test Endorser endorses that transaction and...
  Note: in these cases are we adding the DID to the allow list in the Endorser?
• Accept the TAA for Candy Test
  Note: is there anyone specific that must do this or other governance, what TAA acceptance type?
• Complete Issuer setup
• Add any necessary webhook endpoints back to the A2A app through the Tenant UI
• Through the Tenant UI create a schema with the schema def from the governance docs and keep the schema ID

For CSB Tenant

• Do all the same steps as above except stop at the "create a schema" step, (will create a cred def based on the schema created by the CDT tenant with steps below)
• Add any necessary webhook endpoints back to the A2A app through the Tenant UI
• On the Schema Storage screen use the Add Schema From Ledger and enter the CDT schema Schema ID made by the above tenant
• Create a Cred Def from that resultant added schema
  TODO: specify tag and rev reg size

Production environment

For CDT Tenant

• Create request for Tenant in Prod Tenant UI.
  This requires an IDIR to onboard. Traction Innkeeper (DITP team) will approve request for tenant creation.
• Get approval back to email provided once DITP team approves. Use that 1-time password to create wallet (follow links in email)
• Save the wallet key in an agreed on secure location. Do not share with anyone!
• Log in with key and create API Key
  See Integration Documentation for some details
• Become an issuer on Candy PROD. See docs
  Not in those docs but this will require some async steps with Endorser
• Appropriate person who is the Candy Prod Endorser accepts connection
• Once connection is accepted request DID publishing
• Appropriate person who is the Candy Prod Endorser endorses that transaction and...
  Note: in these cases are we adding the DID to the allow list in the Endorser?
• Complete Issuer setup
• Add any necessary webhook endpoints back to the A2A app through the Tenant UI
• Accept the TAA for Candy Prod
  Note: is there anyone specific that must do this or other governance, what TAA acceptance type?
• With the appropriate API calls in Swagger or with a script create a schema with the schema def from the governance docs and keep the schema ID
  By policy this is not allowed to do in the Tenant UI in production

For CSB Tenant

• Do all the same steps as above except stop at the "create a schema" step, (will create a cred def based on the schema created by the CDT tenant with steps below)
• Add any necessary webhook endpoints back to the A2A app through the Tenant UI
• Use API to add schema from ledger
• Create a Cred Def from that resultant added schema
  TODO: specify tag and rev reg size

[loneil]

From meeting discussion for onboarding steps
cc @WadeBarnes @krobinsonca @esune

[WadeBarnes]

For technical contacts, are we limited to a single contact, or can we have multiple?

[WadeBarnes]

@loneil, What documentation (steps) need to be followed in order to request the tenant for CSB.
cc @HemanthKona

[WadeBarnes]

@loneil, Once we have answers to enough of the questions to created the CDT tenants, we should walk through that together with @HemanthKona so he has an overview of what needs to be done with the CSB tenant.

[WadeBarnes]

There are no endorser rules configured for CANdy dev (or test); https://github.com/bcgov/dts-endorser-service/tree/main/configurations. Which indicates they are using their default configuration of being configured per-connection, until we define and register the necessary rules to allow these new agents to write to the ledgers.

[WadeBarnes]

Details on defining and publishing rules can be found here; https://github.com/hyperledger/aries-endorser-service?tab=readme-ov-file#granular-configuration-of-auto-endorsement

The related API docs (for dev) can be found here; https://aries-endorser-service-dev.apps.silver.devops.gov.bc.ca/endorser/docs

[loneil]

For technical contacts, are we limited to a single contact, or can we have multiple?

On the actual Tenant record in Traction there's just the 1. It's set to the email who requested the tenant and that fills into a "Contact Email" that can be changed through the management UI after it's created if need be.

@loneil, What documentation (steps) need to be followed in order to request the tenant for CSB. cc @HemanthKona

It's self-serve so I think should prompted through well enough by just going to the Tenant UI and starting the process, then there's emails sent to the requester confirming with details about next steps, and an email saying what to do once the approval happens. We don't have step by step documentation for this on devhub, may want to add that, or maybe the process is self-documented enough.
There is an (old, doesn't include IDIR login) video here https://github.com/bcgov/traction/blob/main/docs/USE-CASE-ONBOARD.md showing both sides of the reservation process.
But yeah for this I'd say just go to the UI and start and follow from there (note in dev/test/prod an IDIR is a requirement to get started, not in sandbox)

@loneil, Once we have answers to enough of the questions to created the CDT tenants, we should walk through that together with @HemanthKona so he has an overview of what needs to be done with the CSB tenant.

Sounds good

There are no endorser rules configured for CANdy dev (or test); https://github.com/bcgov/dts-endorser-service/tree/main/configurations. Which indicates they are using their default configuration of being configured per-connection, until we define and register the necessary rules to allow these new agents to write to the ledgers.

Yeah this part I wasn't sure of yet? Will the allow list for transactions here be on the DID, or specific to the particular schema or cred def.

[WadeBarnes]

There are no endorser rules configured for CANdy dev (or test); https://github.com/bcgov/dts-endorser-service/tree/main/configurations. Which indicates they are using their default configuration of being configured per-connection, until we define and register the necessary rules to allow these new agents to write to the ledgers.

Yeah this part I wasn't sure of yet? Will the allow list for transactions here be on the DID, or specific to the particular schema or cred def.

This is where I was going to start my work, fleshing out the rules for both agents and submitting a draft PR pending the details needed for the rules.

[WadeBarnes]

Draft rules with placeholders for the DIDs created here; bcgov/dts-endorser-service#51

[WadeBarnes]

I've proposed some tenant names and technical contacts in the description of this ticket. Confirming a technical contact for CSB.

[esune]

Draft rules with placeholders for the DIDs created here; bcgov/dts-endorser-service#51

For dev we usually have enabled auto-endorse once a connection is accepted, to facilitate independent development. test has been an ad-hoc process to validate with the issuer everything works as expected, prod uses rules. I'd be okay moving to a file-based ruleset for test as well, but am wondering whether we want that in dev or we should add a wildcard list there so we don't have to be on top of potentially a lot of requests.

[WadeBarnes]

Draft rules with placeholders for the DIDs created here; bcgov/dts-endorser-service#51

For dev we usually have enabled auto-endorse once a connection is accepted, to facilitate independent development. test has been an ad-hoc process to validate with the issuer everything works as expected, prod uses rules. I'd be okay moving to a file-based ruleset for test as well, but am wondering whether we want that in dev or we should add a wildcard list there so we don't have to be on top of potentially a lot of requests.

I'd like to see some rules defined. I'm fine with opening it up with wild cards in dev/test. My thought with the rules is we have some structure and pattern established. It makes sense for the rules to become more restrictive as they approach prod.

[WadeBarnes]

@esune, The discussion about the rules does raise a question though ... What is the order of precedence given to the rules? It's not explicitly defined in the documentation. There are the global settings, per connection settings, and granular settings (rules). I know the global settings take precedence over the per connection settings. Do the per connection settings then take precedence over the granular settings (rules)? I'm asking so we don't inadvertently break any of the existing agents we've configured with per connection settings by introducing the rules.

[esune]

@esune, The discussion about the rules does raise a question though ... What is the order of precedence given to the rules? It's not explicitly defined in the documentation. There are the global settings, per connection settings, and granular settings (rules). I know the global settings take precedence over the per connection settings. Do the per connection settings then take precedence over the granular settings (rules)? I'm asking so we don't inadvertently break any of the existing agents we've configured with per connection settings by introducing the rules.

When checking rules, the service will check if:

1. is it globally allowed
2. is it allowed for this connection
3. is it allowed by a configured "granular" setting (which could just have wildcards)

@Gavinok implemented the logic and should be able to

The idea with our deployments is that everything is set to deny-by-default and then allow as needed, either by using a granular rule OR allowing things on a per-connection basis.

[esune]

Also 👍🏻 to proposed tenant names

[Gavinok]

@WadeBarnes As far as priority the following code handles the rejection or endorsement
https://github.com/hyperledger/aries-endorser-service/blob/unique-index-connection_id/endorser/api/services/auto_state_handlers.py#L309-L338

ENDORSER_AUTO_ENDORSE_TXN_TYPES > Allow List API (rules) > ENDORSER_REJECT_BY_DEFAULT

[WadeBarnes]

When checking rules, the service will check if:

1. is it globally allowed
2. is it allowed for this connection
3. is it allowed by a configured "granular" setting (which could just have wildcards)

Perfect, thanks for confirming @esune and @Gavinok

[WadeBarnes]

For the dev environment:
The CDT and CSB tenants have been created, and endorser rules (minus the cred-def rules) have been registered with the endorser. The DIDs and schema have been written to CANdy dev.

• CDT DID: https://candyscan.idlab.org/tx/CANDY_DEV/domain/34741
• contractor-credential Schema: https://candyscan.idlab.org/tx/CANDY_DEV/domain/34742
• CSB DID: https://candyscan.idlab.org/tx/CANDY_DEV/domain/34743

We were unable to write the CSB cred-def rules due to errors encountered in the Swagger UI when attempting to post the rule file. @loneil will be following up on that.

We also did not write CSB's contractor-credential cred-def to the ledger. Partly due to the above issue, but also due to the fact that the Tenant UI does not support creating a cred-def from another issuer's schema, for example creating the CSB contractor-credential cred-def from the CDT contractor-credential schema. @loneil will follow-up on the steps needed to create the CSB cred-def from the CDT schema.

Ledger transactions were created through the tenant UI, endorser rules were registered by uploading the rules files through the endorser's swagger API.

[WadeBarnes]

A fix for the issues affecting the endorser rule registration has been deployed the dev.

[WadeBarnes]

@loneil, Do you want to try registering the endorser rules in dev again?

[loneil]

@loneil, Do you want to try registering the endorser rules in dev again?

This part's done in Candy DEV 👍

We also did not write CSB's contractor-credential cred-def to the ledger. Partly due to the above issue, but also due to the fact that the Tenant UI does not support creating a cred-def from another issuer's schema, for example creating the CSB contractor-credential cred-def from the CDT contractor-credential schema. @loneil will follow-up on the steps needed to create the CSB cred-def from the CDT schema.

I was mistaken about this I think, tried it out on one of my Tenants and believe just the Copy Schema From Ledger feature should work the way we want. Can go into the tenant UI as CSB tenant and

• in Schema Storage use the Copy
• enter the CDT Contractor Cred schema ID
• Once that copy is done, make a cred def from it on that new row (might need to refresh screen)\
• Will need to pick a rev reg size and tag name

[WadeBarnes]

• Will need to pick a rev reg size and tag name

rev reg size: 3000
tag: csb-dev

[loneil]

@WadeBarnes request from Kyle to do it with transcriber as the tag for lower envs too as when trying things out without OCA it will show "Csb Dev" as the credential name otherwise

Created a RSDAVyaiUjFPCj245PoY3P:3:CL:34742:transcriber in the CSB tenant as well, mostly to test out current endorsement rules are all good from the start. Can remove if there's an issue

[WadeBarnes]

@loneil, Looking to the future the cred-def is not specific to transcribers, the same cred-def would be used for other contracted services such as interpreters. So we should likely tag it as contractor or contractor-credential so it's more generic. Agree csd-dev is not great.

[krobinsonca]

@WadeBarnes - it depends on the use case, but in this case, I think the best solution would be to use different cred defs/tags for different purposes. For CSB, the next one would be "interpreter". There is certainly multiple ways to handle it though.

[esune]

@WadeBarnes - it depends on the use case, but in this case, I think the best solution would be to use different cred defs/tags for different purposes. For CSB, the next one would be "interpreter". There is certainly multiple ways to handle it though.

If the credential has the same access "power" and attributes regardless of the type of contractor, then it would definitely be easier to have a more generic tag as Wade is suggesting so the application does not have to include role management and tracking when issuing/revoking. If there is some sort of access control based on the role the user has in the system then the separate tags would be easy to implement.

[WadeBarnes]

I think managing cred-defs that differ in no other way other than tag for different use cases will not scale well and will end up causing confusion, at least at the human (developer) level. I can envision, even one of us, browsing the ledger and comparing the cred-defs and asking why there are two or more "identical" cred-defs.

[krobinsonca]

We already have this pattern established with the LCRB Training Credentials. There are three different cred-defs for the three different certificates (Serving It Right, Selling It Right and Special Event Server). They all use the same schema and are issued from the same DID. This is so the different proof requests can use the cred def restriction, in particular with the "OR" type clause.

[esune]

@krobinsonca how many different types of contractors do we forecast will have access to the systems? With LCRB it's never going to be more than 3 (I think?) and it has some specific meaning since teh credentials indicate different roles. If there are no distinct roles in the application - see my comment above - we may still do separate creddefs, but it might not really be beneficial and will increase the credential handling logic on issuance/reissuance/revocation - that's the main concern.

[WadeBarnes]

If we do continue to use this pattern, we have to ensure we make a conscious effort to educate the product teams (there could be many all from different vendors) as to the nuances of the differences, and ensure we/they ensure the correct cred-defs are machine selected and not left up to the end user issuing the credential to select.

[WadeBarnes]

I'm thinking it would be a good idea to deep dive into the requirements that caused this pattern to emerge to determine whether it's actually an anti-pattern and if there is a better way to accomplish the same thing in a more scalable fashion that does not require multiple cred-defs to be written to the ledger unnecessarily. I'm looking at this from a KIS and scalability perspective.