Skip to content

VPN Access

How to connect to the AWS Client VPN in stage and prod, what each group can reach, and how access is granted, revoked and maintained.

Both environments use one Client VPN endpoint each, with sign-in through Entra ID (SAML). There are no client certificates or shared keys: access follows Entra group membership, so removing someone from a group removes their access.

Required access

  • Entra group: membership of one of the VPN groups below. Without one, sign-in either fails or gives a connection that reaches nothing.
  • AWS permissions: none to connect. Granting access, reading connection logs and ending sessions need the sec-infra AdministratorAccess permission set in the account concerned.
  • Secrets / SSM: none.
  • VPN / tunnel: this page is the VPN. Ports on databases and instances are still limited by their security groups.

Who can reach what

Entra group Stage Prod
sec-infra Whole VPC Whole VPC
sec-devop-{env} Whole VPC Private subnets (Postgres, ClickHouse, ECS, internal ALB), db1, DNS
sec-data-{env} Private subnets (DBs, ClickHouse), internal ALB Private subnets (Postgres, ClickHouse, ECS, internal ALB), db1, DNS
sec-employee-{env} No access No access

Employees are deliberately not given VPN access. sec-employee-* can stay assigned to the Entra app so the groups can be given AWS access later; until then their members sign in to a connection that reaches nothing.

The rules live in Terraform: local.vpn_authorization_rules in environments/{stage,prod}/eu-central-1/locals.tf.

Connecting

  1. Open the self-service portal for the environment and sign in with your Microsoft account:
  2. Download the AWS VPN Client from the portal if you don't have it, and the client configuration (.ovpn). Use the AWS client: OpenVPN and Tunnelblick can't do the Entra sign-in.
  3. In the AWS VPN Client, choose File → Manage Profiles → Add Profile and add the downloaded file. Name the profiles so stage and prod are easy to tell apart.
  4. Connect. Your browser opens the Microsoft sign-in; after it, the page says "Authentication successful" and the client connects.

Only one profile can be connected at a time. Both VPCs use 172.31.0.0/16, so switch environment by disconnecting first. Sessions end after 8 hours, and you sign in again.

Once connected you can reach (depending on your group):

  • Internal ALB services: *.internal.cookiehub.net, *.internal.stage.cookiehub.net
  • RDS and ClickHouse
  • EC2 instances in private subnets

DNS uses the VPC resolver, so the private Route53 zones resolve over the VPN. Only VPC traffic goes through the tunnel (split tunnel).

Troubleshooting

Symptom Cause and fix
Browser says "Authentication successful", then the client says "The provided credentials are incorrect" The Entra app is not signing the whole SAML response. Its signing option must be Sign SAML response and assertion (see Entra app settings).
Microsoft sign-in page shows AADSTS50105 Your account (or a group you are in) is not assigned to the Entra ClientVPN app.
Microsoft sign-in page shows AADSTS50011 The reply URL the client used is not on the Entra app. Both URLs under Entra app settings must be there.
Connected, but a host doesn't answer Check your group can reach that subnet (table above), then the target's security group: it must allow the VPN security group ({env}-euc1-core-vpn-sg) on that port.
Sign-in never finishes, the client keeps waiting The client listens on http://127.0.0.1:35001 for the result. Another program on that port, or a browser policy blocking it, stops the hand-over.
Old certificate profile no longer connects The certificate endpoints were removed in October 2026 (IS-39). Delete the profile and add the SSO one.

Administration

Granting and revoking access

Access is Entra group membership; nothing changes in AWS.

  • Grant: add the person to the right group. If the group is new to the VPN, also assign it to the Entra AWS ClientVPN enterprise app (Users and groups), otherwise the group is not sent at sign-in.
  • Revoke: remove the person from the group, or disable the account. This takes effect at their next sign-in. A session already open lasts up to 8 hours; to end it now:
aws ec2 terminate-client-vpn-connections \
  --client-vpn-endpoint-id <endpoint-id> \
  --username <user>@cookiehub.com \
  --region eu-central-1

A new access tier (another group or destination) is a Terraform change to local.vpn_authorization_rules. Client VPN uses the most specific matching rule for a destination, so every group allowed into a specific subnet needs its own rule on that subnet; the locals build this matrix.

Who connected

Connection logs go to CloudWatch, log group /aws/vpn/{env}-euc1-core-saml, stream connections. Each attempt records the user name, the device's public IP, the VPN address given, the bytes moved and any failure reason.

The logs arrive in batches about 15–20 minutes late. For what is happening right now, use:

aws ec2 describe-client-vpn-connections --client-vpn-endpoint-id <endpoint-id> --region eu-central-1

Each sign-in shows two entries: a first attempt with user N/A that hands over to the browser, then the real connection. That is normal.

Entra app settings

Stage and prod share one Entra enterprise app, AWS ClientVPN: every Client VPN endpoint uses the same identifier and Entra allows an identifier on only one app. The endpoints depend on these settings, which are not in Terraform:

Setting Value
Identifier (Entity ID) urn:amazon:webservices:clientvpn
Reply URLs http://127.0.0.1:35001 (VPN client) and https://self-service.clientvpn.amazonaws.com/api/auth/sso/saml
Signing option Sign SAML response and assertion
Group claim Named memberOf (no namespace), source Group ID
Token encryption Off
Users and groups sec-infra, sec-devop-*, sec-data-* (and optionally sec-employee-*)

The group IDs in Terraform (var.entra_vpn_group_ids) are Entra object IDs, not Identity Center group IDs. List them with aws identitystore list-groups --identity-store-id <store> --query 'Groups[].[DisplayName,ExternalIds[0].Id]'.

Certificate renewals

Two certificates expire and must be renewed by hand.

Entra SAML signing certificate

Expires 2029-08-20. AWS holds a copy in the IAM SAML provider {env}-euc1-core-clientvpn-entra, made from environments/{stage,prod}/eu-central-1/files/entra-clientvpn-saml-metadata.xml (the same file in both). When Entra rotates the certificate:

  1. Download the new Federation Metadata XML from the Entra app (Single sign-on → SAML Certificates).
  2. Replace the file in both environments in an infra PR; the apply updates both SAML providers.
  3. Make the new certificate active in Entra after the apply, then test a sign-in in each environment.

VPN server certificates

The endpoints present a server certificate issued by the CookieHub EasyRSA CA and imported into ACM:

Environment Name Expires
Stage vpn.euc1.stage.cookiehub.net 2028-06-20
Prod vpn.euc1.cookiehub.net 2028-05-23

To renew, issue a new certificate from the CA (~/.my_ca) and re-import it into the same ACM ARN, so the endpoint and var.vpn_server_cert_arn stay unchanged:

cd ~/.my_ca
./easyrsa build-server-full vpn.euc1.cookiehub.net nopass   # vpn.euc1.stage.cookiehub.net for stage

openssl x509 -in pki/issued/vpn.euc1.cookiehub.net.crt -out server-clean.crt
openssl rsa -in pki/private/vpn.euc1.cookiehub.net.key -out server-clean.key
openssl x509 -in pki/ca.crt -out ca-clean.crt

aws acm import-certificate \
  --certificate-arn <existing server cert ARN> \
  --certificate fileb://server-clean.crt \
  --private-key fileb://server-clean.key \
  --certificate-chain fileb://ca-clean.crt \
  --region eu-central-1

The AWS VPN Client checks the server certificate against the CA in the profile, so test a connection after renewing. If the CA itself is replaced, everyone downloads a new profile from the self-service portal.