Authenticate AWS Client VPN users with AWS IAM Identity Center

September 12, 2022: This blog post has been updated to reflect the new name of AWS Single Sign-On (SSO) – AWS IAM Identity Center. Read more about the name change here.

AWS Client VPN is a managed client-based VPN service that enables users to use an OpenVPN-based client to securely access their resources in Amazon Web Services (AWS) and in their on-premises network from any location. In this blog post, we show you how you can integrate Client VPN with your existing AWS IAM Identity Center via a custom SAML 2.0 application to authenticate and authorize your Client VPN connections and traffic.

Maintaining a separate set of credentials to authenticate users and authorize access for each resource is not only tedious, it’s not scalable. A common way to solve this challenge is to use a central identity store such as AWS IAM Identity Center, which functions as your identity provider (IdP). You can then use Security Assertion Markup Language 2.0 (SAML 2.0) to integrate AWS IAM Identity Center with each of your resources or applications, also known as service providers (SPs). The IdP authenticates users and passes their identity and security information to the SP via SAML. With SAML, you can enable a single sign-on experience for your users across many SAML-enabled applications and services. Users authenticate with the IdP once using a single set of credentials, and then have access to multiple applications and services without additional sign-ins.

Client VPN supports identity federation with SAML 2.0 for Client VPN endpoints. Deploying custom SAML applications can present some challenges, specifically around the mapping of attributes between what the SP expects to receive and what the IdP can provide. We’ve taken the guesswork out of the process and show you the exact mappings needed for the Client VPN to AWS IAM Identity Center integration. The integration lets you use AWS IAM Identity Center groups to not only grant access to create a Client VPN connection, but also to allow access to specific network ranges based upon group membership. We walk you through setting up all of the components required to implement the authentication workflow described in Figure 1. This consists of creating the custom SAML applications and tying them into AWS Identity and Access Management (IAM), creating and configuring the Client VPN endpoint, creating a Client VPN connection with an AWS IAM Identity Center user, and testing your connectivity.

Figure 1: Authentication workflow

The steps illustrated in Figure 1 are:

The user opens the AWS-provided VPN client on their device and initiates a connection to the Client VPN endpoint.
The Client VPN endpoint sends an IdP URL and authentication request back to the client, based on the information that was provided in the IAM SAML provider.
The AWS provided VPN client opens a new browser window on the user’s device. The browser makes a request to the IdP and displays a sign-in page. This is the same sign-in experience as the AWS IAM Identity Center user portal, as the IdP URL points to a custom SAML application created within AWS IAM Identity Center.
The user enters their credentials on the sign-in page, and the IdP sends a signed SAML assertion back to the client in the form of an HTTP POST to the AWS provided VPN client.
The SAML assertion is passed from the AWS provided VPN client to the Client VPN endpoint.
The endpoint validates the assertion and either allows or denies access to the user.

Prerequisites

Here are the requirements to complete the VPN and IAM Identity Center setup:

AWS IAM Identity Center is configured to use the internal AWS IAM Identity Center identity store. Refer to the AWS IAM Identity Center Getting Started guide for help configuring AWS IAM Identity Center. AWS IAM Identity Center can exist in a different AWS account than the account where you deploy Client VPN endpoints. The steps outlined in this blog post are specific to the internal AWS IAM Identity Center identity store, however they could be adapted to support other identity stores that support SAML 2.0.
Two AWS IAM Identity Center users and two AWS IAM Identity Center groups for testing. Each user should be a member of only one of the IAM Identity Center groups. The purpose of this configuration is to demonstrate how access can be allowed or denied based upon group membership.
An Amazon Virtual Private Cloud (Amazon VPC) with an Amazon Elastic Compute Cloud (Amazon EC2) instance for connectivity testing.
An x.509 certificate imported into AWS Certificate Manager (ACM). You can generate a self-signed certificate for this walkthrough, however you should review the prerequisites for importing certificates into ACM. This certificate will be used for encrypted communication between the client VPN software and the client VPN endpoint.
Administrative access to your AWS environment, or at least sufficient access to create AWS IAM Identity Center applications, ACM certificates, EC2 Instances, and Client VPN endpoints.
A client device running Windows or macOS with the latest version of Client VPN software installed. You can download it from the AWS Client VPN download.

Solution walkthrough

For this solution, you’ll complete the following steps:

Establish trust with your IdP
Create and configure Client VPN SAML applications in AWS IAM Identity Center.
Integrate the Client VPN SAML applications with IAM.
Create and configure the Client VPN endpoint.
Test the solution.
Cleanup the test environment.

Establish trust with your IdP

