StrongDM Gateway AMI Installation Guide

Overview #

The StrongDM Gateway Amazon Machine Image (AMI) makes it easy to deploy nodes (gateways and relays) when launching Amazon EC2 instances. The AMI comes with the StrongDM package pre-installed. When you launch the EC2 instance using the correct token, the node registers in your StrongDM organization without you having to manually create it, and you are ready to connect to your resource.

This guide describes how to attach the StrongDM Gateway AMI to a new EC2 instance, set a StrongDM token, and enable the correct security settings in order to connect to EC2 through StrongDM.

Prerequisites #

Be an Administrator in StrongDM.

Decide whether you want to install a gateway or a relay. If installing a gateway, you need an admin token (SDM_ADMIN_TOKEN). If installing a relay, you need a relay token (SDM_RELAY_TOKEN).

Steps #

These instructions explain how to launch an EC2 instance and get a StrongDM token to configure your gateway. We recommend that you keep AWS and the StrongDM Admin UI open in separate browser tabs or windows, so you can easily switch between them.

Get a StrongDM token #

If you are setting up a self-registering gateway, follow these steps.

1. In a new browser tab or window, log in to the Admin UI at app.strongdm.com.
2. Go to Principals > Tokens, and click Add token.
3. On the Create Admin Token page, for Name, enter a descriptive name (for example, “Gateway AMI Creator"), so you can remember what this token is for later.
4. Set the token’s Expiration (1 week, 1 month, 1 year, or never).
5. Select the checkbox for Relays, and underneath that, select List and Create.
6. Click Create gateway to generate the SDM_ADMIN_TOKEN value.
7. Copy the admin token value and save it somewhere safe.

If you are setting up a relay, follow these steps.

1. In a new browser tab or window, log in to the Admin UI at app.strongdm.com.
2. Go to Networking > Relays and click Add relay.
3. Fill out the name of the relay and click Create relay to generate the SDM_RELAY_TOKEN value.
4. Copy the relay token value and save it somewhere safe.

Create a new EC2 instance #

1. In AWS, go to the EC2 Dashboard and click Launch instance.

2. On the Choose an Amazon Machine Image (AMI) page, click Community AMIs.

3. Search for “StrongDM” and then choose the latest AMI available.

4. Click Select to attach the StrongDM Gateway AMI to your EC2 instance root device volume.

5. Choose your instance type and click Next.
   

   The AMI is based on Ubuntu and works on any instance type with two CPUs and four GB of memory. We recommend a t3.medium.

6. This step describes two different ways to configure user data. You can set it up with an admin token or relay token, or you can pull a password from a secrets store.

   To configure user data with an admin token or relay token, do the following:

   1. On the Configure Instance Details page, set all properties the way you want.

   2. Expand Advanced Details and configure User data:

   3. Select As text.

   4. In the User data box, enter the token variable and the token value in this specific format:

      If you are setting up a self-registering gateway, enter SDM_ADMIN_TOKEN=<TOKEN>.

      Example: SDM_ADMIN_TOKEN=hU8sHfhdjgg6g43dgabba...7fdjjg.djs1stqjjdop90fjs946fmh

      If you are setting up a relay, enter SDM_RELAY_TOKEN=<TOKEN>.

      Example: SDM_RELAY_TOKEN=cU2sHfasj5g9g11dgambv...3fdjjg.lks1qiqjjdxy90fjs946fll

   If using an admin token instead of relay token, you also have the option to set a custom listen address (the default is the AWS IP for the EC2 instance) and/or custom port (5000 by default). These can be added after the SDM_ADMIN_TOKEN variable by using the SDM_RELAY_PORT and SDM_LISTEN_ADDRESS variables, each separated by line breaks.
   Only define the SDM environment variables in this section, in the indicated format. Any further customization or additions in the “User data” section could break the AMI installation.

   To configure user data with a password from a secrets store (for example, AWS Secrets Manager) in your StrongDM Gateway AMI, you can structure your user data as follows:

   #!/usr/bin/bash
   
   # Do updates
   apt update -y
   
   # Install required helper apps
   apt install -y unzip awscli jq
   
   # Set the StrongDM admin token variable with key value from Secrets Manager
   # where <SECRET_ID> = ARN of the secret, <REGION> is your AWS region, and <SECRET_KEY> is the name of the key that stores the StrongDM admin token
   # Example:  aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:us-west-2:123456789012:secret:sdm/secrets-4hJMIj --region us-west-2 --query SecretString --output text| jq -r ".admintoken”)
   
   ADMIN_TOKEN=$(aws secretsmanager get-secret-value --secret-id <SECRET_ID> --region <REGION> --query SecretString --output text | jq -r ".<SECRET_KEY>")
   
   # Set the StrongDM admin token variable in a way that systemctl can use it
   
   systemctl set-environment SDM_ADMIN_TOKEN="$ADMIN_TOKEN"
   
   # Restart the StrongDM gateway setup script (the script included with the StrongDM Gateway AMI)
   systemctl restart sdm-relay-setup
   
   # Unset the SDM_ADMIN_TOKEN in systemctl because sdm-proxy fails to start if it has this and SDM_RELAY_TOKEN
   systemctl unset-environment SDM_ADMIN_TOKEN
   
   # Enable and restart sdm-proxy
   systemctl enable sdm-proxy
   systemctl restart sdm-proxy
   

7. Set up the instance the way you want on the Add Storage and Add Tags pages.

8. On the Configure Security Group page, click Add Rule and set:

   • Type: Custom TCP
   • Port Range: 5000
   • Source: Anywhere
   If you are setting up a gateway and you neglect the Configure Security Group step, clients are not able to connect.

9. At the bottom of the page, click Review and Launch.

10. On the Review Instance Launch page that opens, check that everything looks OK, and click Launch.

11. When prompted to select an existing key pair or create a new key pair, choose your key pair, check the acknowledgement box, and click Launch Instances.

Check launch status #

It may take a few minutes to get your instance and gateway or relay up and running. You can check the instance’s launch status in both AWS and StrongDM.

In AWS #

1. Check launch status by going to the Instances page.
2. Find the instance that you just launched. If it is up, it is shown in the Running state.

In StrongDM #

If you set up a self-registering gateway:

1. Look at the Networking > Gateways page.
2. Because you gave the EC2 instance an admin token, the instance registers the StrongDM gateway when the instance comes online. You should now see a new gateway in this section. (If you do not, wait a few minutes and refresh the page.)
3. If you didn’t enter a name for the new gateway, it may have been given a a less than obvious name (such as “stinky-fruit-123"). If you do not know which gateway is for EC2, you can compare the gateway’s Listen Address to the IP address in your EC2 instance. Once you identify the new gateway, you may want to rename it with a more descriptive name (for example, “aws-ec2-gateway”).
4. The gateway is live when its status shows that it is online.

If you set up a relay:

1. Look on the Networking > Relays page, which should now display your new relay.
2. It is normal for the status to be offline or restarting at first. When the state changes to online, your relay is ready.

Now that installation is complete, you can use StrongDM!