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-infraAdministratorAccess 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¶
- Open the self-service portal for the environment and sign in with your Microsoft account:
- 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. - 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.
- 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:
- Download the new Federation Metadata XML from the Entra app (Single sign-on → SAML Certificates).
- Replace the file in both environments in an infra PR; the apply updates both SAML providers.
- 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.