Skip to main content

EUID Private Operator for AWS Integration Guide

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

EUID Private Operator for AWS Product

NOTE: European Unified ID 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 the European Unified ID Operator on AWS Marketplace product, you gain access to the following:

  • Amazon Machine Image (AMI) with the EUID Operator service installed and ready to bootstrap:
    The AMI contains an Amazon Linux 2 operating system with the EUID 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 EUID Operator server inside an enclave.
  • CloudFormation template:
    The template deploys the EUID Operator AMI.

Prerequisites

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

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

Minimal IAM Role Privileges

IMPORTANT: 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.

NameTypeDescription
KMSKeyAWS::KMS::KeyThe key for secret encryption (for configuration strings).
SSMKeyAliasAWS::KMS::AliasAn alias that provides an easy way to access the KMS key.
TokenSecretAWS::SecretsManager::SecretAn encrypted configuration that includes the operator key.
WorkerRoleAWS::IAM::RoleThe IAM role that your EUID Operators run as. Roles provide access to configuration keys.
WorkerInstanceProfileAWS::IAM::InstanceProfileThe instance profile with Worker Role to attach to Operator EC2 instances.
SecurityGroupAWS::EC2::SecurityGroupA security group policy that provides rules for operator instances. See also Security Group Policy.
LaunchTemplateAWS::EC2::LaunchTemplateA launch template with all configurations in place. You can spawn new EUID Operator instances from it.
AutoScalingGroupAWS::AutoScaling::AutoScalingGroupAn 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 can either set up a new VPC and subnets or use existing ones.
  • Root volume size (8G Minimum)
  • SSH key: This is the SSH key that you use to access the EUID 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 NumberDirectionProtocolDescription
80InboundHTTPServes all EUID 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 EUID Operator Status.
9080InboundHTTPServes Prometheus metrics (/metrics).
443OutboundHTTPSCalls the EUID Core Service; updates opt-out data and key store.

VPC Chart

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

EUID Operator VPC Chart

Deployment

To deploy European Unified ID Operator on AWS Marketplace, complete the following steps:

  1. Subscribe to European Unified ID Operator on AWS Marketplace. It might take several minutes before AWS completes your subscription.
  2. Click Configuration.
  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).

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.

Application Configuration

Lower part of the page:

Infrastructure Configuration

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

ParameterDescription
Stack nameAny name of your choice.
OPERATOR_KEYThe Operator Key that you received from the EUID Admin team.
EUID EnvironmentSelect prod for production environment or integ for the integration test environment.
Instance Typem5.2xlarge is recommended.
Instance root volume size15 GB or more is recommended.
Key Name for SSHYour EC2 key pair for SSH access to the deployed EC2 instances.
Trusted Network CIDRThe CIDR (Classless Inter-Domain Routing) value determines the IP address range that can access your operator service.
To limit access to the EUID 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.

Stack Configuration Options

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

Configure Stack Options

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

ParameterDescription
Tags(Optional) Tag your stack.
PermissionsIf 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 optionsChoose what happens when deployment fails. The Roll back all stack resources option is recommended.
Advanced optionsThese 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 EUID Load balancer name. Depending on whether or not you need to access EUID APIs from public internet, choose the Internet-facing or Internal scheme.
  5. Select the VPC for your targets and at least two subnets used in your CloudFormation stack.
  6. Under Security groups, click Create new security group and do the following:
    1. Enter EUIDSGALB 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 EUIDSGALB 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 EUIDALBTG 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 EUID 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 EUIDALBTG 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 EUID Operator Status.

Checking EUID Operator Status

To check the EUID 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: 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 the EUID 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:

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.

Technical Support

If you have trouble subscribing or deploying the product, contact us at aws-mktpl-uid@thetradedesk.com.