In this walkthrough, Client VPN is the SAML SP and AWS IAM Identity Center is the SAML IdP. One of the key steps to deploying this solution is to establish trust between the SP and IdP. This one-time configuration is done by creating custom SAML applications within AWS IAM Identity Center and exporting application-specific metadata information from the applications. This metadata is then uploaded—in the form of IAM IdPs—into your AWS account where the Client VPN endpoint is created. IAM IdPs let you manage your user identities in a centralized identity store, such as AWS IAM Identity Center, and grant those user identities permissions to AWS resources within your account. For organizations with multiple AWS accounts, the use of IAM IdPs resolves the management, scalability, and security issues associated with creating IAM users directly within each account.

Create and configure the Client VPN SAML applications in AWS IAM Identity Center

Create two custom SAML 2.0 applications in AWS IAM Identity Center. One will be the IdP for the Client VPN software, the other will be a self-service portal that allows users to download their Client VPN software and client configuration file.

To create the VPN client SAML application:

In the AWS IAM Identity Center console, select Applications from the left pane and select Add a new application.
Select Add a custom SAML 2.0 application to use as the IdP for the Client VPN software.

Figure 2: Add a SAML application
In the Details section, set Display name to VPN Client.
In the Application Metadata section, select If you don’t have a metadata file, you can manually type your metadata values and enter the following values:
- Application ACS URL: http://127.0.0.1:35001
- Application SAML audience: urn:amazon:webservices:clientvpn
Accept the default values for all other fields.
Choose Save Changes.

Select the Attribute mappings tab and configure the mappings as shown in the table and Figure 3 below.

Note: For production environments, you should grant access to these applications via an AWS IAM Identity Center group instead of individual users as shown in this walkthrough.

User attribute in the application	Maps to this string value or user attribute in AWS IAM Identity Center	Format
Subject	${user:email}	emailAddress
Name	${user:email}	unspecified
FirstName	${user:givenName}	unspecified
LastName	${user:familyName}	unspecified
memberOf	${user:groups}	unspecified

Figure 3: VPN client attribute mappings

On the Assign users tab, add your two test user accounts.
On the application configuration page, choose the download link for AWS IAM Identity Center SAML metadata. Save the file to use in a later step.

To create the VPN client self-service SAML application

In the AWS IAM Identity Center console, select Applications from the left pane and select Add a new application.
Select Add a custom SAML 2.0 application to use as the application that will serve as the IdP for the Client VPN software.

Figure 4: Add a SAML application
In the Details section, set Display name to VPN Client Self Service.
In the Application Metadata section, select If you don’t have a metadata file, you can manually type your metadata values and enter the following values:
- Application ACS URL: https://self-service.clientvpn.amazonaws.com/api/auth/sso/saml
- Application SAML audience: urn:amazon:webservices:clientvpn
Accept the default values for all other fields.
Choose Save Changes.

Choose the Attribute mappings tab and configure the mappings as shown in the following table and in Figure 5.

Note: For production environments you should grant access to these applications via an AWS IAM Identity Center group instead of individual users as shown in this walkthrough. For the purposes of this walkthrough, you grant individual users access to the SAML applications but grant network access via group membership. This is done to allow easier demonstration of the ability to grant or deny network specific access via groups when testing the solution.

User attribute in the application	Maps to this string value or user attribute in AWS IAM Identity Center	Format
Subject	${user:email}	emailAddress
Name	${user:email}	unspecified
FirstName	${user:givenName}	unspecified
LastName	${user:familyName}	unspecified
memberOf	${user:groups}	unspecified

Figure 5: VPN Client self-service attribute mappings

On the Assign users tab, add your two test user accounts.
On the application’s Configuration page, choose the download link for AWS IAM Identity Center SAML metadata. Save the file to use in a later step.

Integrate the Client VPN SAML applications with IAM

Client VPN requires a unique IdP definition in IAM. You must set up the IdP in the same AWS account where the Client VPN endpoint will be created.

To create the IAM IdP:

In the IAM console, select Identity providers and Add provider. Name the provider aws-client-vpn and upload the metadata document that you downloaded from the VPN Client SAML application.
Add a second provider, name the provider aws-client-vpn-self-service and upload the metadata document that you downloaded from the VPN Client Self Service SAML application.

Create and configure the Client VPN endpoint

All Client VPN sessions end at the Client VPN endpoint. You configure the Client VPN endpoint to manage and control all Client VPN sessions. In the following steps, you create a Client VPN endpoint and configure it to use the newly added IAM IdPs. You then associate the endpoint with a VPC and configure authorization rules to allow traffic into the VPC, then set up the Client VPN self-service portal.

To create the Client VPN endpoint

