prepare v1 release

Author: michaelwittig

DEV.md

@@ -0,0 +1,9 @@
+# Developer notes
+
+## RegionMap
+To update the region map execute the following lines in your terminal:
+
+```
+$ regions=$(aws ec2 describe-regions --query "Regions[].RegionName" --output text)
+$ for region in $regions; do ami=$(aws --region $region ec2 describe-images --filters "Name=name,Values=amzn-ami-hvm-2016.09.1.20161221-x86_64-gp2" --query "Images[0].ImageId" --output "text"); printf "'$region':\n  AMI: '$ami'\n"; done
+```

LICENSE

@@ -7,4 +7,3 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-

README.md

@@ -1,57 +1,53 @@
 # Manage AWS EC2 SSH access with IAM
 
-This showcase demonstrates how you can use your IAM user's public SSH key to get access via SSH to an EC2 instance.
+Use your IAM user's public SSH key to get access via SSH to an EC2 instance.
 
 ## How does it work
 
 A picture is worth a thousand words:
 
 ![Architecture](./docs/architecture.png?raw=true "Architecture")
 
-* On first start all IAM users are imported and local users are created
- * The import also runs every 10 minutes (via cron - calls import_users.sh)
- * You can control which users are given sudo access as:
+* On first start, all IAM users are imported and local UNIX users are created
+ * The import also runs every 10 minutes (via cron - calls `import_users.sh`)
+ * You can control which IAM users get a local UNIX user and are therefore able to login
+  * all (default)
+  * only those in specific IAM groups
+ * You can control which IAM users are given sudo access
   * none (default)
   * all
-  * only those in a specific IAM group.
-* On every SSH login the EC2 instance tries to fetch the public key(s) from IAM using sshd's `AuthorizedKeysCommand`
- * You can restrict that the EC2 instance is only allowed to download public keys from certain IAM users instead of `*`. This way you can restrict SSH access within your account
+  * only those in a specific IAM group
+ * You can specify the local UNIX groups for the local UNIX users
+ * 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)
+* On every SSH login, the EC2 instance tries to fetch the public key(s) from IAM using sshd's `AuthorizedKeysCommand`
  * As soon as the public SSH key is deleted from the IAM user a login is no longer possible
 
