Implement RefArch Access / Set up AWS Auth

_docs-sources/products.md

@@ -16,27 +16,21 @@ import CenterLayout from "/src/components/CenterLayout"
 <Card
   title="Infrastructure as Code Library"
   href="/iac/overview/">
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Purus gravida quis blandit turpis cursus.
+A collection of reusable code that enables you to deploy and manage infrastructure quickly and reliably.
 </Card>
 <Card
   title="Reference Architecture"
   href="/refarch/whats-this/what-is-a-reference-architecture">
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Purus gravida quis blandit turpis cursus.</Card>
+An end-to-end tech stack built using best practices on top of our Infrastructure as Code Library, deployed into your AWS accounts.</Card>
 <Card
   title="Pipelines"
   href="/pipelines/overview">
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Purus gravida quis blandit turpis cursus.
+A framework for running secure deployments for infrastructure code and application code.
 </Card>
 <Card
 title="Developer Portal"
 href="/developer-portal/create-account">
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Purus gravida quis blandit turpis cursus.
-</Card>
-<Card
-title="CIS"
-href="https://github.com/gruntwork-io/repo-copier"
-tags={["with cis subscription"]}>
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Purus gravida quis blandit turpis cursus.
+Gain access to all resources included in your Gruntwork subscription.
 </Card>
 
 </CardGroup>

_docs-sources/refarch/access/how-to-auth-CLI/index.md

