Skip to main content

UID2 Private Operator for Azure Integration Guide

This guide provides information for setting up the UID2 Operator Service in a Confidential Container, a confidential computing option from Microsoft Azure. Confidential containers run in a hardware-backed Trusted Execution Environment (TEE) that provides intrinsic capabilities such as data integrity, data confidentiality, and code integrity.

When the Docker container for the UID2 Operator Confidential Container starts up, it completes the attestation process that allows the UID2 Core Service to verify the authenticity of the Operator Service and the enclave environment that the Operator Service is running in.

When the attestation is successful, the UID2 Core Service provides seed information such as salts and keys to bootstrap the UID2 Operator in the secure UID2 Operator Confidential Container.

caution

UID2 Private Operator for Azure is not supported in these areas: Europe, China.

Prerequisites

Before deploying the UID2 Private Operator for Azure, complete these prerequisite steps:

Set Up UID2 Operator Account

Ask your UID2 contact to register your organization as a UID2 Operator. If you're not sure who to ask, see Contact Info.

When the registration process is complete, you'll receive an operator key, exclusive to you, that identifies you with the UID2 service as a Private Operator. During configuration, use this as the value for OPERATOR_KEY. This value is both your unique identifier and a password; store it securely and do not share it.

note

You'll receive a separate operator key for each deployment environment.

Install Azure CLI

Install the Azure command-line interface. For details, see How to install the Azure CLI in the Azure documentation.

Get the Required Azure Permissions

You'll need to have subscription owner permission so that you can create a resource group.

When that's done, you only need contributor permission on the resource group level for that resource.

For details, see Azure roles in the Azure documentation.

When all prerequisite steps are complete, you're ready to deploy the UID2 Private Operator. See Deployment.

Deployment Environments

The following environments are available. As a best practice, we recommend that you test and verify your implementation in the integration environment before deploying in the production environment.

note

You'll receive separate {OPERATOR_KEY} values for each environment. Be sure to use the correct key for the environment you're using. The deployment artifacts and the process flow are the same for both environments.

EnvironmentDetails
Integration (integ)For testing only. Debug mode is available in the integration environment.
Production (prod)For managing production traffic.

Deployment

To deploy a new UID2 Private Operator for Azure, you'll need to complete the following high-level steps:

Download ZIP File and Extract Files

The first step is to get set up with the deployment files you'll need:

  1. Download the ZIP file linked in the following table, Azure Download column, for the latest version.

  2. Unzip the ZIP file to extract the following files, needed for the deployment:

    • vault.json and vault.parameters.json
    • vnet.json and vnet.parameters.json
    • operator.json and operator.parameters.json
    • gateway.json and gateway.parameters.json

Operator Version

The latest ZIP file is linked in the Azure Download column in the following table.

ReleaseVersionDateRelease NotesAWS VersionGCP DownloadAzure Download
Q1 20245.26.19Feburary 13 2024v5.26.19-56899dc0d75.26.19-56899dc0d75.26.19-56899dc0d7 GCP ZIP5.26.19-56899dc0d7 Azure ZIP

Create Resource Group

In Azure, run the following command to create a resource group to run the UID2 operator:

az group create --name {RESOURCE_GROUP_NAME} --location {LOCATION}
info

All the resources are provisioned later under the name you provide as the {RESOURCE_GROUP_NAME} value.

There are some limitations with regard to location:

  • UID2 Private Operator for Azure is not supported in these areas: Europe, China.

  • For Azure virtual network deployment availability, check Linux container groups in the Azure documentation. You can only deploy to regions with the Confidential SKU column set to Y in the table.

Complete Key Vault and Managed Identity Setup

The next step is to set up a key vault and save the operator key in it.

When you've created the key vault, you can create a managed identity and grant it permission to access the key vault.

Later Azure Container Instances (ACIs) will launch as this identity.

