Documentation
System StatusPortal Login

Passport

Suggest Edits

The Fanatical Support for AWS offering includes access to our Passport™ service. This is the same capability that Rackers use to access your environment. Passport leverages AWS Systems Manager to provision short lived users onto your EC2 instances and provide network access into your VPC.

Passport v2 offers several improvements over our original Passport tool, including:

  • User accounts are created on demand and cleaned up after use.
  • Public subnets and bastion hosts are no longer required in customer VPCs.
  • EC2 instances with multiple Elastic Network Interfaces (ENIs) are now supported.

Passport’s primary concept is an Access Request. Each access request defines who is accessing your account, which specific EC2 instances they are accessing, the duration of the access request, and the reason for the access. Access requests default to expiring after 1 hour but can be extended up to 12 hours.

As an example, a Racker receiving a CloudWatch monitoring alarm for CPU utilization on your application server might create an access request referencing the alert ticket and granting them access to your active and passive database instances. Once troubleshooting and remediation is complete, the Racker completes the access request, immediately removing the short-lived user from your instances.

All access request actions, from access request creation through expiration, are logged in Logbook.

Installation

AWS Systems Manager Agent

All EC2 instances must have AWS Systems Manager Agent 2.3.672.0 or higher installed to work with Passport. Each EC2 instance must also be configured with an instance profile that allows AWS Systems Manager to perform actions on your instances. Rackspace recommends using the AmazonSSMManagedInstanceCORE managed IAM policy.

You can learn more about how AWS Systems Manager is used in the Architecture section.

Passport CLI

You must install the Passport CLI on your local workstation in order to connect to instances with Passport. Before you install the Passport CLI, make sure that you have the following dependencies installed:

Linux and MacOS

Run the following command in your terminal:

curl -sL https://passport-packages.manage.rackspace.com/installer/latest | sudo sh -s

If you’d like to install the CLI directly rather than using the installation script, you can download the latest binary using the following links:

Once you have installed the Passport CLI, you can verify that it is installed and working correctly by running the following command:

passport --help

Windows

Download and run the installer by using the following links:

Once the AWS Systems Manager Agent and Passport CLI are install, you’re ready to start using Passport. You can learn more about how to use the Passport CLI in the CLI Usage section.

CLI Usage

Once the Passport CLI is installed, you can log in to the CLI. The following command will open your browser and you will be prompted to log in with your Rackspace credentials:

📘

passport auth login

Next, browse to the Passport section of the Fanatical Support for AWS control panel. Click Create Access Request and complete the form to initiate access to your instances.

Once the access request is active, you can connect to any instance that belongs to that access request by using the following command:

📘

passport connect

When connecting to an EC2 instance running Linux, the connect command will automatically open an SSH connection to the target server.

When connecting to an EC2 instance running Windows, the connect command will provide you with connection information for an RDP connection. Here is a sample output for an RDP connection:

📘

Windows Login Credentials:

Host: localhost:58829
Username:
Password: <password

To connect with RDP, open your preferred RDP client and use the information above to connect.

SSH Integration

Most users will only interact with the passport CLI tool directly. However, you can use Passport with any SSH-based tooling by using the ssh-config command. This command generates an SSH config that can be used with any tooling that supports SSH config files, including ssh port forwarding, scp, and Ansible.

📘

#Outputs a path to an SSH config

passport ssh-config

Forwarding Ports

SSH port forwarding is commonly used to access a service that is not directly accessible to the end user. For example, RDS database instances do not have the SSM agent installed and cannot be used with Passport directly. However, SSH port forwarding can be used to access the RDS instance by using a Passport-enabled server as an intermediary.

📘

# Forwarding localhost:13306 to an RDS instance on port 3306 through i-123456

ssh -F $(passport ssh-config) -L 13306:my_instance.us-east-1.rds.amazonaws.com:3306 i-123456

Once the above command is successfully running, you can use familiar local tools and connect them to localhost:13306 to work with your RDS instance.

📘

Note: You must also have security group rules in place that permit access from the intermediate instance to the AWS resource that you’re accessing.

Copying Files

scp can be used to copy files to and from a target instance. The following command copies the file data.csv from your local workstation to your home directory on the target server i-1234567890:

📘

# Copy data.csv from the local workstation to i-1234567890

scp -F $(passport ssh-config) data.csv i-1234567890:~

Permissions

📘

Note: This behavior applies specifically to Passport v2 and represents a change in how permissions work. The original Passport tool for AWS did not require an IAM policy to use Passport.

Passport relies on two settings to determine which instances a user can access with Passport. First, the user must have their Fanatical Support for AWS permission for an AWS account set to “Admin”. If the permission is set to either “Observer” or “None”, the user will not have access to any instances in that AWS account. Second, the user must have an IAM policy that allows the ssm:StartSession and ssm:TerminateSession action to be performed against the target instance. This setting allows you to choose which instances within an AWS account a user will have access to. Together, these two settings give you granular control over which instances can be accessed using Passport.

There are several IAM policies available out of the box that are commonly used with Passport:

  • AdministratorAccess grants full access to all AWS resources and will allow a user to access any instance in the account using Passport.
  • PowerUserAccess grants access to non-IAM AWS resources. It will allow a user to access any instance in the account using Passport.
  • AmazonSSMFullAccess grants access to all actions and resources within AWS Systems Manager. It will allow a user to access any instance in the account using Passport.
  • RackspacePassportOnly grants ssm:StartSession and

ssm:TerminateSession on all instances. It will

allow a user to access any instance in the account using Passport, but the user won’t have any other permissions in the AWS console.

  • RackspaceReadOnlyWithPassport grants read-only access to most AWS resources as well as ssm:StartSession and ssm:TerminateSession on all instances. It will allow a user to access any instance in the account using Passport.

