Skip to content

Latest commit

 

History

History
157 lines (111 loc) · 8.06 KB

getting-started.md

File metadata and controls

157 lines (111 loc) · 8.06 KB
Raw

Getting Started with CfnVpn

Installation

Install cfn-vpn gem

gem install cfn-vpn

Setup Easy-RSA

Option 1 - Docker

Install docker

Docker is required to generate the certificates required for the client vpn. The gem uses openvpn/easy-rsa project in base2/aws-client-vpn docker image. repo

Option 2 - local

If you would rather setup easy-rsa than install docker, you can use the --easyrsa-local flag when running the commands to use a local copy of easy-rsa, the binary just needs to be available in the $PATH. Install from openvpn/easy-rsa

Setup Your AWS Credentials

Setup your AWS credentials by either setting a profile or exporting them as environment variables.

export AWS_ACCESS_KEY_ID="XXXXXXXXXXXXXXXXXXXXX"
export AWS_SECRET_ACCESS_KEY="XXXXXXXXXXXXXXXXXXXXX"
export AWS_SESSION_TOKEN="XXXXXXXXXXXXXXXXXXXXX"

Optionally export the AWS region if not providing --region flag

export AWS_REGION="us-east-1"

Initializing CfnVpn

to launch a new CfnVpn stack run the init command along with the options.

Certificate Authenticated VPN

This is the default option when launching a ClientVPN using certificated based authentication. https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/client-authentication.html#mutual

The following command and required options will launch a new certificate based Client-VPN

cfn-vpn init [name] --bucket [s3-bucket] --server-cn [server certificate name] --subnet-ids [list of subnets to associate with the vpn]

Federated SAML Authenticated VPN

This option is for when you want to manage users through an external directory provider like AWS SSO, OKTA or AzureAD. https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/client-authentication.html#federated-authentication

Prerequisites: Client-VPN requires a IAM SAML identity provider ARN, see the AWS docs to create one.

The following command and required option will launch a new federated based Client-VPN

cfn-vpn init [name] --server-cn [server certificate name] \
  --subnet-ids [list of subnets to associate with the vpn] \
  --saml-arn [identity provider arn]

The default authorization rule for the associated subnets allows all. You can optionally change this by using the --default-groups flag to set groups on the default authorization rule.

! Group id's must be used if creating authorization rules. 
! Each SAML provider will have different group id's and means of retrieving them.
cfn-vpn init [name] --server-cn [server certificate name] \
  --subnet-ids [list of subnet to associate with the vpn] \
  --saml-arn [identity provider arn]  \
  --default-groups [list of group ids]

AWS SSO

If using AWS SSO as your SAML provider check this guide on how to set up SAML using AWS SSO https://codeburst.io/the-aws-client-vpn-federated-authentication-missing-example-655e0a1ff7f4

If you want to leverage the Self Service Portal you need to add the specify the --saml-self-service-arn [self service identity provider arn] You can follow the example here https://aws.amazon.com/blogs/security/authenticate-aws-client-vpn-users-with-aws-single-sign-on/ on how to setup the self sign-on sso application

cfn-vpn init [name] --server-cn [server certificate name] \
  --subnet-ids [list of subnet to associate with the vpn] \
  --saml-arn [identity provider arn]  \
  --saml-self-service-arn [self service identity provider arn] \
  --default-groups [list of group ids]

AWS Directory Services Authenticated VPN

This option integrates Microsoft Active Directory or Simple AD through AWS Directory Service with AWS Client VPN.

The following command and required option will launch a new directory service based Client-VPN

cfn-vpn init simple-ad --server-cn [server certificate name] \
  --subnet-ids [list of subnets to associate with the vpn] \
  --directory-id [aws directory service id]

The default authorization rule for the associated subnets allows all. You can optionally change this by using the --default-groups flag to set groups on the default authorization rule. The group Id is the Active Directory Group ID or SID.

cfn-vpn init simple-ad --server-cn [server certificate name] \
  --subnet-ids [list of subnets to associate with the vpn] \
  --directory-id [aws directory service id] \
  --default-groups [list of group ids]

See this guide for further help on setting up https://shogokobayashi.com/2019/05/18/aws-client-vpn-with-simplead/

Subnet Associations and Authorization

AWS ClientVPN requires one or more subnets to be associated with the vpn. These subnets setup the default routes and by default cfn-vpn creates a allow all auth for the default routes. When using a federated ClientVPN you can modify the default auth to only allow specific groups by setting the groups in the --default-groups flag. This can also be modified later using the modify command.

Additional Initializing Options

Options:
  r, [--region=REGION]                                     # AWS Region
                                                           # Default: ap-southeast-2
      [--verbose], [--no-verbose]                          # set log level to debug
      --server-cn=SERVER_CN                                # server certificate common name
      [--client-cn=CLIENT_CN]                              # client certificate common name
      [--easyrsa-local], [--no-easyrsa-local]              # run the easyrsa executable from your local rather than from docker
      [--bucket=BUCKET]                                    # s3 bucket, if not set one will be generated for you
      --subnet-ids=one two three                           # subnet id to associate your vpn with
      [--default-groups=one two three]                     # groups to allow through the subnet associations when using federated auth
      [--cidr=CIDR]                                        # cidr from which to assign client IP addresses
                                                           # Default: 10.250.0.0/16
      [--dns-servers=one two three]                        # DNS Servers to push to clients.
      [--split-tunnel], [--no-split-tunnel]                # only push routes to the client on the vpn endpoint
                                                           # Default: true
      [--internet-route=INTERNET_ROUTE]                    # [subnet-id] create a default route to the internet through a subnet
      [--protocol=PROTOCOL]                                # set the protocol for the vpn connections
                                                           # Default: udp
                                                           # Possible values: udp, tcp
      [--start=START]                                      # cloudwatch event cron schedule in UTC to associate subnets to the client vpn
      [--stop=STOP]                                        # cloudwatch event cron schedule in UTC to disassociate subnets to the client vpn
      [--saml-arn=SAML_ARN]                                # IAM SAML identity provider arn if using SAML federated authentication
      [--saml-self-service-arn=SAML_SELF_SERVICE_ARN]      # IAM SAML identity provider arn for the self service portal
      [--directory-id=DIRECTORY_ID]                        # AWS Directory Service directory id if using Active Directory authentication
      [--slack-webhook-url=SLACK_WEBHOOK_URL]              # slack webhook url to send notifications from the scheduler and route populator
      [--auto-limit-increase], [--no-auto-limit-increase]  # automatically request a AWS service quota increase if limits are hit for route entry and authorization rule limits
                                                           # Default: true