Skip to content

AWS IAM Permissions

StormTunnel uses two AWS identities for a Session Manager tunnel: your AWS user or role starts the session, and the EC2 instance role lets SSM Agent communicate with Systems Manager. Database network access is controlled separately by VPC routes and security groups.

Permissions for StormTunnel Users

Ask your AWS administrator to grant the permissions required to:

  • Start a session to the specific EC2 instance with ssm:StartSession.
  • Use the port-forwarding document: AWS-StartPortForwardingSessionToRemoteHost when a Database or Service Host is set, or AWS-StartPortForwardingSession when it is empty.
  • End sessions created by your identity with ssm:TerminateSession.
  • Optionally describe instances and Systems Manager status (ec2:DescribeInstances, ec2:DescribeInstanceStatus, ssm:DescribeInstanceInformation) for instance discovery and the Check Access tests. Denied Describe checks do not prevent starting a tunnel to an instance ID you enter manually.

Scope access to the intended instances, regions, accounts, and session documents. AWS's Session Manager end-user policy examples show how to scope ssm:StartSession and session resources. AWS also documents session document permissions.

Do not attach AmazonSSMManagedInstanceCore to a person or workstation as the user policy. It is an instance policy for the SSM-managed EC2 node.

Check Permissions in StormTunnel

In the AWS tunnel editor, the Check Access section has three actions:

  • Validate checks your credentials and tries to verify the managed instance's status. When AWS does not allow the required Describe calls, StormTunnel reports that it could not verify the status; those optional permissions do not by themselves prevent starting a tunnel with an instance ID.
  • Test Permissions checks the three Describe permissions with read-only calls and lists each permission as Granted, Missing, or Unverified. ssm:StartSession and ssm:TerminateSession are always Unverified because checking them would require starting or ending a real session. A successful preflight therefore does not prove that those session permissions are allowed or that the managed instance can reach the database. Starting and stopping the tunnel exercises the session permissions; connecting a database client through the local port verifies the database path and login. Results are cached for five minutes.
  • Copy IAM Policy copies a broad example policy (all five actions, Resource: "*") to the clipboard. Give it to your administrator as a starting point and narrow the resources before using it.

Both checks resolve credentials through the installed AWS CLI (aws configure export-credentials, AWS CLI v2), exactly as starting a tunnel does. IAM Identity Center profiles that use sso-session work. If credentials are expired, MFA is required, or the AWS CLI is missing, StormTunnel shows that problem instead of a permissions result.

Permissions for the EC2 Instance

The EC2 instance needs an IAM role that lets SSM Agent register and communicate with Systems Manager. AWS's AmazonSSMManagedInstanceCore managed policy is the standard starting point for that role. See AWS instance permissions.

Network Access to RDS

IAM permissions do not grant network access to the database. Confirm that:

  • The EC2 instance can resolve and reach the RDS endpoint and port.
  • Routes and network ACLs allow the path.
  • The RDS security group allows inbound traffic from the EC2 instance's security group on the database port.

See AWS configuration for the full checklist.

Permission Errors

If StormTunnel reports access denied:

  1. Confirm which profile StormTunnel is using and which AWS identity it resolves to (aws sts get-caller-identity --profile PROFILE).
  2. Ask your administrator to check the user or role policy and any permission boundary or organization policy.
  3. Confirm that the policy allows the port-forwarding session document.
  4. Check the EC2 instance role and Systems Manager status.
  5. Re-authenticate the profile and try again.