1 - Certificate Generation

Generate Required Certificates

Note

This method of certificate generation is intended only for demonstration purposes with this reference architecture, and it is highly recommended this not be used in a production environment.

Background and Further Reading

The EU Digital Covid Certificate project uses and generates many different certificates and certificate authorities (CAs). A summary of the most important certificates and CAs has been included in the table below. For a full list of these, please refer to the upstream documentation for complete documentation of these certificates and CAs.

Owner Name Signed By CA Description
EU Trustanchor Self-Signed Root Certificate Authority (CA)
Country Auth Trustanchor The Auth cert is used to authenticate against the EU Gateway for read operations
Country Upload Trustanchor The Upload cert is used to authenticate against the EU Gateway for upload (write) operations
Country CSCA Trustanchor The Country Signing Certificate Authority (CSCA) is used to sign Document Signer Certificates
Country DSC Country CSCA The Document Signer Certificates (DSC) are used to sign individual Digital Covid Certificates
Individual DCC Country DSC The Digital Covid Certificate (DCC) that is issued to members of the general public

Generating the required certificates for the Reference Architecture

Use the following command from the root folder of the Git clone to automatically generate the necessary certs for use in a test environment. For a production deployment, please refer to the upstream dgc-participating-countries project for guidance on generating certificates, safe handling of certificates, and onboarding those certificates to the EU gateway.

$ make certs

[ .. SNIP .. ]

Signing IE Auth Cert
Signing IE CSCA Cert
Signing IE Upload Cert
DONE

Calls to Action

Read about deployment in the next section.

2 - Deployment

Deploy the EU Digital Green Certificate Reference Architecture

Set Variables

Below is a starter set of variables needed to deploy a simple example of the stack.

A full set of options is documented in the Terraform section.

We used a combined terraform.tfvars for all three steps, so combine any extra options needed into this single file.

Create a terraform.tfvars at the root of the repo that contains:

prefix                              = "<prefix>"
location                            = "northeurope"
subscription_id                     = "<id>"
tenant_id                           = "<id>"
parent_dns_zone_name                = "contoso.com"
parent_dns_zone_rg_name             = "<id>"
administrator_group_oid             = "<id>"
jumpbox_ssh_source_address_prefixes = []
ghcr_username                       = "<GH Username>"
ghcr_password                       = "<GH Password / Token>"
enable_azure_policy                 = true
Name Description Type Default Required
prefix Resource Name Prefix. Should be less than 6 chars. This is used to make sure some resource names are globally unique for some azure resources that require unique names (like Key Vault and Azure Container Registries) string "" no
location Location Name string n/a yes
subscription_id Subscription to deploy into string n/a yes
tenant_id Tenant to deploy into string n/a yes
parent_dns_zone_name Parent DNS Zone Name string n/a yes
parent_dns_zone_rg_name Parent DNS Zone Resource Group Name string n/a yes
administrator_group_oid OID of the Group to grant Administrator permissions. This is used to allow access to the deployed AKS cluster for deployments and troubleshooting string n/a yes
jumpbox_ssh_source_address_prefixes List of network prefixes allowed to SSH to Jumpbox VM list(string) [] no
ghcr_password GitHub Container Registry Personal Access Token (PAT) with read:packages access, Refer to Creating a personal access token for more information. string n/a yes
ghcr_username GitHub Container Registry Username string n/a yes
prefix Enable Azure Policy. Incase of Quota or duplication restrictions. these Policies can be enable and disabled through this boolean.) boolean "" no

Deployment

We offer two ways of doing the install, and all in one deployment, or a step by step, which can help you understand the difference resources, groups and terraform stacks.

All In One Deployment

Once the variables file has been created, the process of creating the infrastructure and deploying the application has been automated though terraform and scripts. Before initialing the deployment, Azure cli (az) must be logged in, you can log in by running az login. After logged, the process can be started by running make on the base directory of the project. This will create the required certificates and start the terraform deployment of the different components described in the step by step process.

➜ /workspaces/eu-digital-covid-certificates-reference-architecture (main) $ make

Step by Step Deployment

This section describes how to apply each step manually instead of getting invoked by the main make.

Step by Step - Terraform workspaces

Deployment is done via terraform, which supports workspaces for isolation between different deployments of the same infrastructure. In this case, we use the variable defined in prefix to create different terraform workspaces, so multiple users can perform a deployment in the same subscription. Running make workspace will go to the different terraform stacks and adjust the namespace.

➜ /workspaces/eu-digital-covid-certificates-reference-architecture (main) $ make workspace

Step by Step - Certificates

As describes in certificates doc section, project relies on certificates to ensure security as well as the green digital certificate itself. The process of generating the certificates has been automated in an script, it can be invoked with the required arguments/variables by make certs command.

➜ /workspaces/eu-digital-covid-certificates-reference-architecture (main) $ make certs

Step by Step - Jumpboxes

For security, none of the services used in this deployment, uses public endpoints (except of course the load balances), this prevents any public IP reaching the Databases or Key vault. This means that before connecting Kubernetes cluster (AKS) to perform deployments, we need to connect to jumphosts that have private connectivity to the services.

