Onboarding Emma to a Virtual Company, issuing custom credentials, and utilizing dynamic verification policies.
In this tutorial, we will expand on the "My First VC" tutorial by now onboarding Emma to a virtual company. During the onboarding, Emma will receive an EmployeeID credential, which will be based on a custom credential template using the status property. With that, you learn about two more concepts; Custom credential templates and the status property. The credential will also have Emma's role as a property, which can then be checked with a dynamic verification policy, another new concept.
Where we start:
Using the walt.id SSI-Kit's REST API, we'll streamline access control within the company by
Establishing a Digital Identity (DID): The company will be set up as the issuer through its own Digital Identity (DID).
Creating an EmployeeID Template: This template will be used for generating verifiable credentials for employees.
Issuing a Verifiable Credential to Emma: Emma, an employee, will be issued a Verifiable Credential, making her the holder.
Authenticating with Door Access System: The system, acting as the Verifier, will:
Confirm Emma's employment status
Assess her role within the company
Grant or deny access to specific areas on the company campus based on the above.
Make sure you have Docker or a JDK 16 build environment including Gradle installed on your machine
Pull the docker container directly from docker hub and run the project
This will create a folder called data in your current directory as storage for the VC, DIDs, Keys and other things which need to be stored in order to provide all the functionality.
Clone the project
2. Change the folder
3. Run the project
The first time you run the command you will be asked to built the project. You can confirm the prompt.
Now with the SSI-Kit up and running, we can create the DID for the company, establishing its Digital Identity.
You have two options for creating a DID: executing a curl command or visiting the swagger docs. The custodian endpoint should be visible in the terminal after you have run the serve command, visit the endpoint to see the swagger docs.
Body Parameters
method: [string] method of the did. Value can be one of key, web, ebsi, iota, cheqd, jwk
Example
Create one DID for the company using the command above. In case you don't have done the My First VC tutorial and still have the DID for Emma, create another one for her. Make sure to save both, as we will be needing them later for the issuance of the EmployeID. You can also use the list DID endpoint to see all previously created DIDs.
The SSI-Kit supports the creation of credential templates, which are blueprints that establish reusable data structures based on which credentials can be issued.
Let's create one for an EmployeeID. The template will include the following properties:
id: Identifier for the employee
name: Name of the employee
role: Role or designation in the company
joiningDate: Date of joining the company
Path Parameters
id: The name for the credential template, which we will later reference during issuance. e.g. EmployeeID
Body Use the JSON structure from above as the body. Example
We can streamline the process of issuing a credential to Emma by utilizing the EmployeeID credential template. However, we also have the opportunity to further simplify the process using an additional feature: prefilling credential properties. This will be particularly beneficial as Emma likely won't be the only one receiving the Engineer role assignment. By creating a template where the Engineer role is prefilled, we can improve the issuance process.
You can now also save this template and use it later for the issuance of our VC, or use the one we created before and provide the value for the role attribute during issuance.
In order to issue Emma's EmployeeID VC, we will use one of the credential templates. Additionally, we will include a credential status so that we have the option to revoke the credential if Emma leaves the company without needing to remove it from her ownership. For more information on credential status and the types we support, read our guide.
Body Parameters
templateId: [string] The identifier of the template used for issuing a Verifiable Credential. In our case this would be the EmployeeID or EngineerEmployeeID template.
config: [object] Contains configuration parameters for the issuance process.
issuerDid: [string] The DID of the entity issuing the credential (University).
subjectDid: [string] The DID of the entity receiving the credential (Emma).
proofType: [string] Specifies the format and cryptographic algorithm used for the digital signature of the Verifiable Credential. E.g. LD_PROOF
statusType: [statusType] Specifies if the credential should be issued with status and the type of the status. Options StatusList2021Entry or SimpleCredentialStatus2022
credentialData: [object] Contains the actual data of the credential being issued.
credentialSubject: [object] Holds the information about the employee as described in the EmployeeID credential template.
The id in the credential subject we don't need to provide as this will be prefilled automatically with the DID of Emma.
Example EmployeeID:
Example EngineerEmployeeID:
Now we can use the issued VC in the company campus verification system.
To successfully authorize access, our authentication system needs to verify four crucial elements regarding the Verifiable Credential presented during the verification process:
Confirm the signature of the Verifiable Credential to ensure it's legitimate.
Ascertain the credential's validity by validating its current status, ensuring it has not expired or been revoked.
Verify that the issuer is indeed our company, thereby eliminating any fraudulent issuers.
Evaluate whether the role of the employee, as indicated on the credential, authorizes them to access the desired area.
To facilitate successful verification, we will use Verification Policies. For the initial two cases, which are relatively common, we can utilize our built-in policies, namely SignaturePolicy and CredentialStatusPolicy. These policies essentially verify that the signature is authentic and that the status is still valid.
For the additional cases, we will create custom policies, leveraging the Open Policy Agent (OPA) Engine and the REGO language. You can learn more about it here.
Please install the Open Policy Agent as described here, to ensure seamless verification.
Make sure to replace {issuerDID} with the DID of your issuer (company)
Creating Custom Policies - IsRole
This custom policy holds greater flexibility, as it accepts an argument containing a 'role' property. This property is then cross-verified with the role present in the Verifiable Credential. Alternatively, the role can be hardcoded, and the policy can be renamed accordingly, such as IsEngineer, similar to the IsCompany policy.
Path parameters:
policyName: [string] Name of the policy, e.g. IsCompany
Query parameters:
update: [boolean] Specifies if existing policy with same name should be overridden (if mutable)
downloadPolicy: [boolean] When using an URL to reference the to created policy. Downloads and/or saves the policy definition locally, rather than keeping the reference to the original URL\
Body
name: [string] Policy name, must not conflict with existing policies
description: [string] Optional policy description
input: [JSON] Input JSON object for rego query, which can be overridden/extended on verification. Can be a JSON string or JSON file
policy: [URL, REGO] Whole Policy or URL to policy definition.
dataPath: [JSON path] JSON path to the data in the credential which should be verified, default: "$" (whole credential object)
policyQuery: [string] The query string in the policy engine language. Defaults to
"data.system.main".
policyEngine: [string] Policy engine type, default: OPA. Options, OPA
applyToVC: [boolean] Apply/Don't apply to verifiable credentials (default: apply)
applyToVP: [boolean] Apply/Don't apply to verifiable presentation (default: don't apply)
Using the endpoint above, you can save both policies.
Now with the custom policies created, we will use those and the two predefined ones to verify Emma's credential and enable access.
Body
policies: [array] A list of policy definitions to verify against
policy: [string] The name/id of the policy
argument: [JSON] The argument needed by the policy (optional)
credentials: [array] An array of credentials in JWT, or LD_PROOF format
Congratulations, you've reached the finish line! 🎉 You have skillfully utilized an array of features to bring this use case to life. Now, you have the opportunity to explore further and deepen your understanding of the concepts introduced today. Happy building!
Credential Templates - Dive deeper into credential templates and what you can do with them
Credential Status - Learn more about the credential status property and what is enables.
Verification Policies - Explore our pre-build templates and learn more about how to build and leverage custom ones using OPA (Open Policy Agent) and the Rego language.