Open the AWS VPC console and select Client VPN Endpoints and then select Create Client VPN endpoint.
Enter a Name Tag and Description for the endpoint.
Enter 172.16.0.0/22 for the Client IPv4 CIDR. This is the IP range that will be allocated to your VPN clients. It shouldn’t overlap the CIDR of your AWS VPCs or of the network that your client device is connected to and must be at least a /22 bitmask. You can adjust this value as needed for your specific network requirements. The Client IPv4 CIDR value can only be set during endpoint creation.

Note: For production environments you should review the Client VPN documentation for scaling considerations before you create the endpoint.
In the Server certificate ARN drop down menu, select the ACM certificate that you created for your VPN clients.
Set the Authentication Options to Use user-based authentication with Federated authentication. Select the aws-client-vpn IAM IdP for the SAML provider ARN, and select the aws-client-vpn-self-service IAM IdP as the Self-service SAML provider ARN.

Figure 6: Authentication settings
For this walkthrough, set Connection Logging to No. Connection logging is a feature of Client VPN that enables you to capture connection logs for your Client VPN endpoint. Those logs are published to an Amazon CloudWatch Logs log group in your account. For production environments or for troubleshooting purposes, you can enable connection logging while or after you create the endpoint.
Select the VPC ID to associate with the endpoint. This should be the VPC with an EC2 instance deployed that can be used to test connectivity. You can select an existing security group, or create a new one for the VPN endpoint. The only requirement for this walkthrough is that it has outbound rules that allow access to your test EC2 instance. For additional flexibility, you can create and apply multiple security groups that use different rulesets to the endpoint to provide fine-grained control of which resources can be accessed within the VPC.
Select Enable self-service portal and—if desired—select Enable split-tunnel. Split tunneling is designed to ensure that only client traffic destined for the IP ranges configured on the Client VPN endpoint is routed to your VPC. By default, all traffic, including internet bound traffic, is routed through your VPC.
Choose Create Client VPN endpoint.

To configure the Client VPN endpoint

On the Client VPN endpoint Associations tab, select Associate. Select the same VPC that you chose when you set up the endpoint and select a subnet to associate. This creates an elastic network interface (ENI) in the selected subnet that will be the ingress point from VPN clients into your AWS VPC. For production environments, you should select at least two subnets based upon your redundancy requirements.
Authorizing VPN ingress traffic from your users can be done either globally for all users or via group membership. When granting access via an AWS IAM Identity Center group, you must use the group ID of the AWS IAM Identity Center group, not the friendly name of the group. After selecting a group in the AWS IAM Identity Center management console, you can find group ID in the Details section. You can also obtain the group ID by using AWS Command Line Interface (AWS CLI) to issue the following command, replacing the <AWSRegion>, <Identity Store ID>, and <AWS IAM Identity Center Group Display Name> variables with your information. This command should be issued within the same AWS account where AWS IAM Identity Center is configured. The identity store ID can be found in the AWS IAM Identity Center console under Settings.
```
aws identitystore list-groups --region <AWSRegion> --identity-store-id <Identity Store ID> --filter AttributePath=DisplayName,AttributeValue=<AWS IAM Identity Center Group Display Name>
```
Create an ingress authorization rule by selecting Authorize Ingress on the Authorization tab. Configure the destination network to enable as 0.0.0.0/0, set Grant access to: Allow access to users in a specific access group and enter the access group ID that you discovered in the previous step. This should be the group that contains one of your test user accounts. For production environments, you should follow the principle of least privilege and narrow the destination network range to only what is required. Ingress authorization rules can be used to restrict network access to specific network ranges based upon IdP group membership. You can use a client connection handler to enforce additional security policies on Client VPN connections. Refer to the Client VPN documentation for additional details.
- Connection authorization
- Enforcing VPN access policies with AWS Client VPN connection handler
Figure 7: Add authorization rule
From the Client VPN Endpoint Summary tab, copy the Self-service portal URL to use in the next step.

To set up the Client VPN self-service portal

Open the Client VPN self-service SAML application in the AWS IAM Identity Center management console to edit the configuration.
In the Application start URL textbox, paste the Client VPN endpoint self-service portal URL that you copied in the previous section. This ties the Client VPN self-service SAML application to the self-service portal URL for the specific Client VPN endpoint that you created, allowing users to download their AWS VPN Client configuration file.

Figure 8: Client VPN self-service portal

Test the solution

During the testing phase, you download the VPN client configuration file and configure the VPN client application. You then create a Client VPN connection and validate that you have access to your target VPC. You also test the Client VPN connection with multiple user accounts in order to confirm that the ingress authorization rules are functioning as expected.

To test the Client VPN solution:

Open an internet browser and sign in to your AWS IAM Identity Center user portal as a user who has access to the VPN Client SAML applications and is a member of the AWS IAM Identity Center group defined in the VPN endpoint ingress authorization rule. You should see two new SAML applications. Select the VPN client self-service application.
In the VPN Client Self Service portal, you can download the AWS VPN Client software if you haven’t already done so. Select Download client configuration and save the file on your local device. Close the browser window that you used to sign in to the AWS IAM Identity Center user portal.
Open the AWS VPN Client application and configure a new profile, selecting the client configuration file that you downloaded in the previous step. Once your client profile has been created, select Connect.

Figure 9: VPN Client ready to connect
A new browser window should open automatically to an AWS IAM Identity Center sign-in page. Enter the credentials of your test user who is a member of the AWS IAM Identity Center group defined in your ingress authorization rule.
Upon a successful connection through the VPN client, you can make a management connection (RDP, SSH, HTTP, or other) to one of the EC2 instances within your VPC. Connect to the private IPv4 address of your EC2 instance (rfc1918)—you should not attempt to connect to your EC2 instance through an EIP. You might need to adjust the security group rules on your EC2 instance to allow traffic from the subnets that you selected when you created the VPN endpoint associations.
Once you have a successful connection to your test EC2 instance and you know that your Client VPN connectivity is working, you should also validate that access is denied for users who aren’t a member of the group specified in your ingress authorization rule.
1. Disconnect from your Client VPN connection and close all browser windows.
2. Depending upon your internet browser and its configuration, you might need to delete any cookies associated with your AWS IAM Identity Center user portal in order to sign in as a different AWS IAM Identity Center user.
3. Initiate a new Client VPN connection and sign in as the test user account that is not a member of the AWS IAM Identity Center group specified in the ingress authorization rule.
4. You should be able to successfully establish the Client VPN connection, but not to access your test EC2 instance. This validates that the ingress authorization rule isn’t allowing Client VPN traffic from users who aren’t a member of the AWS IAM Identity Center group to enter your VPC.

Troubleshooting

If you have any issues completing the walkthrough and testing, here are some things that you can check:

In the AWS VPC management console, review the Connections tab to verify that you see a connection from your test user account and that it’s active.
Confirm that your test user account is in the group that was defined in your ingress authorization rule.
Confirm that the access group ID specified in the ingress authorization rule is for the AWS IAM Identity Center group that your test user is a member of.
Confirm that the AWS IAM Identity Center group still exists and hasn’t been deleted. You might encounter an error message similar to the one shown in Figure 10 if you attempt a Client VPN connection but the AWS IAM Identity Center group no longer exists.

Figure 10: Error message
If you receive a credential error when attempting to sign in to the AWS IAM Identity Center browser window that’s launched by the VPN Client application, you might have an issue with the ACM certificate that you’re using. There can be authentication related issues if the root CA certificates aren’t correct or if any part of the certificate chain is missing.
Validate your EC2 instance security group rules and VPC route table configuration. From a routing perspective, your test EC2 instance must be accessible from the subnet that you selected when you created the Client VPN endpoint association.
If you want to see the SAML assertion that’s being sent to the AWS VPN client application. Sign in to the AWS IAM Identity Center user portal, and hold down the Shift key while selecting the VPN client SAML application. A new browser tab will open with the SAML assertion visible. The SAML assertion contains the access group IDs of all groups that your test user is a member of. You can use this information to validate that the correct group memberships and group IDs are defined in your ingress authorization rules.
Make sure that TCP port 35001 is available on your client device. It shouldn’t be used by any other process or blocked by a firewall. Port 35001 only needs to be open on your localhost interface. The SAML assertion is sent to localhost on port 35001 as an HTTP POST from the browser window opened by the AWS VPN client application after a successful sign-in.

Clean up the test environment

To avoid charges for the use of AWS EC2, Client VPN, IAM Identity Center, or ACM services, remove any components that were created as part of this walkthrough. Components that can be deleted if applicable are:

The Client VPN endpoint. You must first remove all associations that were created for the endpoint.
The EC2 instance and VPC.
The test IdPs from IAM.
The VPN client custom SAML applications from AWS IAM Identity Center.
AWS IAM Identity Center users and groups.
The ACM certificate.

Conclusion

In this blog post, we’ve shown how you can integrate Client VPN and AWS IAM Identity Center to provide a familiar and seamless VPN connection experience to your users. By adding the Client VPN self-service portal, you can reduce the effort needed to deploy the solution by allowing users to perform their own VPN client application installation and configuration. We demonstrated the creation of IdPs using AWS IAM Identity Center custom applications and then showed you how to configure a Client VPN endpoint to use SAML-based federated authentication and associate it with the IdPs. Client VPN users can then use their centralized credentials to connect to the Client VPN endpoint and access specific network ranges based upon their group membership or further refined through a client connection handler.

If you have feedback about this post, submit comments in the Comments section below.

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.

AWS Security Blog