1 - Certificate Generation
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
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
Issue a Certificate
Navigate to the Issuance Web Portal
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.
Once logged in, the Issuance Web Portal homepage should be presented:
Issue a Vaccination Certificate
Choose the Record Vaccination Certification
option, complete the required form fields, and choose Next
to submit:
Once submitted, you will be presented with the Vaccine 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
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” - Click on the “enterprise application” result
- Click on properties
- Switch “User assignment required?” to “Yes”
- 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
- Leave role as “Default Access”
- Click “Assign”
- Click “Permissions”
- Click “Grant admin consent for ORG”