This step is performed by moving to the eudgc-dev and executing make. The first part of this make target will create the infrastructure for the jumpboxes using terraform, once the VMs are ready, it will create ssh configuration files (in eudgc-dev/jumpbox-ssh-configs folder) to facilitate the access to it as well as establishing the required tunnels to reach AKS clusters.

➜ /workspaces/eu-digital-covid-certificates-reference-architecture (main) $ cd eudcc-dev/
➜ /workspaces/eu-digital-covid-certificates-reference-architecture/eudcc-dev (main) $ make

Step by Step - EU Infrastructure

Each country service, relies on the “central” european gateway. The folder eudgc-eu contains the folder with the infrastructure and deployment of the gateway. The default make target (all), will first establish the required ssh tunnels to start the proxy in the VNET where the deployment will be made, enabling the deployment of the application after the AKS cluster is up and running.

➜ /workspaces/eu-digital-covid-certificates-reference-architecture/eudcc-dev (main) $ cd ../
➜ /workspaces/eu-digital-covid-certificates-reference-architecture (main) $ cd eudcc-eu/
➜ /workspaces/eu-digital-covid-certificates-reference-architecture/eudcc-eu (main) $ make

Step by Step - IE Infrastructure

The main applications of this deployment are the validation and rules services, that are deployed by each country and the mobile apps will contact to. Those services, as well as the EU are deployed into a kubernetes (AKS) cluster, applying the same security principles, only the HTTPS services being exposed. All the infrastructure and deployment is done via terraform, in the folder eudgc-ie.

➜ /workspaces/eu-digital-covid-certificates-reference-architecture/eudcc-eu (main) $ cd ../
➜ /workspaces/eu-digital-covid-certificates-reference-architecture (main) $ cd eudcc-ie/
➜ /workspaces/eu-digital-covid-certificates-reference-architecture/eudcc-ie (main) $ make

Calls to Action

Read about validation in the next section.

3 - Validation

Validation the deployment of the EU Digital Green Certificate Reference Architecture

Issue a Certificate

Issuing a Vaccine, Test or Recovery Certificate will validate that most of the components are up and running successfully, so this shoud be the first validation performed.

Open the Issuance Web Portal in your web browser by opening the following URL, replacing the two placeholders with the matching values from your terraform.tfvars file:

https://dgca-issusance-web.eudcc-ie.<prefix>.<parent_dns_zone_name>/

For example, the complete URL would be https://dgca-issusance-web.eudcc-ie.tst.contoso.com/ if your terraform.tfvars had the following options:

prefix               = "tst"
parent_dns_zone_name = "contoso.com"

Login to the Issuance Portal

Once you have determined the URL of the Issuance Web Portal and visted the URL in your browser, you will be presented with a login screen. Please login using your Azure Active Directory credentials.

Issuance Portal Login

Once logged in, the Issuance Web Portal homepage should be presented:

Issuance Portal Home

Issue a Vaccination Certificate

Choose the Record Vaccination Certification option, complete the required form fields, and choose Next to submit:

Issuance Portal Form

Once submitted, you will be presented with the Vaccine Certificate:

Issuance Portal Certificate

Import the Certificate into the Wallet Android App

TODO..

Verify a Certificate using the Verifier Android App

TODO..

Individual Component Validations

SSH to EU or IE Jumpboxes

During the creation of the eudgc-dev terraform stack, a Jumpbox is created for each of the EU and IE stacks, allowing secure access the Azure resources deployed. To SSH into these Jumpboxes, you can use the Azure CLI SSH extention which is preinsalled in the Codespace and DevContainer.

Stack Command
EU az ssh vm -g eudcc-eu -n eudcc-eu-dev-jumpbox-vm
IE az ssh vm -g eudcc-ie -n eudcc-ie-dev-jumpbox-vm

Access AKS

Begin by SSHing to the approperiate EU or IE Jumpbox, and the proceed with the steps below.

Login to Azure CLI

Start by logging into the Azure CLI, and selecting the correct subscription:

$ az login
$ az account set -s <subscription_id>

Login and Inspect the AKS Cluster

Next, login to the AKS Cluster:

$ az aks get-credentials -g eudcc-eu -n eudcc-eu-aks
$ kubectl get pods --all-namespaces

Calls to Action

Read about web authentication in the next section.

4 - Issuance Web Authentication Setup

Issuance Web Authentication Setup

Issuance Web Authentication

By default, when we deploy the issuance web application, the application is setup to allow all members of the AAD tenant to log into and issue certs.

This is due to the need for an admin to grant consent to applications that have been directly assigned to users without their direct consent recorded in the AAD portal.

Restricting Access to Specific users

  • Navigate to the Active directory blade in the Azure portal.
  • Search for the application name (The URL for issuance web that is printed at the end of the make terraform command, minus the “https://") e.g. “dgca-issuance-web.eudcc-ie.contoso.com” web auth search enterprise apps
  • Click on the “enterprise application” result
  • Click on properties
  • Switch “User assignment required?” to “Yes” web auth enterprise app propperties
  • Click on “Users and Groups”
  • Click “Add User/Group”
  • Search for either the user you want to grant access or the group that contains the users you want to add web auth add user and groups
  • Leave role as “Default Access”
  • Click “Assign”
  • Click “Permissions”
  • Click “Grant admin consent for ORGweb auth assign default access role