Additionally, you can define custom IAM policies that allow you to further restrict which instances can be accessed within an AWS account. See Additional Sample IAM Policies for Session Manager for more information on how to use IAM policies to limit access to certain instances.

Architecture

Passport provides secure, auditable access to servers inside a Virtual Private Network (VPC). In addition to Passport, there are several other components that play a part in this feature: AWS Systems Manager and Identity Stores. This document discusses each of these components and the role they play in governing server access.

Passport handles all orchestration for an access request including: authenticating a user with their Identity Store via SAML, creation/deletion of short-lived users, and generation of temporary credentials.

AWS Systems Manager is used to create short-lived users and distribute credentials to servers that are accessed via Passport. Session Manager tunneling is also used to make a network connection to the target servers. Users are created at the time an access request is created and are cleaned up when the access request is complete. Credentials are only valid for the lifetime of the access request.

Identity Store(s) are the source of truth for all users and their associated permissions. Rackspace Customer Identity is the identity store that is used for customer users, and it can optionally be connected via SAML to an on-premise identity store via Rackspace Identity Federation. Racker permissions are stored in Rackspace’s internal identity store.

https://d33wubrfki0l68.cloudfront.net/1d6fb7c9ea8592ff1c423121bd5b89705a763fb9/478cb/docs/fanatical-support-aws/_static/img/passport-v2-architecture.png

  1. User creates an access request via Passport. The user specifies their reason for access and the servers that can be accessed.
  2. Passport provisions a short-lived user on the servers being accessed. On Linux-based systems, the short-lived user is authenticated with an SSH certificate. On Windows systems, the short-lived user is authenticated with a password. Both the SSH certificate and the password are generated by Passport and are only valid for the duration of the access request. Provisioning of the short-lived user is performed using Systems Manager Run Command.
  3. User connects to resources using a Session Manager tunnel. Both SSH and RDP traffic are routed from the user’s workstation through a Session Manager tunnel to the target resources. Once the tunnel is established, the SSH or RDP connection is authenticated using the temporary credentials generated during step 2.
  4. Passport removes the short-lived user from the server being accessed. The short-lived user is removed and all associated credentials are revoked. Clean up of the short-lived user is performed using Systems Manager Run Command.

Changelog

2024-09-01 - v1.3.5

Version: 1.3.5

The ssh-config command now supports 2 new parameters to generate an SSH config file with explicit values:

  • --keyType specifies either ed25519 or RSA key type
  • --i validates the config for an individual VM instance. Executing passport ssh-config --i <resourceID> will provide the config path if the VM is in a valid state, or will provide a warning message if the VM is in invalid state.

2024-02-09 - v1.3.4

Version: 1.3.4

Bug Fix - Fixed issue with passport version --self-update on Windows platforms due to mismatch of SHA256 checksum.

2023-12-07 - v1.3.3

Version: 1.3.3

passport versioncommand no longer emits extra log lines to standard output.

2023-12-04 - v1.3.2

Version: 1.3.2

The install-ssm-plugin command will now upgrade to the latest version of the SSM plugin if it is not installed.

2023-11-13 - v1.3.1

Version: 1.3.1

Passport CLI updated algorithm for selecting SSH user certificate signing defaults.

2023-09-25 - v1.3.0

Version: 1.3.0

  • Self-Update and version management

Self-Update

Passport CLI now supports the --self-update option to update to the latest available version:

passport version --self-update

or
sudo passport version --self-update (for macOS/Linux)

You can also switch to a specific Passport version. For example if you are on version 1.2.1 and would like to move to 1.1.0:

sudo passport version --self-update --to-version=1.1.0

2023-08-28 - v1.2.1

Version: 1.2.1

  • Passport CLI now collects diagnostic information for support and troubleshooting.

2023-08-15 - v1.2.0

Version: 1.2.0

  • Fixed Passport crash when tunneling if the SSM agent was missing on the target instance.
  • Performance improvements.

Ed25519 Key Support

Added support for Ed25519 keys. Systems which no longer support RSA SHA-1 key signing, including Ubuntu 24 servers and Mac workstations running macOS Ventura or above, should see improved user experience when using Passport.

A new --keyType flag has been added to the connect and ssh-config commands to enable users to force a particular key type if necessary, but there should be no change to the user experience when connecting. Passport will attempt to connect using the most appropriate key type, and will fallback to existing behavior if necessary. Existing RSA keys are still supported.

2023-01-19 - v1.1.0

Version: 1.1.0

Support STS tokens with higher access granularity

Passport now supports STS tokens which respect account level IAM policies and provide more access granularity.

This release also handles a bug in generating STS tokens for AWS native Passport users.

2022-10-07 - v1.0.0

Version: 1.0.0

Support for Active Directory Domain Controllers

Passport now supports connecting to domain controllers. In order to support this change, we have changed the format of the Rackspace usernames generated by Passport to avoid collisions when accessing multiple domain controllers at the same time:

Old Format: racker-<masked-id>

New Format (Non-Domain Controller): rs-<masked-id>

New Format (Domain Controller): rs-<masked-id>-<random-suffix>

Semantic Versioning

All CLI releases beginning with 1.0.0 will follow semantic versioning.

2020-11-03

Version: 5bba0a79

Support for SHA-2 Certificate Signing

Previous version of Passport always signed SSH keys using the SHA-1 algorithm. Newer OSes, including Ubuntu 20, are now shipping openssh 8.2. openssh 8.2+ drops support for SHA-1 certificates. Starting with this version of Passport, Passport will always generate both SHA-1 and SHA-2 certificates and attempt to authenticate with both versions. This allows Passport to work for older OSes that only support SHA-1 as well as newer OSes that only support SHA-2.

Updated 3 months ago