openg2p-vci

Introduction

This repository contains Odoo modules that help PBMS/Registry to issue Verifiable Credentials (VC). This repo also provides default VC templates for both Registry and PBMS. This repo also adds OpenID for VCI APIs to both Registry and PBMS.

Odoo modules

This repository contains the following modules:

G2P OpenID VCI

Module Name: g2p_openid_vci

Source Code: https://github.com/openg2p/openg2p-vci

• This module adds g2p.openid.vci.issuers model, called "VC Issuer". Following are the main fields in this VC Issuer model.

  • issuer_type selection field decides the functionality of this VC Issuer. If issuer_type is Registry , it is issuing Registry Credentials.

  • credential_format is a Jq expression, which is supposed to define the format/template of the final verifiable credential.

  • credential_type is nothing but a name given to VC of this format. Example "FarmerIDVerifiableCredential", "StudentVerifiableCredential", or something generic like "OpenG2PRegistryVerifiableCredential" etc.

  • issuer_metadata_text is a Jq expression, which is supposed give out metadata of this issuer, and metadata of the fields in the credential.

  • context_json is the JSON-LD context of this VerifiableCredential.

  • scope is OIDC authentication scope. In other words this issuer will only respond to requests for which the auth scope matches the scope configured here. Example scopes; farmer_id_vc_ldp , etc.

  • Further this also adds parameters to configure authentication. Like allowed auth token issuers, allowed auth token audience, which Registrant ID is present in the auth token subject, etc.

  • Refer to Configuration for complete configuration reference.

• Any number of issuers can be created with different combinations of scope, credential_type, credential_format, issuer_metadata.

• Say you want to issue two types of credentials from your registry, each of which needs different fields to be placed in the credential, then follow this:

  • Create two issuers, both issuer_types are Registry .

  • Configure different credential types and scopes for both issuers.

  • Configure the credential format of both the issuers with the relevant fields to be placed.

  • Modify the issuer metadata of both the issuers along with relevant metadata for the fields.

  • Modify contexts json with different fields and different credential type for both issuers.

• When a credential request is received, it will select the issuer based on the combination of scope (from auth JWT), credential type (from credential request body) (and supported_format which defaults to ldp_vc for now).

• This module also uses g2p.encryption.provider (of any type) to sign the final VC. If encryption provider is not configured on the issuer, it will use the default encryption provider.

• A credential will only be issued if the sub from auth JWT exists as one of IDs in registry against a registry entry.

G2P OpenID VCI: Programs

Module Name: g2p_openid_vci_programs

Source Code: https://github.com/openg2p/openg2p-vci-beneficiary

• This extends the "G2P OpenID VCI" module, by adding a new issuer type called Beneficiary. This effectively adds ability to issue VC for beneficiaries that are part of a program in PBMS.

• This adds a parameter to attach a Program to an Issuer. With this each Program in PBMS is an issuer.

• For example, if three programs are running on PBMS, 3 different issuers can be created with issuer_type as "Beneficiary" and different programs.

  • Configure 3 different scopes for the three issuers. Example:

    • IssuerName: "SafetyNetIssuer", scope: "safety_net_program_vc_ldp", Program: "Safety Net Program".

    • IssuerName: "HumAidIssuer", scope: "hum_aid_program_vc_ldp", Program: "Humanitarian Aid Program", etc.

  • If the content of the credential is the same for all the 3 programs, then use a generic credential_type and format across all three issuers, like "OpenG2PBeneficiaryVerifiableCredential". If the content is different in all programs, use different credential types.

• Unlike a Registry VC, a Beneficiary may contain additional data, like name of Program, duration for which this beneficiary is part of the program, last date till which this beneficiary is part of program, etc. All these are supported by this module.

• A credential will only be issued if the sub from auth JWT exists as one of IDs in registry against a registry entry, and that registrant is also an enrolled beneficiary of the said program.

• Rest of the functionality from the base module remains the same.

G2P OpenID VCI: Rest API

Module Name: g2p_openid_vci_rest_api

Source Code: https://github.com/openg2p/openg2p-vci

