UID2 Private Operator for AWS Integration Guide

The UID2 Operator is the API server in the UID2 ecosystem. For details, see The UID2 Operator.

For a Private Operator service running in AWS Marketplace, the UID2 Operator solution is enhanced with AWS Nitro Enclave technology. This is an additional security measure to help protect UID2 information from unauthorized access.

UID2 Private Operator for AWS

note

UID2 Private Operator for AWS is a free product. The cost displayed on the product page is an estimated cost for the necessary infrastructure.

By subscribing to UID2 Private Operator for AWS, you gain access to the following:

• Amazon Machine Image (AMI) with the UID2 Operator service installed and ready to bootstrap:
  The AMI contains an Amazon Linux 2023 operating system with the UID2 Operator service already set up. When an EC2 instance based on the AMI boots up, it automatically fetches the configuration from your AWS account and starts the UID2 Operator server inside an enclave.
• CloudFormation template:
  The template deploys the UID2 Operator AMI.

Prerequisites

To subscribe and deploy one or more UID2 Operators on AWS, complete the following steps:

1. Register your organization as a UID2 Operator.
2. Create an AWS account with an IAM role that has the minimal privileges.

Minimal IAM Role Privileges

To succeed in a one-click deployment, your AWS account must have the privileges to run the following actions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ec2:*",
                "kms:*",
                "autoscaling:*",
                "cloudformation:*",
                "iam:ListRoleTags",
                "secretsmanager:*",
                "iam:PutRolePolicy",
                "iam:AddRoleToInstanceProfile",
                "iam:ListRolePolicies",
                "iam:ListPolicies",
                "iam:GetRole",
                "iam:GetPolicy",
                "iam:DeleteRole",
                "iam:UpdateRoleDescription",
                "iam:TagPolicy",
                "iam:GetRolePolicy",
                "iam:CreateInstanceProfile",
                "iam:UntagRole",
                "iam:TagRole",
                "iam:ListInstanceProfilesForRole",
                "iam:PassRole",
                "iam:DeleteRolePolicy",
                "iam:ListPolicyTags",
                "iam:DeleteInstanceProfile",
                "iam:ListRoles",
                "iam:CreatePolicy",
                "iam:UntagPolicy",
                "iam:UpdateRole",
                "iam:UntagInstanceProfile",
                "iam:TagInstanceProfile",
                "iam:SetDefaultPolicyVersion",
                "iam:UpdateAssumeRolePolicy",
                "iam:GetPolicyVersion",
                "iam:RemoveRoleFromInstanceProfile",
                "iam:CreateRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:ListAttachedRolePolicies",
                "iam:DeletePolicy",
                "iam:ListInstanceProfileTags",
                "iam:CreatePolicyVersion",
                "iam:GetInstanceProfile",
                "iam:ListInstanceProfiles",
                "iam:ListPolicyVersions",
                "iam:DeletePolicyVersion",
                "iam:ListUserTags"
            ],
            "Resource": "*"
        }
    ]
}

Resources Created

The following table lists all resources that are created during the deployment.

Name	Type	Description
KMSKey	AWS::KMS::Key	Custom KMS key used for encrypting the secrets in AWS Secrets Manager.
SSMKeyAlias	AWS::KMS::Alias	An alias that provides an easy way to access the KMS key.
TokenSecret	AWS::SecretsManager::Secret	A Secrets Manager secret to store the operator key.
WorkerRole	AWS::IAM::Role	The IAM role that your UID2 Operators run as. The role provides access to AWS Secrets Manager to retrieve operator keys.
WorkerInstanceProfile	AWS::IAM::InstanceProfile	The instance profile with Worker Role to attach to Operator EC2 instances.
SecurityGroup	AWS::EC2::SecurityGroup	A security group policy that provides rules for operator instances. See also Security Group Policy.
LaunchTemplate	AWS::EC2::LaunchTemplate	A launch template with all configurations in place. You can spawn new UID2 Operator instances from it.
AutoScalingGroup	AWS::AutoScaling::AutoScalingGroup	An auto-scaling group (ASG) to which the launch template is attached. You can use this to update the desired number of instances later, if needed.