Follow these steps:

  1. Update the vault.parameters.json file with the following required values:

    ParameterDescription
    vaultNameThe name of the key vault for hosting the operator key secret. The name you choose must be globally unique.
    operatorKeyValueThe OPERATOR_KEY secret value, which you received from the UID team as part of account setup (see Set Up UID2 Operator Account). This value is unique to you, and acts as a password: keep it secure and secret.
  2. (Optional) If you don't want to accept the defaults, update the vault.parameters.json file with the following values. These parameters have default values and in most cases you won't need to make any updates.

    ParameterDescription
    operatorIdentifierThe name of the managed identity that will launch the container.
    Default: uid-operator.
    operatorKeyNameThe operator key secret name.
    Default: operator-key.
  3. Run the following command to trigger the deployment:

    az deployment group create --name vault --resource-group {RESOURCE_GROUP_NAME} --parameters vault.parameters.json  --template-file vault.json

Set Up the VPC Network

The next step is to set up the VPC network.

The following diagram illustrates the virtual private cloud that hosts a UID2 Private Operator in Microsoft Azure.

VPC Network

Follow these steps:

  1. (Optional) If you don't want to accept the defaults, update the vnet.parameters.json file with the following values. These parameters have default values and in most cases you won't need to make any updates.

    ParameterDescription
    vnetNameThe virtual network name.
    Default: unified-id-network
    computeSubnetNameThe name of the subnet that runs the UID2 Operator.
    Default: unified-id-subnet-operators
    gatewaySubnetNameThe name of the subnet that runs the UID2 Gateway.
    Default: unified-id-subnet-gateway
    VnetAddressPrefixThe vnet address prefix.
    Default: 10.0.0.0/20
    computeSubnetPrefixThe vnet address prefix of the subnet that is delegated to run the UID2 Operator.
    Default: 10.0.0.0/24
    gatewaySubnetPrefixThe vnet address prefix of the subnet that runs the UID2 Gateway.
    Default: 10.0.1.0/28
  2. Run the following command to trigger the deployment:

    az deployment group create --name vnet --resource-group {RESOURCE_GROUP_NAME} --parameters vnet.parameters.json  --template-file vnet.json

Complete the UID2 Private Operator Setup

The next step is to bring up multiple Azure Container Instances (ACIs) in the VPC subnetwork that you created.

Follow these steps:

  1. Update the operator.parameters.json file with the following required values:

    ParameterDescription
    vaultNameThe name of the key vault for hosting the operator key secret. The value must match the name you created in Complete Key Vault and Managed Identity Setup.
    deploymentEnvironmentIndicates the environment you're deploying to: integ or prod. For details, see Deployment Environments.
  2. (Optional) If you don't want to accept the defaults, update the operator.parameters.json file with the following values. These parameters have default values and in most cases you won't need to make any updates.

    ParameterDescription
    operatorKeyNameThe operator key secret name. The value must match the value specified in Complete Key Vault and Managed Identity Setup. If you accepted the default, the value is operator-key.
    operatorIdentifierThe name of the managed identity that will launch the container. The value must match the value specified in Complete Key Vault and Managed Identity Setup. If you accepted the default, the value is uid-operator.
    vnetNameThe virtual network name. The value must match the value specified in Set Up the VPC Network. If you accepted the default, the value is unified-id-network.
    computeSubnetNameThe name of the subnet that will run the Private Operator. The value must match the value specified in Set Up the VPC Network. If you accepted the default, the value is unified-id-subnet-operators.
    countThe count for the number of instances you want to bring up. The default is 2.
  3. Run the following command to deploy the ACIs:

    az deployment group create --name operator --resource-group {RESOURCE_GROUP_NAME} --parameters operator.parameters.json  --template-file operator.json
  4. Get the IP addresses of the ACI instances you created by running the following command:

    az deployment group show -g {RESOURCE_GROUP_NAME} -n operator --query properties.outputs

    The output should look something like the following:

    { "ipAddress": { "type": "Array", "value": [ "10.0.0.5", "10.0.0.4" ] } }

Set Up the Gateway Load Balancer

