Add-on installation

Caution

The progress of the add-on installation is not saved automatically. If you are unable to complete the installation in one go, make sure to retain a copy of all the values you filled-in or copied into the installer. To continue the installation later, start the installation again and copy-paste all the values you already filled in.

Start the installation

1. Navigate to the Schoolyear Admin dashboard

2. Start the installation by clicking Add > Azure Virtual Desktop, select the version that matches the version of this documentation and click Start installation.

3. When you are unable to complete the installation in one go, make sure to keep a copy of all the values you filled-in or copy-pasted up to that point. To seamlessly continue later, simply copy-paste previously filled-in values up to the step where you left off.

Prerequisites

In this step, you’ll name your add-on installation and verify prerequisites. The name you choose will be visible to Schoolyear Admins for display purposes.

Review the prerequisites carefully, mark them as confirmed, and proceed to the next step.

Entra ID setup

The Schoolyear AVD integration requires an App Registration to be created in Entra. This step requires write access to Entra, which in many organizations is closely guarded. You may need the assistance of authorized personnel.

You can pick the name of the App Registration yourself to make sure it fits the naming conventions of your organization. Make sure to fill in the name before copying the command.

Caution

Make sure to switch to the correct Subscription before executing the command as shown in the installer.

Make sure to audit the command before executing it.

The command outputs a JSON object that starts with { and ends with }. Copy-paste this object back into the add-on installer. This object contains an API, which is a sensitive value.

Connect Entra ID with AVD

By default, Azure Virtual Desktop may prompt users to grant access to the VM they are about to connect to. This causes a bad user experience in general and, in fact, does not work in the browser in Schoolyear. That makes this step mandatory.

This step requires write access to Entra, which in many organizations is closely guarded. You may need the assistance of authorized personnel.

In this step, you will create a Dynamic Group in Entra and configure it such that every VM created by the Schoolyear AVD integration is added to this group. Then, Entra is configured to not show the prompt for any VM in this group.

Since this configuration is global for your Azure tenant, you only need to perform this step once per Azure tenant. We still recommend running this script each time you perform a Schoolyear AVD implementation, but it is recommended to use the same Dynamic Group Name across all these implementations.

Deploy Azure integration

In this step you will deploy all the Azure resources required by the Schoolyear AVD integration. Follow along with the steps in the installer.

After clicking Deploy to Azure, make sure to start by selecting the Subscription you dedicated to this implementation. If your Subscription is not visible, it may be due to the required Resource Providers not being registered properly. Revisit the prerequisites in that case.

Danger

The options you configure during this deployment cannot be changed later. Make sure you review them before deploying the template.

Pay special attention to the network section if you are planning on connecting a license server. In that case, you will need to create a network peering, which requires a non-overlapping network range with your existing Azure networking.

After starting the deployment, wait for it to finish and copy-paste the output parameter of the deployment back to the add-on installer. You will find this parameter under the Outputs tab of the deployment.

Configure exam resources

The Schoolyear AVD integration automatically deploys and deletes resources for each exam that uses the integration. If your Azure tenant enforces specific naming conventions or tags to be applied to resources, you can configure that in this step. If not, you can skip this step.

If your tenant has such policies, and you misconfigure this step, your exam deployments will fail. In that case, you can edit these values later in the AVD add-on.

Connect DNS

In a previous step you deployed a new public DNS zone as part of the larger deployment in Azure. Now, you need to configure your own public DNS zone to delegate a subdomain to this new DNS zone. This is done by creating a NS record, sometimes called a Delegation.

Follow the steps in the installer and check if you set it up correctly by clicking the Query NS record. Depending on your DNS server, it may take a couple of minutes to propagate the changes you made.

Some customers have separate DNS servers/resolvers for on-campus and off-campus. In that case, make sure to configure the delegation for both. The installer will only check the publicly available resolver.

Import certificate

The Schoolyear AVD integration requires an SSL wildcard certificate for the subdomain you configured during the installation. For example, if you configured syproxy.example.com, you need an SSL certificate for *.syproxy.example.com. A wildcard certificate is required because each exam is hosted on a subdomain of the domain you configured (e.g. 123.syproxy.example.com).

Some organizations have policies against wildcard certificates because they are commonly misused. However, in this case, the wildcard certificate is used for what these are designed to do: provide SSL encryption for dynamically changing hostnames.

This SSL certificate can be requested from your regular supplier, or you can follow along with the guide below to request one from Let’s Encrypt free of charge.

Follow the steps in the installer to upload the certificate to the Key Vault in Azure. When you import the certificate into the Key Vault, you must configure a name for it. Make sure to copy-paste this name into the add-on installer.

Even global Azure Administrators do not have the permission to import certificates into Key Vaults. Most likely, you will have to grant yourself the Key Vault Administrator role on the Resource Group the Key Vault belongs to.

Caution

Uploading a certificate without all required parts is our most commonly reported issue. To avoid this, ensure your Azure certificate upload includes the complete certificate chain, this means the main certificate plus all intermediate and root certificates.

Tip

If your certificate request process involves creating a DNS record in the DNS zone of the dedicated subdomain, you must create this records in the newly created DNS zone in Azure, not in the DNS zone/resolver in which you configured the NS/delegation record in a previous step.

You can find the new DNS zone in the Azure Portal, by searching for DNS Zone resources and filtering on the Subscription dedicated to this implementation.

Using Let’s Encrypt

Note

This step guides you through requesting a wildcard certificate from Let’s Encrypt. If you obtained your certificate in a different way, you can skip this step.

macOS and Linux

1. Install the certbot CLI tool on your machine. See https://certbot.eff.org/instructions for the most up-to-date installation instructions.

2. Install the openssl CLI tool on your machine. You can use brew or choco for this or use your preferred method.

   macOS (brew)

   brew install openssl

   Linux (apt)

   apt install openssl

   Linux (yum)

   yum install openssl

3. Open a terminal in a temporary directory you can easily delete at the end.

4. Start the request process. Make sure you fill in your own domain (including the *.) and email.

   certbot \
      -d "*.syproxy.contoso.com" \
      --manual \
      --preferred-challenges dns \
      certonly \
      --agree-tos \
      --email "you@example.com" \
      --config-dir ./config \
      --work-dir ./work \
      --logs-dir ./logs

5. Certbot will instruct you to create a TXT DNS entry in your newly created DNS zone. Follow these instructions. Once you complete the instructions and the certificate is issued, Certbot will show you the path in which the certificate is stored. Note down this path, as you need it in the following step.

6. Run the following command to pack the two files created by Certbot into a single certificate file. that can be imported into the KeyVault. Replace path with the path Certbot gave you in the previous step. This command will ask you for a password. You can generate a temporary password using your preferred method. You will only need it in the following step.

   openssl pkcs12 -export \
      -out cert.pfx \
      -in path/cert.pem \
      -inkey path/privkey.pem \
      -certfile path/chain.pem

7. Navigate to the KeyVault you created earlier. Go to “Certificates” and click “Generate/Import”. Upload the cert.pfx you created using openssl and the password from the previous step. Name the certificate proxycertificate.

8. Delete the temporary directory you created in step 2.

Windows

Certbot no longer supports Windows. You can use one of the alternative tools to request a certificate from Let’s Encrypt or you can purchase one from a commercial supplier.

Finish

Make sure to finish the installation before closing your browser window. Once you have completed the installation, you will see the newly installed add-on. You can always come back to the add-on to update the configuration.