-## How to run this showcase (CloudFormation)
+### Demo with CloudFormation
 
 1. Upload your public SSH key to IAM: 
  1. Open the Users section in the [IAM Management Console](https://console.aws.amazon.com/iam/home#users)
  1. Click the row with your user
- 1. Click the "Upload SSH public key" button at the bottom of the page
- 1. Paste your public SSH key into the textarea and click the "Upload SSH public key" button to save
-1. Create a stack based on the `showcase.yaml` template
+ 1. Select the **Security Credentials** tab
+ 1. Click the **Upload SSH public key** button at the bottom of the page
+ 1. Paste your public SSH key into the text-area and click the **Upload SSH public key** button to save
+1. Create a CloudFormation stack based on the `showcase.yaml` template
 1. Wait until the stack status is `CREATE_COMPLETE`
 1. Copy the `PublicName` from the stack's outputs
-1. Connect via ssh `ssh $Username@$PublicName` replace `$Username` with your IAM user and `$PublicName` with the stack's output
+1. Connect to the EC2 instance via `ssh $Username@$PublicName` with `$Username` being your IAM user, and `$PublicName` with the stack's output
 
-## How to integrate this system into your environment (non-CloudFormation)
+## How to integrate this system into your environment
 
-1. Upload your public SSH key to IAM as above
-1. Make sure any instances you want to ssh into contain the correct IAM permissions
-(usually based on IAM Profile, but also possibly based on an IAM user and their credentials).
-Look at the `iam_ssh_policy.json` for an example policy that will permit login.
-1. Make sure those instances automatically run a script similar to `install.sh` (note - that script assumes `git` is installed _and_ instances have access to the Internet; feel free to modify it to instead install from a tarball or using any other mechanism such as Chef or Puppet).
- * If you want to control sudo access, you should modify the value of ‘SudoersGroup’ in import_users.sh
-1. Connect to your instances now using `ssh $Username@$PublicName` with `$Username` being your IAM user, and `$PublicName` being your server's name or IP address.
-
-## Limitations
-
-* your EC2 instances need access to the AWS API either via an Internet Gateway + public IP or a Nat Gatetway / instance.
-* it can take up to 10 minutes until a new IAM user can log in
-* if you delete the IAM user / ssh public key and the user is already logged in, the SSH session will not be closed
-* 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.
-* 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:
-  * IAM API limitations
-  * Disk space issues
-* not all IAM user names are allowed in Linux user names. See section [IAM user names and Linux user names](#iam-user-names-and-linux-user-names) for further details.
+1. Upload your public SSH key to IAM: 
+ 1. Open the Users section in the [IAM Management Console](https://console.aws.amazon.com/iam/home#users)
+ 1. Click the row with your user
+ 1. Select the **Security Credentials** tab
+ 1. Click the **Upload SSH public key** button at the bottom of the page
+ 1. Paste your public SSH key into the text-area and click the **Upload SSH public key** button to save
+1. Attach the IAM permissions defined in `iam_ssh_policy.json` to the EC2 instances (by creating an IAM role and an Instance Profile)
+1. Run the `install.sh` script as `root` on the EC2 instances
+1. 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
 
-### IAM user names and Linux user names
+## IAM user names and Linux user names
 
 Allowed characters for IAM user names are:
 > alphanumeric, including the following common characters: plus (+), equal (=), comma (,), period (.), at (@), underscore (_), and hyphen (-).
@@ -69,3 +65,44 @@ This solution will use the following mapping for those special characters when c
 * `@` => `.at.`
 
 So instead of `[email protected]` you will need to use `name.at.email.com` when login via SSH.
+
+## Using a multi account strategy with a central IAM user account
+
+If 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.
+
+### Setup users account
+
+1. In the **users account**, create a new IAM role
+1. Select Role Type **Role for Cross-Account Access** and select the option **Provide access between AWS accounts you own**
+1. Put the **users account** number in **Account ID** and leave **Require MFA** unchecked
+1. Skip attaching a policy (we will do this soon)
+1. Review the new role and create it
+1. Select the newly created role
+1. In the **Permissions** tab, expand **Inline Policies** and create a new inline policy
+1. Select **Custom Policy**
+1. Paste the content of the `iam_ssh_policy.json` file and replace `<YOUR_USERS_ACCOUNT_ID_HERE>` with the AWS Account ID of the **users account**.
+
+### Setup dev account
+
+For your EC2 instances, you need a IAM role that allows the `sts:AssumeRole` action
+
+1. In the **dev account**, create a new IAM role
+1. Select ROle Type **AWS Service Roles** and select the option **Amazon EC2**
+1. Skip attaching a policy (we will do this soon)
+1. Review the new role and create it
+1. Select the newly created role
+1. In the **Permissions** tab, expand **Inline Policies** and create a new inline policy
+1. Select **Custom Policy**
+1. Paste the content of the `iam_crossaccount_policy.json` file and replace `<YOUR_USERS_ACCOUNT_ID_HERE>` with the AWS Account ID of the **users account** and `<YOUR_USERS_ACCOUNT_ROLE_NAME_HERE>` with the IAM rol name that you created in the **users account**
+1. Replace the `ASSUMEROLE` placeholder with the ARN of the IAM role in `import_users.sh` and `authorized_keys_command.sh`
+
+## Limitations
+
+* your EC2 instances need access to the AWS API either via an Internet Gateway + public IP or a Nat Gatetway / instance.
+* it can take up to 10 minutes until a new IAM user can log in
+* if you delete the IAM user / ssh public key and the user is already logged in, the SSH session will not be closed
+* 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.
+* 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:
+  * IAM API limitations
+  * Disk space issues
+* not all IAM user names are allowed in Linux user names. See section [IAM user names and Linux user names](#iam-user-names-and-linux-user-names) for further details.

docs/multiawsaccount.md

@@ -1,8 +1,15 @@
 {
-    "Version": "2012-10-17",
-    "Statement": {
-        "Effect": "Allow",
-        "Action": "sts:AssumeRole",
-        "Resource": "arn:aws:iam::<IAM ACCOUNT ID WITH IAM USERS>:role/<ROLE WITH IAM ACCESS>"
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "Stmt1471562879000",
+      "Effect": "Allow",
+      "Action": [
+        "sts:AssumeRole"
+      ],
+      "Resource": [
+        "arn:aws:iam::<YOUR_USERS_ACCOUNT_ID_HERE>:role/<YOUR_USERS_ACCOUNT_ROLE_NAME_HERE>"
+      ]
     }
+  ]
 }

iam_crossaccount_policy.json

@@ -20,7 +20,7 @@
         "iam:ListSSHPublicKeys"
       ],
       "Resource": [
-        "arn:aws:iam::<YOUR_ACCOUNT_ID_HERE>:user/*"
+        "arn:aws:iam::<YOUR_USERS_ACCOUNT_ID_HERE>:user/*"
       ]
     }
   ]