Customization Options

Here's what you can customize during or after the deployment:

• VPC: You must specify the existing VPC and related VPC Subnet IDs.
• Root volume size (8G Minimum)
• SSH key: This is the SSH key that you use to access the UID2 Operator EC2 instances.
• Instance type: m5.2xlarge, m5.4xlarge, and so on. If there is no customization, the default value, m5.2xlarge, is recommended.

Security Group Policy

note

To avoid passing certificates associated with your domain into the enclave, inbound HTTP is allowed instead of HTTPS. This also avoids the cost of a secure layer, if used in a private network that is internal to your organization.

Port Number	Direction	Protocol	Description
80	Inbound	HTTP	Serves all UID2 APIs, including the healthcheck endpoint /ops/healthcheck. When everything is up and running, the endpoint returns HTTP 200 with a response body of OK. For details, see Checking UID2 Operator Status.
9080	Inbound	HTTP	Serves Prometheus metrics (/metrics).
443	Outbound	HTTPS	Calls the UID2 Core Service, AWS S3, to download files for opt-out data and key store.

VPC Chart

The following diagram illustrates the virtual private cloud that hosts private operators.

Deployment

To deploy UID2 Operator on AWS Marketplace, complete the following steps:

1. Subscribe to Unified ID 2.0 Operator on AWS Marketplace. It might take several minutes before AWS completes your subscription.

2. Click Configuration and then specify configuration values.

   For software version, see Operator Version and choose the value in the AWS Version column.

3. On the Configuration page, click Launch and then select the Launch CloudFormation action.

4. In the Create Stack wizard, specify the template and then click Next. The S3 path for the template file is automatically filled in.

5. Fill in the stack details and then click Next.

6. Configure the stack options and then click Next.

7. Review the information you have entered, and make changes if needed.

8. If you are prompted for permission to create IAM roles, select the I acknowledge that AWS CloudFormation might create IAM resources checkbox.

9. Click Create stack.

It takes several minutes for the stack to be created. When you see an Auto Scaling Group (ASG) created, you can select it and check the EC2 instances. By default, there is only one instance to start with.

Operator Version

The latest ZIP file is linked in the Release Notes column in the following table.

Release	Version	Date	Release Notes	AWS Version	GCP Download	Azure Download
Q2 2024	5.37.12	June 12, 2024	v5.37.12	5.37.12	gcp-oidc-deployment-files-5.37.12.zip	azure-cc-deployment-files-5.37.12.zip
Q3 2024	5.38.104	September 12, 2024	v5.38.104	5.38.104	gcp-oidc-deployment-files-5.38.104.zip	azure-cc-deployment-files-5.38.104.zip
Q3 2024 Out-of-band	5.41.0	October 29, 2024	v5.41.0	5.41.0	gcp-oidc-deployment-files-5.41.0.zip	azure-cc-deployment-files-5.41.0.zip
Q1 2025	5.49.7	Mar 19, 2025	v5.49.7	5.49.7	gcp-oidc-deployment-files-5.49.7.zip	azure-cc-deployment-files-5.49.7.zip

Stack Details

The following images show the Specify stack details page in the Create stack wizard (deployment step 5). The table that follows provides a parameter value reference.

Lower part of the page:

The following table explains the parameter values that you need to provide in step 5 during the deployment.

Parameter	Description
Stack name	Any name of your choice.
OPERATOR_KEY	The Operator Key that you received from the UID2 Admin team.
UID2 Environment	Select prod for production environment or integ for the integration test environment.
Instance Type	m5.2xlarge is recommended.
Instance root volume size	15 GB or more is recommended.
Key Name for SSH	Your EC2 key pair for SSH access to the deployed EC2 instances.
Trusted Network CIDR	The CIDR (Classless Inter-Domain Routing) value determines the IP address range that can access your operator service. To limit access to the UID2 Operators so that they can only be accessed through an internal network or a load balancer, specify an internal IP range as the CIDR value.
VPC	The existing VPC ID.
VpcSubnet1	The existing VPC AZ1 Subnet ID.
VpcSubnet2	The existing VPC AZ2 Subnet ID.

