Merge pull request #271 from ResearchComputing/CFS-651_aws_cilogon

Cfs 651 aws cilogon

docs/cloud/aws/getting-started/aws-console-access.md

@@ -1,8 +1,9 @@
 ## Accessing the AWS Management Console
 
-### Prerequisite
+### Prerequisites
+1. You are a member of CUBoulder. If you have access to CUBoulder AWS resources and are from another institution, please see <a href="./aws-console-access-non-cu-boulder.md" target="_blank">this guide</a> on signing in using your institution's credentials.
 
-The <a href="https://oit.colorado.edu/services/identity-access-management/multi-factor-remote-access" target="_blank">DUO Multi-Factor Remote Access</a> (MFA) app is installed and enrolled.
+2. The <a href="https://oit.colorado.edu/services/identity-access-management/multi-factor-remote-access" target="_blank">DUO Multi-Factor Remote Access</a> (MFA) app is installed and enrolled.
 Visit OIT's <a href="https://oit.colorado.edu/services/identity-access-management/multi-factor-remote-access" target="_blank">DUO Multi-Factor Remote Access</a> documentation to install and enroll MFA.
 
 ### Single Sign-On

docs/cloud/aws/getting-started/index.rst

@@ -2,11 +2,18 @@ AWS - Getting Started
 ===============
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :caption: Getting Started Documentation
 
     aws-console-access
     aws-cli-saml2aws
+    non-cu-boulder/index
     customer-permission-boundary
     managing-grouper-groups
     customer-support
+
+.. toctree::
+    :maxdepth: 1
+    .. :caption: Getting Started Non-CU Boulder
+    non-cu-boulder/index
+

docs/cloud/aws/getting-started/non-cu-boulder/aws-cli-saml2aws-non-cu-boulder.md

@@ -0,0 +1,183 @@
+## Accessing the AWS CLI Using saml2aws (Non-CU Boulder)
+
+The **saml2aws** CLI tool is used to login and retrieve AWS temporary credentials.
+
+### Prerequisites
+
+1. This guide is only relevant if you are not a member of CU Boulder and require access to manage AWS resources owned by CU Boulder. If you are a member of CU Boulder, please see <a href="./aws-console-access.md" target="_blank">this guide</a> on signing in using your IdentiKey.
+
+2. You have a chromium based browser installed on your PC.
+
+### Install saml2aws
+
+To install **saml2aws** (MacOS, Windows, Linux), visit the online documentation: <a href="https://github.com/Versent/saml2aws#install" target="_blank">saml2aws installation instructions</a>
+
+Verify **saml2aws** is installed by running the following command (output should show the installed version):
+
+`$ saml2aws --version`
+
+### Configure saml2aws
+
+Run the following command to begin the configuration process.
+This only needs to be done one time:
+
+`$ saml2aws configure`
+
+Provide the following values for the configuration:
+
+```buildoutcfg
+Provider:    Browser
+AWS Profile: saml (default, just hit the enter key)
+URL:         https://federation-proxy.rmacc.org/aws
+Username:    leave blank (just hit the enter key)
+Password:    leave blank (just hit the enter key)
+```
+
+Example configuration input:
+
+```
+? Please choose a provider: Browser
+? AWS Profile: (default, hit enter key)
+? URL: https://federation-proxy.rmacc.org/aws
+? Username:
+? Password:
+```
+
+Example configuration output:
+
+```
+account {
+  URL: https://federation-proxy.rmacc.org/aws
+  Username: 
+  Provider: Browser
+  MFA: Auto
+  SkipVerify: false
+  AmazonWebservicesURN: urn:amazon:webservices
+  SessionDuration: 3600
+  Profile: saml
+  RoleARN: 
+  Region: 
+}
+```
+### Using saml2aws
+
+Using **saml2aws** involves logging in first using the `saml2aws login` command. Once logged in, you can then execute AWS CLI commands using the `saml2aws exec` command. You can also establish an interactive shell to run your commands in. Both methods are described below.
+
+#### saml2aws login
+
+Log in using the following command:
+
+`$ saml2aws login`
+
+**Note**: When logging in for the first time, you will need to add the `--download-browser-driver` flag which will download drivers for chromium based browsers, allowing the login page to pop-up in browser. The full command is as follows:
+`$ saml2aws login --download-browser-driver`
+
+When prompted for the Username and Password, just hit the ENTER key to accept the defaults you configured earlier. A browser window like the one shown below should pop up.
+
+![](images/aws-cli-saml2aws-non-cu-boulder/cilogon-logon.png)
+
+Select your institution from the drop down menu and click "Log On".
+
+![](images/aws-cli-saml2aws-non-cu-boulder/cilogon-selection.png)
+
+Log in using your regular institution credentials. You may be asked to authenticate with MFA.
+
+![](images/aws-cli-saml2aws-non-cu-boulder/denver-anschutz-sso.png)
+
+If you only have access to a single AWS Account and a single Role, you will be immediatly authenticated with SAML.
+
+If you have access to multiple AWS Accounts and/or Roles, you will be presented with a list of Accounts/Roles to select.  Select the Account and Role you wish to log in to.
+![](images/aws-cli-saml2aws-non-cu-boulder/select-role.png)
+
+Your browser window should then close and your terminal should have a similar output to the following
+
+```
+Selected role: arn:aws:iam::XXXXXXXXXXXX:role/Shibboleth-Customer-Admin
+Requesting AWS credentials using SAML assertion
+Logged in as: arn:aws:sts::XXXXXXXXXXXX:assumed-role/Shibboleth-Customer-Admin/ralphie@colorado.edu
+
+Your new access key pair has been stored in the AWS configuration
+Note that it will expire at 2022-04-21 23:10:34 -0600 MDT
+To use this credential, call the AWS CLI with the --profile option (e.g. aws --profile saml ec2 describe-instances).
+```
+
+AWS CLI commands can be executed by using the format:
+
+`aws --profile saml <aws subcommands here>`
+
+Let's test your login from above by running your first AWS CLI command.
+
+`$ aws --profile saml sts get-caller-identity`
+
+You should see output similar to the following:
+
+```
+$ aws --profile saml sts get-caller-identity
+{
+    "UserId": "XXXXXXXXXXXXXXXXXXXXX:ralphie@colorado.edu",
+    "Account": "XXXXXXXXXXXX",
+    "Arn": "arn:aws:sts::XXXXXXXXXXXX:assumed-role/Shibboleth-Customer-Admin/ralphie@colorado.edu"
+}
+```
+
+
+
+#### saml2aws exec
+
+You can use `saml2aws exec` to run a command using the login credentials from the `saml2aws login` command from above.
+AWS CLI commands can be executed by using the format:
+
+`saml2aws exec aws <aws subcommands here>`
+
+Run the following command, which is equivalent to the command you ran above.
+You should get the same output:
+
+`$ saml2aws exec aws sts get-caller-identity`
+
+#### saml2aws shell
+
+Most times, users will want to establish a shell to type AWS CLI commands in to without the extra hassle of providing a profile or prepending with the saml2aws exec command.
+Here's how it's done:
+
+`$ saml2aws exec -- $SHELL`
+
+Now try the following AWS CLI command:
+
+`$ aws sts get-caller-identity`
+
+You should see the same output from earlier.
+Now you can run all the AWS CLI commands you want, or run a shell script.
+All AWS CLI commands will run under the saml2aws login credentials from earlier.
+
+### saml2aws Advanced Configuration
+
+You can manually add profiles for each AWS Account/Role.
+This is particularly helpful for automating **saml2aws** commands non-interactively.
+Profiles are added by editing the %HOME_DIR%/.saml2aws file (ie. ~/.saml2aws).
+Profiles can be added using the following template:
+* substitute <account_alias> for the AWS Alias
+* substitute XXXXXXXXXXXX for the AWS Account Number
+
+```
+[admin-<account_alias>]
+url                  = https://federation-proxy.rmacc.org/aws
+provider             = Browser
+mfa                  = auto
+skip_verify          = false
+timeout              = 0
+aws_urn              = urn:amazon:webservices
+aws_session_duration = 3600
+aws_profile          = <account_alias>
+```
+
+Example command for establishing an interactive shell in a single command.
+Note that you will have to manually accept the MFA request.
+
+```shell
+$ saml2aws -a admin-<account_alias> login --skip-prompt --duo-mfa-option="Duo Push" --session-duration=3600 && saml2aws -a admin-<account_alias> exec -- $SHELL
+```
+
+You can run the `saml2aws exec` portion of the above command however you need.
+For example, you can execute a shell script.
+Again, MFA will need to be performed manually.
+