• This module exposes the following OpenID for VCI REST APIs.

  • /api/v1/vci/credential API - the main credential request API. This first gets the issuer based on scope, credential type, and supported format. Then verifies verifies and validates auth JWT based on issuer config. Then retrieves registrant data based on issuer config and auth JWT sub. And then issues credential based on credential format.

  • /api/v1/vci/.well-known/openid-credential-issuer API - Issuer metadata API. This will collate the issuer_metadata of all issuers and return.

    • It is also possible to get individual metadata of each issuer by suffixing the above API with Issuer Name. Example /api/v1/vci/.well-known/openid-credential-issuer/SafetyNetIssuer .

  • /api/v1/vci/.well-known/contexts.json API - All the contexts from all the Issuers are collated and returned on this API. This path will be included in as context path within the VC.

Create a custom VC Issuer

This section describes procedure for developing custom VC Issuers with custom functionality that is different from the above Registry Credential Issuer and Beneficiary Credential Issuer.

• Inherit g2p.openid.vci.issuers model. Add a new type to the issuer_type Selection field using selection_add. Example

  issuer_type = fields.Selection(selection_add=[("Mock", "Mock")], ondelete={"Mock": "cascade"})

• Implement the following functions:

  • issue_vc_{issuer_type}

  • set_default_credential_type_{issuer_type}

  • set_from_static_file_{issuer_type}

• Example:

  class BeneficiaryOpenIDVCIssuer(models.Model):
      _inherit = "g2p.openid.vci.issuers"
  
      issuer_type = fields.Selection(selection_add=[("Mock", "Mock")], ondelete={"Mock": "cascade"})
      
      def issue_vc_Mock(self, auth_claims, credential_request):
          ...    
      
      def set_default_credential_type_Mock(self):
          self.credential_type = "OpenG2PMockVerifiableCredential"
  
      def set_from_static_file_Mock(self, **kwargs):
          kwargs.setdefault("module_name", "g2p_openid_vci_mock")
          return self.set_from_static_file_Registry(**kwargs)

Configuration

• VCI Issuers' configs can be found under Settings Menu -> VCI Issuers Page.

• VC Issuer general config properties:

Name	Property name	Description
Name	name	Name of this issuer.
Scope	scope	Scope that is to be accepted in authentication.
Issuer Type	issuer_type	Type of Issuer
Supported Format	supported_format	VC Format supported. Defaults to ldp_vc .
Unique Issuer ID	unique_issuer_id	A unique id (string) assigned to this issuer. Defaults to did:example:12345678abcdefgh .
Encryption Provider	encryption_provider_id	Encryption Provider. If left blank, it will choose default encryption provider.
Auth Subject ID Type	auth_sub_id_type_id	Type of ID which is present in Subject of Authentication.
Auth Allowed Audiences	auth_allowed_auds	Only authentications with "aud" from this list will be allowed. Seperated by space/newline. If left blank, audience in auth will be ignored.
Auth Allowed Issuers	auth_allowed_issuers	Only authentications with "iss" from this list will be allowed. Seperated by space/newline.
Auth Issuer Jwks Mapping	auth_issuer_jwks_mapping	JWKs Url of each issuer from "Auth Allowed Issuers". If there are 3 entries in "Auth Allowed Issuers", then there should 3 Jwks urls in this too, one for each iss. Seperated by space/newline.
Auth Allowed Client IDs	auth_allowed_client_ids	Only authentications with "client_id" from this list will be allowed. Seperated by space/newline. If left blank, client_id in auth will be ignored.
Credential Type	credential_type	Type of the VC. Leave it blank to take the default value, according to Issuer Type.
Credential Format	credential_format	Credential format as Jq expression. Leave it blank to take the default value, according to Issuer Type.
Issuer Metadata Text	issuer_metadata_text	Issuer Metadata as Jq expression. Leave it blank to take the default value, according to Issuer Type.
Contexts Json	contexts_json	Contexts Json for this credential Type. Leave it blank to take the default value, according to Issuer Type.

• VC Issuer Program/Beneficiary specific configs:

Name	Property Name	Description
Program	program_id	Program for which we are issuing the Beneficiary VC.