Stack Configuration Options

The following image shows the Configure stack options page in the Create stack wizard (deployment step 6).

The following table explains the parameter values that you need to provide in step 6 during the deployment.

Parameter	Description
Tags	(Optional) Tag your stack.
Permissions	If you have separate IAM roles subscribing to AWS marketplace and deploying the stack, enter the name/ARN of the role you will use to deploy the stack.
Stack failure options	Choose what happens when deployment fails. The Roll back all stack resources option is recommended.
Advanced options	These are optional.

Creating a Load Balancer

To create a load balancer and a target operator auto-scaling group, complete the following steps:

1. In the AWS Console, navigate to the EC2 dashboard and search for Load Balancer.
2. Click Create Load Balancer.
3. On the Load balancer types page, in the Application Load Balancer section, click Create.
4. Enter the UID2 Load balancer name. Depending on whether or not you need to access UID2 APIs from public internet, choose the Internet-facing or Internal scheme.
5. Select the VPC you used while creating the CloudFormation stack, and at least two subnets.
6. Under Security groups, click Create new security group and do the following:
   1. Enter UID2SGALB as its Security group name, as well as a relevant Description.
   2. Under Inbound rules, click Add rule, then select the HTTPS Type and an appropriate Source according to your requirements.
   3. Click Create security group.
7. Go back to the Load Balancer page and select the newly created UID2SGALB security group.
8. Under Listeners and routing, click the Create target group link and do the following:
   1. On the Specify group details page, select Instances as the target type, then enter UID2ALBTG as the Target group name.
   2. Ensure HTTP1 is selected as the Protocol version.
   3. Under Health checks, provide /ops/healthcheck as the Health check path, and then click Next.
   4. Select UID2 Operator EC2 Instances created by your auto-scaling group and then click Include as pending below.
   5. Make sure that all the ports for the targets contains 80.
   6. Click Create target group.
9. Go back to the Load Balancer page, and under Listeners and routing, select UID2ALBTG as the target group to forward to as a default action. Note that you may have to refresh the target groups for your newly created target group to appear. Change the listener Port value to 443.
10. Set up an HTTPS listener by following the instructions in the AWS user guide.
11. Click Create load balancer.
12. To verify the status of this load balancer, please continue in the below section: Checking UID2 Operator Status

Checking UID2 Operator Status

To check the UID2 Operator status of your Load Balancer, complete the following steps:

1. Identify the DNS name of your load balancer by going to EC2 > Load balancers and looking at the DNS name column of your load balancer.
2. In your browser, go to https://{dns-name-of-your-load-balancer}/ops/healthcheck. A response of OK indicates good operator 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: Operator 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 the UID2 Operator

For each operator version update, each private operator receives an email notification with an upgrade window. After the upgrade window, the old version is deactivated and is no longer supported.

Here's what you need to know about upgrading:

• Information on the availability of new versions is provided on the Unified ID 2.0 Operator on AWS Marketplace page.
• To upgrade your UID2 Operators, create a new CloudFormation stack. For details, see Deployment.

tip

For a smooth transition, create the new stack first. After the new stack is bootstrapped and ready to serve, delete the old stack. If you are using a load balancer, first get the new instances up and running and then convert the DNS name from the previous one to the new one.

Managing the Logs

Use the following sections to help you make the best use of your logs:

• Where to Read Logs
• Default Log Settings
• Changing the Log Rotation Schedule
• Additional Commands for Logging

Where to Read Logs

To access the logs, ssh into the EC2 instance. The logs are located at /var/logs/ and are in the format operator.log-<timestamp rotated>.

Default Log Settings

The UID2 system uses syslog-ng for log generation and employs logrotate with cron jobs to manage log rotation and prevent excessive log size. The following sections provide information on the default settings and the reasons behind them, and give guidance for customizing the log rotation configuration to meet your specific requirements:

• Log Rotation Configuration
• Log Rotation Default Settings
• cronjob Configuration

Log Rotation Configuration

When the operator instance has been deployed, the default log rotation settings are applied, as follows:

• Logs are rotated daily and 30 log entries are kept, so the log history is equivalent to 30 days of data if the log entries are not abnormally large.
• If log entries are very large, and the log size reaches 30 MB within a 24-hour period, the log is rotated at that point.

Log Rotation Default Settings

The following are the default logrotate settings, defined in /etc/logrotate.d/operator-logrotate.conf:

/var/log/operator.log*
{
        rotate 30
        daily
        maxsize 30M
        dateext dateformat -%Y-%m-%d-%s
        notifempty
        sharedscripts
        postrotate
                /usr/sbin/syslog-ng-ctl reload
        endscript
}

For a detailed explanation of this config, see logrotate(8) - Linux man page, or run logrotate man in the Linux environment.

cronjob Configuration

The logrotate generates the following script in /etc/cron.daily by default:

#!/bin/sh
   
/usr/sbin/logrotate -s /var/lib/logrotate/logrotate.status /etc/logrotate.conf
EXITVALUE=$?
if [ $EXITVALUE != 0 ]; then
    /usr/bin/logger -t logrotate "ALERT exited abnormally with [$EXITVALUE]"
fi
exit 0

The following script in /etc/cron.d ensures that the logrotate check is run every minute:

# Run the minutely jobs
SHELL=/bin/bash
PATH=/sbin:/bin:/usr/sbin:/usr/bin
MAILTO=root
* * * * * root /usr/sbin/logrotate -s /var/lib/logrotate/logrotate.status /etc/logrotate.conf

These are the default settings for the following reasons:

• The script ensure that the maxsize condition is checked frequently.
• The command refers to /var/lib/logrotate/logrotate.status to check the log status and see if it has reached the rotation condition, so that it won't make extra rotations when logrotate is run every minute.

Changing the Log Rotation Schedule

To change the log rotation schedule, update the etc/logrotate.d/operator-logrotate.conf file.

Follow the instructions in the logrotate documentation: see logrotate(8) - Linux man page.

note

The service does NOT need to be restarted to pick up the change.

Additional Commands for Logging

The following table includes some additional commands that might help you manage logs.

Action	Command
Provides a detailed explanation of what will be rotated.	sudo logrotate -f /etc/logrotate.conf --debug
Runs one iteration of logrotate manually, without changing the scheduled interval.	sudo logrotate -f /etc/logrotate.conf --force
Reloads syslog-ng.	sudo /usr/sbin/syslog-ng-ctl reload

UID2 Operator Error Codes

The following table lists errors that might occur during a Private Operator's startup sequence.

note

Error codes for Private Operator startup issues are applicable only to release v5.49.7 and later.

Error Code	Issue	Steps to Resolve
E01	InstanceProfileMissingError	Attach an IAM instance profile to the EC2 instance with the required permissions. The UID2 Operator needs these permissions to access configurations from AWS Secrets Manager.
E02	OperatorKeyNotFoundError	Make sure that the secret referenced by the Private Operator exists in AWS Secrets Manager in the same region as the operator, and that the IAM instance profile has permission to access the secret. If needed, you can check the logs for the specific secret name and region.
E03	ConfigurationMissingError	Required attributes are missing in the configuration. Refer to the logs for details and update the missing attributes in Secrets Manager.
E04	ConfigurationValueError	A configuration value is invalid. Verify that the configuration values in the AWS Secrets Manager align with the required format and environment. Note: debug_mode = true is allowed only in the integ environment. Check the logs for more details.
E05	OperatorKeyValidationError	Ensure the operator key is correct for the environment and matches the one provided to you.
E06	UID2ServicesUnreachableError	Allow UID2 core and opt-out service IP addresses in the egress firewall. For IP addresses and DNS details, refer to the logs.

Technical Support

If you have trouble subscribing to the product, or deploying, contact us.