From d89db618673e46eb6a2f8875736af195da826c22 Mon Sep 17 00:00:00 2001 From: Rohith Jayawardene Date: Wed, 9 Oct 2024 12:49:36 +0100 Subject: [PATCH] docs: updating the readme --- README.md | 106 ------------------------------------------------------ 1 file changed, 106 deletions(-) diff --git a/README.md b/README.md index e3be702..be1bf91 100644 --- a/README.md +++ b/README.md @@ -1,109 +1,3 @@ - - - -Appvia Banner

Terraform Registry Latest Release Slack Community Contributors - - - - - -# Description - -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 AWS SSO is configured (`https://.awsapps.com/start#/` => ``) -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 - -```hcl -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: - -```hcl - 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](https://admin.google.com/u/1/ac/apps/saml/45189681917) -- Add the new group to [terraform-aws-identity](https://github.com/CUSTOMER_ORG/terraform-aws-vpn/tree/main) 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](https://aws.amazon.com/blogs/networking-and-content-delivery/using-aws-sso-with-aws-client-vpn-for-authentication-and-authorization/) -- AWS Docs: [SAML-based IDP configuration](https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/federated-authentication.html) - ## Requirements