The next step is to set up the Gateway Load Balancer, which takes the private IP addresses of the ACIs you created and uses them as a backend pool.

Follow these steps:

  1. Update the gateway.parameters.json file with the following required value:

    ParameterDescription
    containerGroupIPsThe IP addresses of the ACI instances you created—the values output as a result of Complete the UID2 Private Operator Setup Step 4.

    For example, the updated file might look something like the following:

    "containerGroupIPs":{
    "value":[
    "10.0.0.5",
    "10.0.0.4"
    ]
    }
  2. (Optional) If you don't want to accept the defaults, update the gateway.parameters.json file with the following values. These parameters have default values and in most cases you won't need to make any updates.

    ParameterDescription
    vnetNameThe virtual network name. The value must match the value specified in Set Up the VPC Network. If you accepted the default, the value is unified-id-network.
    gatewaySubnetNameThe name of the subnet that runs the UID2 Gateway. The value must match the value specified in Set Up the VPC Network. If you accepted the default, the value is unified-id-subnet-gateway.
  3. Run the following command:

    az deployment group create --name gateway --resource-group {RESOURCE_GROUP_NAME} --parameters gateway.parameters.json  --template-file gateway.json
  4. Get the public IP address of the Gateway Load Balancer by running the following command:

    az deployment group show -g {RESOURCE_GROUP_NAME} -n gateway --query properties.outputs

    The output should look something like the following:

    { "gatewayIP": { "type": "String", "value": "20.163.172.56" } }
tip

If you update the container, the Azure backend pool is not automatically updated with the IP address for the new container. For solutions, see Automate infrastructure reconfiguration by using Azure in the Azure documentation.

caution

This example deploys a Gateway Load Balancer with HTTP. We strongly recommend you set up SSL. For instructions, see Tutorial: Configure an Application Gateway with TLS termination using the Azure portal in the Azure documentation.

Running the Health Check

Call the health check endpoint to test the health of your implementation.

Running the health check is the same for the integration and production environments, except for the endpoints.

Follow these steps:

  1. Get the public IP address for the Gateway Load Balancer—the value output as a result of Set Up the Gateway Load Balancer Step 4.

  2. To test operator status, in your browser, go to the health check endpoint: http://{LB_IP}/ops/healthcheck.

    An HTTP 200 with a response body of OK indicates healthy status.

Private Operator Attestation Failure

When a private operator fails to attest with the core service, one of the following actions happens:

  • HTTP 401 response. The Private Operator terminates itself immediately.
    • Likely Causes: API key revoked or incorrect.
  • Any other non-200 response code. The Private Operator continues to function for 12 hours. If the issue is not resolved in this time frame, it terminates itself.
    • Likely Causes: Core service issues, network issues.

Private Operator hosts must have infrastructure in place to handle alerting and restarting operators in the case of an error.

Upgrading

When a new version of UID2 Azure Confidential Container is released, private operators receive an email notification of the update, with a new release link. There is a window of time for upgrade, after which the older version is deactivated and is no longer supported.

To upgrade, complete the following steps:

  1. Follow the instructions in Download ZIP File and Extract Files to download the deployment file for the new version and then unzip it.

  2. Follow the instructions in Complete the UID2 Private Operator Setup, using the new files, to deploy ACIs with new versions.

  3. Follow the instructions in Set Up the Gateway Load Balancer to add the new ACIs to the backend pool.

  4. Check the health of the new ACIs and make sure the status is healthy, as shown in the following example:

    az network application-gateway show-backend-health --resource-group {RESOURCE_GROUP_NAME} --name uid-operator-gateway
  5. Clean up old ACIs from the Gateway Load Balancer: Follow the instructions in Set Up the Gateway Load Balancer to remove the old ACIs from the backend pool.

  6. Shut down old ACIs by running the following command:

    for i in {0..COUNT}; az container delete --name uid-operator-OLD-VERSION-$i --resource-group {RESOURCE_GROUP} --yes