docs/cloud/aws/getting-started/non-cu-boulder/aws-console-access-non-cu-boulder.md

@@ -0,0 +1,22 @@
+## Accessing the AWS Management Console with CILogon (Non-CU Boulder)
+
+### Prerequisites
+This guide is only relevant if you are not a member of CU Boulder and require access to manage AWS resources owned by CU Boulder. If you are a member of CU Boulder, please see <a href="./aws-console-access.md" target="_blank">this guide</a> on signing in using your IdentiKey.
+
+### CILogon
+
+Users access the <a href="https://federation-proxy.rmacc.org/aws" target="_blank">CILogon page</a> and log in using their campus credentials. They will then need to select the account with which they wish to log in if they have access to more than one account, otherwise they will be redirected to the AWS management console 
+
+1. Launch <a href="https://federation-proxy.rmacc.org/aws" target="_blank">CILogon</a>.
+2. Select your institution from the drop-down list
+![](images/aws-console-access-non-cu-boulder/cilogon-selection.png)
+3. Tick "Remember this selection" and click Log On.
+![](images/aws-console-access-non-cu-boulder/cilogon-logon.png)
+4. You will be redirected to your institution's sign in page. Log in using your credentials - you may also be asked to authenticate using MFA.
+![](images/aws-console-access-non-cu-boulder/denver-anschutz-sso.png)
+5. If you only have access to a single AWS Account and a single Role, you will be logged straight in to the AWS Console.
+If you have access to multiple AWS Accounts and/or Roles, you will be presented with a list of Accounts/Roles to select.  Select the Account and Role you wish to log in to.
+![](images/aws-console-access-non-cu-boulder/select-role.png)
+6. You will be logged in to the AWS Management Console.  Always be sure to verify you have the AWS Region you are working with selected after logging in.
+![](images/aws-console-access-non-cu-boulder/select-region.png)
+Once logged in, you have a 60 minute session.  You will be asked to log back in and re-authenticate when your session expires.

docs/cloud/aws/getting-started/non-cu-boulder/index.rst

@@ -0,0 +1,10 @@
+AWS - Getting Started (Non-CU Boulder)
+===============
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Getting Started Non-CU Boulder
+
+    aws-console-access-non-cu-boulder
+    aws-cli-saml2aws-non-cu-boulder
+