@@ -0,0 +1,55 @@
+# Authenticate via the AWS command line interface (CLI)
+
+CLI access requires [AWS access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). We recommend using [aws-vault](https://github.com/99designs/aws-vault) for managing all aspects related to CLI authentication. To use `aws-vault` you will need to generate AWS Access Keys for your IAM user in the security account.
+
+:::tip
+
+`aws-vault` is not the only method which can be used to authenticate on the CLI. Please refer to [A Comprehensive Guide to Authenticating to AWS on the Command Line](https://blog.gruntwork.io/a-comprehensive-guide-to-authenticating-to-aws-on-the-command-line-63656a686799) for several other options.
+
+:::
+
+:::info
+
+MFA is required for the Reference Architecture, including on the CLI. See [configuring your IAM user](/refarch/access/setup-auth/#configure-your-iam-user) for instructions on setting up an MFA token.
+
+:::
+
+## Access resources in the security account
+
+To authenticate to the security account, you only need your AWS access keys and an MFA token. See [the guide](https://github.com/99designs/aws-vault#quick-start) on adding credentials to `aws-vault`.
+
+You should be able to run the following command using AWS CLI
+
+```bash
+aws-vault exec <YOUR_SECURITY_ACCOUNT_PROFILE_NAME> -- aws sts get-caller-identity
+```
+
+and expect to get an output with your user's IAM role:
+
+```json
+{
+    "UserId": "AIDAXXXXXXXXXXXX”,
+    "Account": “<YOUR_ACCOUNT_ID>",
+    "Arn": "arn:aws:iam::<YOUR_ACCOUNT_ID>:user/<your_iam_user_name>"
+}
+```
+
+## Accessing all other accounts
+
+To authenticate to all other accounts (e.g., dev, stage, prod), you will need the ARN of an IAM Role in that account to assume. To configure accessing accounts using assumed roles with `aws-vault` refer to [these instructions](https://github.com/99designs/aws-vault#roles-and-mfa).
+
+Given the following command (where `YOUR_ACCOUNT_PROFILE_NAME` will be any account other than your security account)
+
+```bash
+aws-vault exec <YOUR_ACCOUNT_PROFILE_NAME> -- aws sts get-caller-identity
+```
+
+you should expect to see the following output:
+
+```json
+{
+  "UserId": "AIDAXXXXXXXXXXXX",
+  "Account": "<YOUR_ACCOUNT_ID>",
+  "Arn": "arn:aws:sts::<YOUR_ACCOUNT_ID>:assumed-role/<assumed_role_name>/11111111111111111111"
+}
+```

_docs-sources/refarch/access/how-to-auth-aws-web-console/index.md

@@ -0,0 +1,26 @@
+# Authenticating to the AWS web console
+
+## Authenticate to the AWS Web Console in the security account
+
+To authenticate to the security account, you will need:
+
+1. IAM User Credentials. See [setting up initial access](/refarch/access/setup-auth/) for how to create IAM users.
+1. An MFA Token. See [Configuring your IAM user](/refarch/access/setup-auth/#configure-your-iam-user).
+1. The login URL. This should be of the format `https://<YOUR_ACCOUNT_ID>.signin.aws.amazon.com/console`.
+
+## Authenticate to the AWS Web Console in all other accounts
+
+To authenticate to any other account (e.g., dev, stage, prod), you need to:
+
+1. Authenticate to the security account. All IAM users are defined in this account, you must always authenticate to it first.
+1. [Assume an IAM Role in the other AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html). To access other accounts, you switch to an IAM Role defined in that account.
+
+:::note
+Note that to be able to access an IAM Role in some account, your IAM User must be in an IAM Group that has permissions to assume that IAM Role.
+:::
+
+See the `cross-account-iam-roles` module for the [default set of IAM Roles](https://github.com/gruntwork-io/terraform-aws-security/blob/main/modules/cross-account-iam-roles/README.md#iam-roles-intended-for-human-users) that exist in each account. For example, to assume the allow-read-only-access-from-other-accounts IAM Role in the prod account, you must be in the \_account.prod-read-only IAM Group. See [Configure other IAM Users](/refarch/access/setup-auth/#configure-other-iam-users) for how you add users to IAM Groups.
+
+:::note
+Not all of the default roles referenced in the `cross-account-iam-roles` module are deployed in each account.
+:::

_docs-sources/refarch/access/how-to-auth-ec2/index.md

@@ -1,9 +1,63 @@
-# SSH to an EC2 Instance
+# SSH to EC2 Instances
 
+You can SSH to any of your EC2 Instances in the Reference Architecture in two different ways:
 
-Haxx0r ipsum foo Trojan horse new all your base are belong to us ip error private shell fopen semaphore epoch char packet sniffer segfault gurfle bypass. Memory leak bubble sort injection leet malloc brute force double xss mega sudo mountain dew void echo win emacs linux piggyback bin. I'm compiling float bang case cat infinite loop Donald Knuth unix for /dev/null machine code then chown d00dz worm gnu crack packet bar eof while.
+1. `ssh-grunt` (Recommended)
+1. EC2 Key Pairs (For emergency / backup use only)
 
-Lib void brute force bypass nak concurrently all your base are belong to us break leapfrog bit default packet sniffer Linus Torvalds. Man pages packet stack trace Starcraft Donald Knuth pwned worm hello world public giga frack gurfle. Irc fork malloc fopen script kiddies flood blob fail hexadecimal while access semaphore loop mega Trojan horse foo gobble.
+## `ssh-grunt` (Recommended)
 
-Bang spoof *.* headers Dennis Ritchie pragma bubble sort mutex d00dz firewall wombat snarf. Win L0phtCrack back door big-endian tera injection flush suitably small values interpreter class hello world client segfault. Boolean buffer emacs highjack concurrently boolean I'm compiling malloc finally char protected void fopen ascii var cd Trojan horse public.
+[`ssh-grunt`](../../../reference/modules/terraform-aws-security/ssh-grunt/) is a tool developed by Gruntwork that automatically syncs user accounts from AWS IAM to your servers to allow individual developers to SSH onto EC2 instances using their own username and SSH keys.
 
+In this section, you will learn how to SSH to an EC2 instance in your Reference Architecture using `ssh-grunt`. Every EC2 instance has `ssh-grunt` installed by default.
+
+### Add users to SSH IAM Groups
+
+When running `ssh-grunt`, each EC2 instance specifies from which IAM Groups it will allow SSH access, and SSH access with sudo permissions. By default, these IAM Group names are `ssh-grunt-users` and `ssh-grunt-sudo-users`, respectively. To be able to SSH to an EC2 instance, your IAM User must be added to one of these IAM Groups (see Configure other IAM Users for instructions).
+
+### Upload your public SSH key
+
+1. Authenticate to the AWS Web Console in the security account.
+1. Go to your IAM User profile page, select the "Security credentials" tab, and click "Upload SSH public key".
+1. Upload your public SSH key (e.g. `~/.ssh/id_rsa.pub`). Do NOT upload your private key.
+
+### Determine your SSH username
+
+Your username for SSH is typically the same as your IAM User name. However, if your IAM User name has special characters that are not allowed by operating systems (e.g., most punctuation is not allowed), your SSH username may be a bit different, as specified in the `ssh-grunt` [documentation](../../../reference/modules/terraform-aws-security/ssh-grunt/). For example:
+
+1. If your IAM User name is `jane`, your SSH username will also be `jane`.
+1. If your IAM User name is `jane@example.com`, your SSH username will be `jane`.
+1. If your IAM User name is `_example.jane.doe`, your SSH username will be `example_jane_doe`.
+
+
+### SSH to an EC2 instance
+
+Since most EC2 instances in the Reference Architecture are deployed into private subnets, you won't be able to access them over the public Internet. Therefore, you must first connect to the VPN server. See [VPN Authentication](../how-to-auth-vpn/index.md) for more details.
+
+Given that:
+
+1.  Your IAM User name is jane.
+1.  You've uploaded your public SSH key to your IAM User profile.
+1.  Your private key is located at `/Users/jane/.ssh/id_rsa` on your local machine.
+1.  Your EC2 Instance's IP address is 1.2.3.4.
+
+
+First, add your SSH Key into the SSH Agent using the following command:
+
+```bash
+ssh-add /Users/jane/.ssh/id_rsa
+```
+
+Then, use this command to SSH to the EC2 Instance:
+
+```bash
+ssh jane@1.2.3.4
+```
+
+You should now be able to execute commands on the instance.
+
+## EC2 Key Pairs (For emergency / backup use only)
+
+When you launch an EC2 Instance in AWS, you can specify an EC2 Key Pair that can be used to SSH into the EC2 Instance. This suffers from an important problem: usually more than one person needs access to the EC2 Instance, which means you have to share this key with others. Sharing secrets of this sort is a security risk. Moreover, if someone leaves the company, to ensure they no longer have access, you'd have to change the Key Pair, which requires redeploying all of your servers.
+
+As part of the Reference Architecture deployment, Gruntwork will create EC2 Key Pairs and put the private keys into AWS Secrets Manager. These keys are there only for emergency / backup use: e.g., if there's a bug in `ssh-grunt` that prevents you from accessing your EC2 instances. We recommend only giving a handful of trusted admins access to these Key Pairs.