iam_ssh_policy.json

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/bin/bash -e
 
 # Which IAM groups have access to this instance
 # Comma seperated list of IAM groups. Leave empty for all available IAM users

import_users.sh

@@ -1,14 +1,12 @@
-#!/bin/bash
+#!/bin/bash -e
 
 tmpdir=$(mktemp -d)
 
-cd "${tmpdir}" || exit 1
+cd "$tmpdir"
 
-# yum install -y git # if necessary
-# or download a tarball and decompress it instead
 git clone https://github.com/widdix/aws-ec2-ssh.git
 
-cd "${tmpdir}/aws-ec2-ssh" || exit 1
+cd "$tmpdir/aws-ec2-ssh"
 
 cp authorized_keys_command.sh /opt/authorized_keys_command.sh
 cp import_users.sh /opt/import_users.sh
@@ -17,24 +15,24 @@ cp import_users.sh /opt/import_users.sh
 # changing GROUPNAMES to a comma seperated list of IAM groups you want to sync.
 # You can specify 1 or more groups, comma seperated, without spaces.
 # If you leave it blank, all IAM users will be synced.
-#sudo sed -i 's/IAM_AUTHORIZED_GROUPS=""/IAM_AUTHORIZED_GROUPS="GROUPNAMES"/' /opt/import_users.sh
+#sed -i 's/IAM_AUTHORIZED_GROUPS=""/IAM_AUTHORIZED_GROUPS="GROUPNAMES"/' /opt/import_users.sh
 
 # To control which users are given sudo privileges, uncomment the line below
 # changing GROUPNAME to either the name of the IAM group for sudo users, or
 # to ##ALL## to give all users sudo access. If you leave it blank, no users will
 # be given sudo access.
-#sudo sed -i 's/SUDOERSGROUP=""/SUDOERSGROUP="GROUPNAME"/' /opt/import_users.sh
+#sed -i 's/SUDOERSGROUP=""/SUDOERSGROUP="GROUPNAME"/' /opt/import_users.sh
 
 # To control which local groups a user will get, uncomment the line belong
 # changing GROUPNAMES to a comma seperated list of local UNIX groups.
 # If you live it blank, this setting will be ignored
-#sudo sed -i 's/LOCAL_GROUPS=""/LOCAL_GROUPS="GROUPNAMES"/' /opt/import_users.sh
+#sed -i 's/LOCAL_GROUPS=""/LOCAL_GROUPS="GROUPNAMES"/' /opt/import_users.sh
 
 # If your IAM users are in another AWS account, put the AssumeRole ARN here.
 # replace the word ASSUMEROLEARN with the full arn. eg 'arn:aws:iam::$accountid:role/$role'
 # See docs/multiawsaccount.md on how to make this work
-#sudo sed -i 's/ASSUMEROLE=""/ASSUMEROLE="ASSUMEROLEARN"/' /opt/import_users.sh
-#sudo sed -i 's/ASSUMEROLE=""/ASSUMEROLE="ASSUMEROLEARN"/' /opt/authorized_keys_command.sh
+#sed -i 's/ASSUMEROLE=""/ASSUMEROLE="ASSUMEROLEARN"/' /opt/import_users.sh
+#sed -i 's/ASSUMEROLE=""/ASSUMEROLE="ASSUMEROLEARN"/' /opt/authorized_keys_command.sh
 
 sed -i 's:#AuthorizedKeysCommand none:AuthorizedKeysCommand /opt/authorized_keys_command.sh:g' /etc/ssh/sshd_config
 sed -i 's:#AuthorizedKeysCommandUser nobody:AuthorizedKeysCommandUser nobody:g' /etc/ssh/sshd_config