{"id":13722129,"url":"https://github.com/widdix/aws-ec2-ssh","last_synced_at":"2025-05-07T14:31:10.185Z","repository":{"id":46191903,"uuid":"55903770","full_name":"widdix/aws-ec2-ssh","owner":"widdix","description":"Manage AWS EC2 SSH access with IAM","archived":true,"fork":false,"pushed_at":"2022-03-07T20:28:18.000Z","size":221,"stargazers_count":828,"open_issues_count":23,"forks_count":289,"subscribers_count":43,"default_branch":"master","last_synced_at":"2024-11-14T11:39:50.764Z","etag":null,"topics":["amazon-web-services","aws","aws-ec2","ssh"],"latest_commit_sha":null,"homepage":"https://cloudonaut.io/manage-aws-ec2-ssh-access-with-iam/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/widdix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"widdix"}},"created_at":"2016-04-10T14:31:09.000Z","updated_at":"2024-10-25T02:01:24.000Z","dependencies_parsed_at":"2022-09-13T08:41:50.460Z","dependency_job_id":null,"html_url":"https://github.com/widdix/aws-ec2-ssh","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widdix%2Faws-ec2-ssh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widdix%2Faws-ec2-ssh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widdix%2Faws-ec2-ssh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widdix%2Faws-ec2-ssh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/widdix","download_url":"https://codeload.github.com/widdix/aws-ec2-ssh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252895579,"owners_count":21821184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-web-services","aws","aws-ec2","ssh"],"created_at":"2024-08-03T01:01:24.877Z","updated_at":"2025-05-07T14:31:09.684Z","avatar_url":"https://github.com/widdix.png","language":"Java","funding_links":["https://github.com/sponsors/widdix"],"categories":["Java","Security Enabling Tools"],"sub_categories":[],"readme":"# Manage AWS EC2 SSH access with IAM\n\n\u003e This project is no longer maintained. AWS offers two alternatives to solve similar needs:\n\u003e * [Amazon EC2 Instance Connect](https://aws.amazon.com/blogs/compute/new-using-amazon-ec2-instance-connect-for-ssh-access-to-your-ec2-instances/)\n\u003e * [AWS Systems Manager Session Manager ](https://aws.amazon.com/de/blogs/aws/new-session-manager/)\n\nUse your IAM user's public SSH key to get access via SSH to an **EC2 instance** running\n* Amazon Linux 2018.03\n* Amazon Linux 2\n* Ubuntu 16.04\n* SUSE Linux Enterprise Server 12 SP3\n* RHEL 7.4\n* CentOS 7\n\n`aws-ec2-ssh` depends on the [AWS CLI](https://aws.amazon.com/cli/) and `git` if you use the `install.sh` script.\n\n## How does it work\n\nA picture is worth a thousand words:\n\n![Architecture](./docs/architecture.png?raw=true \"Architecture\")\n\n* On first start, all IAM users are imported and local UNIX users are created\n* The import also runs every 10 minutes (via cron - calls [`import_users.sh`](./import_users.sh))\n* You can control which IAM users get a local UNIX user and are therefore able to login\n   * all (default)\n   * only those in specific IAM groups\n* You can control which IAM users are given sudo access\n  * none (default)\n  * all\n  * only those in a specific IAM group\n* You can specify the local UNIX groups for the local UNIX users\n* You can assume a role before contacting AWS IAM to get users and keys (e.g. if your IAM users are in another AWS account)\n* On every SSH login, the EC2 instance tries to fetch the public key(s) from IAM using sshd's `AuthorizedKeysCommand`\n* As soon as the public SSH key is deleted from the IAM user a login is no longer possible\n\n### Demo with CloudFormation\n\n1. Upload your public SSH key to IAM: \n   1. Open the Users section in the [IAM Management Console](https://console.aws.amazon.com/iam/home#users)\n   2. Click the row with your user\n   3. Select the **Security Credentials** tab\n   4. Click the **Upload SSH public key** button at the bottom of the page\n   5. Paste your public SSH key into the text-area and click the **Upload SSH public key** button to save\n2. Create a CloudFormation stack based on the `showcase.yaml` template\n3. Wait until the stack status is `CREATE_COMPLETE`\n4. Copy the `PublicName` from the stack's outputs\n5. Connect to the EC2 instance via `ssh $Username@$PublicName` with `$Username` being your IAM user, and `$PublicName` with the stack's output\n\n## How to integrate this system into your environment\n\n### Install via RPM\n\n1. Upload your public SSH key to IAM: \n   1. Open the Users section in the [IAM Management Console](https://console.aws.amazon.com/iam/home#users)\n   2. Click the row with your user\n   3. Select the **Security Credentials** tab\n   4. Click the **Upload SSH public key** button at the bottom of the page\n   5. Paste your public SSH key into the text-area and click the **Upload SSH public key** button to save\n2. Attach the IAM permissions defined in [`iam_ssh_policy.json`](./iam_ssh_policy.json) to the EC2 instances (by creating an IAM role and an Instance Profile)\n3. Install the RPM\u003csup\u003e1\u003c/sup\u003e: `rpm -i https://s3-eu-west-1.amazonaws.com/widdix-aws-ec2-ssh-releases-eu-west-1/aws-ec2-ssh-1.9.2-1.el7.centos.noarch.rpm`\n4. The configuration file is placed into `/etc/aws-ec2-ssh.conf`\n5. The RPM creates a crontab file to run import_users.sh every 10 minutes. This file is placed in `/etc/cron.d/import_users`\n\n\u003e \u003csup\u003e1\u003c/sup\u003eCheck the [releases](https://github.com/widdix/aws-ec2-ssh/releases) and use the latest released RPM.\n\n### Install via install.sh script\n\n1. Upload your public SSH key to IAM: \n   1. Open the Users section in the [IAM Management Console](https://console.aws.amazon.com/iam/home#users)\n   2. Click the row with your user\n   3. Select the **Security Credentials** tab\n   4. Click the **Upload SSH public key** button at the bottom of the page\n   5. Paste your public SSH key into the text-area and click the **Upload SSH public key** button to save\n2. Attach the IAM permissions defined in [`iam_ssh_policy.json`](./iam_ssh_policy.json) to the EC2 instances (by creating an IAM role and an Instance Profile)\n3. Run the `install.sh` script as `root` on the EC2 instances. Run `install.sh -h` for help.\n4. The configuration file is placed into `/etc/aws-ec2-ssh.conf`\n5. Connect to your EC2 instances now using `ssh $Username@$PublicName` with `$Username` being your IAM user, and `$PublicName` being your server's name or IP address\n\n## IAM user names and Linux user names\n\nAllowed characters for IAM user names are:\n\u003e alphanumeric, including the following common characters: plus (+), equal (=), comma (,), period (.), at (@), underscore (_), and hyphen (-).\n\nAllowed characters for Linux user names are (POSIX (\"Portable Operating System Interface for Unix\") standard (IEEE Standard 1003.1 2008)):\n\u003e alphanumeric, including the following common characters: period (.), underscore (_), and hyphen (-).\n\nTherefore, characters that are allowed in IAM user names but not in Linux user names:\n\u003e plus (+), equal (=), comma (,), at (@).\n\nThis solution will use the following mapping for those special characters when creating users:\n* `+` =\u003e `.plus.`\n* `=` =\u003e `.equal.`\n* `,` =\u003e `.comma.`\n* `@` =\u003e `.at.`\n\nSo instead of `name@email.com` you will need to use `name.at.email.com` when login via SSH.\n\nLinux user names may only be up to 32 characters long.\n\n## Configuration\n\nThere are a couple of things you can configure by editing/creating the file `/etc/aws-ec2-ssh.conf` and adding\none or more of the following lines:\n\n```\nASSUMEROLE=\"IAM-role-arn\"                      # IAM Role ARN for multi account. See below for more info\nIAM_AUTHORIZED_GROUPS=\"GROUPNAMES\"             # Comma separated list of IAM groups to import\nSUDOERS_GROUPS=\"GROUPNAMES\"                    # Comma seperated list of IAM groups that should have sudo access or `##ALL##` to allow all users\nIAM_AUTHORIZED_GROUPS_TAG=\"KeyTag\"             # Key Tag of EC2 that contains a Comma separated list of IAM groups to import - IAM_AUTHORIZED_GROUPS_TAG will override IAM_AUTHORIZED_GROUPS, you can use only one of them \nSUDOERS_GROUPS_TAG=\"KeyTag\"                    # Key Tag of EC2 that contains a Comma separated list of IAM groups that should have sudo access - SUDOERS_GROUPS_TAG will override SUDOERS_GROUPS, you can use only one of them\nSUDOERSGROUP=\"GROUPNAME\"                       # Deprecated! IAM group that should have sudo access. Please use SUDOERS_GROUPS as this variable will be removed in future release.\nLOCAL_MARKER_GROUP=\"iam-synced-users\"          # Dedicated UNIX group to mark imported users. Used for deleting removed IAM users\nLOCAL_GROUPS=\"GROUPNAMES\"                      # Comma seperated list of UNIX groups to add the users in\nUSERADD_PROGRAM=\"/usr/sbin/useradd\"            # The useradd program to use. defaults to `/usr/sbin/useradd`\nUSERADD_ARGS=\"--create-home --shell /bin/bash\" # Arguments for the useradd program. defaults to `--create-home --shell /bin/bash`\nUSERDEL_PROGRAM=\"/usr/sbin/userdel\"            # The userdel program to use. defaults to `/usr/sbin/userdel`\nUSERDEL_ARGS=\"--force --remove\"                # Arguments for the userdel program. defaults to `--force --remove`\n```\n\nThe LOCAL_MARKER_GROUP will be created if it does not exist. BEWARE: DO NOT add any manually created users\nto this group as they will be deleted in the next sync. This group is used by aws-ec2-ssh to keep track\nof what users were imported in the last run.\n\n## Using a multi account strategy with a central IAM user account\n\nIf you are using multiple AWS accounts you probably have one AWS account with all the IAM users (I will call it **users account**), and separate AWS accounts for your environments (I will call it **dev account**). Support for this is provided using the AssumeRole functionality in AWS.\n\n### Setup users account\n\n1. In the **users account**, create a new IAM role\n2. Select Role Type **Role for Cross-Account Access** and select the option **Provide access between AWS accounts you own**\n3. Put the **dev account** number in **Account ID** and leave **Require MFA** unchecked\n4. Skip attaching a policy (we will do this soon)\n5. Review the new role and create it\n6. Select the newly created role\n7. In the **Permissions** tab, expand **Inline Policies** and create a new inline policy\n8. Select **Custom Policy**\n9. Paste the content of the [`iam_ssh_policy.json`](./iam_ssh_policy.json) file and replace `\u003cYOUR_USERS_ACCOUNT_ID_HERE\u003e` with the AWS Account ID of the **users account**.\n\n### Setup dev account\n\nFor your EC2 instances, you need a IAM role that allows the `sts:AssumeRole` action\n\n1. In the **dev account**, create a new IAM role\n2. Select ROle Type **AWS Service Roles** and select the option **Amazon EC2**\n3. Skip attaching a policy (we will do this soon)\n4. Review the new role and create it\n5. Select the newly created role\n6. In the **Permissions** tab, expand **Inline Policies** and create a new inline policy\n7. Select **Custom Policy**\n8. Paste the content of the [`iam_crossaccount_policy.json`](./iam_crossaccount_policy.json) file and replace `\u003cYOUR_USERS_ACCOUNT_ID_HERE\u003e` with the AWS Account ID of the **users account** and `\u003cYOUR_USERS_ACCOUNT_ROLE_NAME_HERE\u003e` with the IAM rol name that you created in the **users account**\n9. Create/edit the file `/etc/aws-ec2-ssh.conf` and add this line: `ASSUMEROLE=\"IAM-ROLE-ARN` or run the install.sh script with the -a argument\n\n## Limitations\n\n* your EC2 instances need access to the AWS API either via an Internet Gateway + public IP or a Nat Gatetway / instance.\n* it can take up to 10 minutes until a new IAM user can log in\n* if you delete the IAM user / ssh public key and the user is already logged in, the SSH session will not be closed\n* uid's and gid's across multiple servers might not line up correctly (due to when a server was booted, and what users existed at that time). Could affect NFS mounts or Amazon EFS.\n* this solution will work for ~100 IAM users and ~100 EC2 instances. If your setup is much larger (e.g. 10 times more users or 10 times more EC2 instances) you may run into two issues:\n  * IAM API limitations\n  * Disk space issues\n* **not all IAM user names are allowed in Linux user names** (e.g. if you use email addresses as IAM user names). See section [IAM user names and Linux user names](#iam-user-names-and-linux-user-names) for further details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiddix%2Faws-ec2-ssh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiddix%2Faws-ec2-ssh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiddix%2Faws-ec2-ssh/lists"}