Terraform AWS VPN

This repository creates an AWS Client VPN Endpoint for the AWS Organization, which is connected to the AWS Transit Gateway.

Prerequisites

AWS SSO must be configured appropriately for the AWS Organization, for the Client VPN to be able to authenticate users.

Steps:

1. Login to the AWS Account where <CUSTOMER_NAME> AWS SSO is configured (https://<CUSTOMER_SSO_DOMAIN>.awsapps.com/start#/ => <CUSTOMER_MANAGEMENT_ACCOUNT>)
2. Navigate to IAM Identity Center
3. On the left-hand column, navigate to Applications and then Add application
4. Tick Add a custom SAML 2.0 application and press Next
5. Provide a friendly display name for the application, e.g. AWS Client VPN
6. Application start URL can later be changed to the VPN self-service portal URL, once provisioned
7. At the bottom under Application metadata, specify:
   1. Application ACS URL: http://127.0.0.1:35001
   2. Application SAML audience: urn:amazon:webservices:clientvpn
8. Press Submit
9. Press Assign Users and then assign any Users or Groups who should have access to the VPN (or select all Groups for now)
10. At the top right, press Actions and then Edit attribute mappings
    1. For Subject, set the string value to ${user:email} and format as emailAddress
    2. Add memberOf, set the string value to ${user:groups} and format as unspecified
11. Press Save changes
12. Go back to Actions and then Edit configuration
13. Press Download to retrieve the IAM Identity Center SAML metadata file and store it in this repository in the metadata directory
14. Repeat all the steps for the AWS Client VPN Self Service Portal, with one change:
    1. For the Application ACS URL, provide the value https://self-service.clientvpn.amazonaws.com/api/auth/sso/saml

Once the above steps are complete, the Terraform can be applied via the GitHub CI Pipeline.

Updating Docs

The terraform-docs utility is used to generate this README. Follow the below steps to update:

1. Make changes to the .terraform-docs.yml file
2. Fetch the terraform-docs binary (https://terraform-docs.io/user-guide/installation/)
3. Run terraform-docs markdown table --output-file ${PWD}/README.md --output-mode inject .

Adding new authorization rule

By default, all VPN access is denied, regardless of provided routing. You are required to explicitly allow access to given CIDR ranges to different SSO groups through a set of authorization rules. In order to add a new rule when the SSO Group exists already, you need to do the following:

1. Check if the data resource was created to extract the group ID in your terraform values

variable "sso_groups" {
  description = "SSO groups to create VPN rules for"
  type        = list(string)
  default     = []
}

2. Add a new authorization rule explicitly in main.tf specifying what CIDR range is allowed for each group. Only one CIDR is allowed per rule:

  authorization_rules = [
    {
      access_group_id     = data.aws_identitystore_group.groups["NAME OF THE GROUP"].group_id
      description         = "Allow VPN access to all internal services for Cloud Admin users"
      name                = "allow-all-cloud-admin"
      target_network_cidr = "10.0.0.0/8" # All internal access
    },
  ]

Troubleshooting

Can't access required CIDRs over VPN?

If you have added an authorization rule, but can't access the network over VPN, make sure that:

• you have disconnected/reconnected to your VPN client (you may need to wait a couple of minutes or disconnect/reconnect a couple of times)
• you are part of the correct group
• the group ID is correct (You can find it in the Identity Center in AWS Audit Account and comapre to added rules for Client VPN in Remote Access AWS Account)
• the group has been added to both VPN applications in Identity Center in AWS Audit Account
• the resource you are trying to access has correct security group rules.

Want to add a new SSO group and permissions to access VPN?

When adding a new group to SSO, there are following steps to complete:

• Add a new group to the AWS SSO Application within Google Admin
• Add the new group to terraform-aws-identity repository.
• Add a new group to VPN applications in Identity Center in AWS Audit Account
• Specify the allowed CIDR ranges via new authorization rule for the new group in this repository.

References

• AWS Blog: AWS SSO and AWS Client VPN setup
• AWS Docs: SAML-based IDP configuration

Requirements

Name	Version
terraform	>= 1.0
aws	~> 5.0

Providers

Name	Version
aws	~> 5.0

Modules

Name	Source	Version
client_vpn	cloudposse/ec2-client-vpn/aws	1.0.0

Resources

Name	Type
aws_iam_saml_provider.vpn	resource
aws_iam_saml_provider.vpn_portal	resource

Inputs

Name	Description	Type	Default	Required
authorization_rules	Authorization rules for the VPN	list(object({ access_group_id = string description = string name = string target_network_cidr = string }))	n/a	yes
name	Name of the VPN	string	n/a	yes
saml_provider_document	Document for the SAML provider	string	n/a	yes
saml_provider_portal_document	Document for the SAML provider portal	string	n/a	yes
tags	Tags to apply to all resources	map(string)	n/a	yes
vpc_id	ID of the VPC to use for the VPN	string	n/a	yes
vpn_log_stream_name	Name of the CloudWatch log stream for the VPN	string	n/a	yes
vpn_org_name	Name of the organization for the VPN	string	n/a	yes
client_cidr	CIDR block for the VPN clients	string	"172.16.0.0/16"	no
enable_vpn	Whether to enable and deploy the VPN (useful do to dependency of this module)	bool	false	no
public_subnet_ids	IDs of the public subnets to use for the VPN	list(string)	[]	no
saml_provider_name	Name of the SAML provider	string	"Client_VPN"	no
saml_provider_portal_name	Name of the SAML provider portal	string	"Client_VPN_Portal"	no
vpn_log_retention	Number of days to retain VPN logs	number	7	no

Outputs

Name	Description
client_configuration	VPN Client Configuration data.
vpn_endpoint_arn	The ARN of the Client VPN Endpoint Connection.
vpn_endpoint_dns_name	The DNS Name of the Client VPN Endpoint Connection.
vpn_endpoint_id	The ID of the Client VPN Endpoint Connection.