|
| 1 | +--- |
| 2 | +title: "Authenticate with AWS using Leapp" |
| 3 | +description: "Learn how to use Leapp to supply AWS credentials to tools used within Geodesic." |
| 4 | +weight: 1 |
| 5 | +--- |
| 6 | +## Intro |
| 7 | + |
| 8 | +In this how-to, we will help you get started using Geodesic to work with AWS |
| 9 | +resources by helping you set up and use [Leapp](https://leapp.cloud) to handle |
| 10 | +credentials and authentication. Leapp is an open-source tool that makes this easier. |
| 11 | + |
| 12 | +## Prerequisites |
| 13 | + |
| 14 | +### SweetOps Know-how |
| 15 | + |
| 16 | +We expect you've gone through the tutorial on ["Getting started with Geodesic"]({{< relref "tutorials/geodesic-getting-started.md" >}}) prior to this How-To since that contains some important understanding of what Geodesic is, how it works, and what it's doing. |
| 17 | + |
| 18 | +### AWS Region and Credentials |
| 19 | + |
| 20 | +#### Region |
| 21 | + |
| 22 | +It will be helpful to know which AWS Region you will be primarily working in. |
| 23 | +This should be fairly common knowledge among people with AWS access at your |
| 24 | +company. If you are doing this on your own, choose the region closest to |
| 25 | +you geographically. If you are still in doubt, pick |
| 26 | +- `ca-central-1` if in Canada, |
| 27 | +- `us-east-2` if in the United States east of the Mississippi, |
| 28 | +- `us-west-2` if anywhere else in the North America or anywhere in Central America, |
| 29 | +- `sa-east-1` if in South America, |
| 30 | +- `eu-north-1` if in Europe, |
| 31 | +- `af-south-1` if in Africa, |
| 32 | +- `ap-south-1` if in Asia, or |
| 33 | +- `ap-southeast-2` if in Australia or Antarctica. |
| 34 | + |
| 35 | +#### Credentials |
| 36 | + |
| 37 | +You will have to have some way of authenticating to AWS already set up, and you |
| 38 | +need to know the nature of your credentials. Whoever gave you access to AWS |
| 39 | +should be able to tell you what kind of access you have. It should be one of the following: |
| 40 | + |
| 41 | +- **Federated Role** (recommended). This means you log into something you use to |
| 42 | +identify yourself to a lot of places (usually refered to as Single Sign-On |
| 43 | +or SSO), and it is set up to log you into AWS with a specific IAM Role as well. |
| 44 | +At a company, this is usually Google Workspaces (formerly GSuite), |
| 45 | +Okta, or Active Directory. This is also known as a SAML IdP. |
| 46 | +- **AWS SSO**. This means your company has configured AWS as a Single Sign-On |
| 47 | +provider. This is AWS _as_ a Single Sign-On provider, allowing you to access |
| 48 | +multiple _permission sets_ within AWS, not using some |
| 49 | +other Single Sign-On provider to sign in to AWS as a single IAM Role. |
| 50 | +Please note that even if your company has set up AWS _as_ a Single Sign-On provider, you still may be using your company's primary SSO provider to authenticate to AWS SSO. |
| 51 | +- **AWS IAM User**. This is the older way of authenticating to AWS, with a basic |
| 52 | +username and password to log into the AWS console, |
| 53 | +and a long-lived "Access Key" for API access. If you are going to use this |
| 54 | +method, we strongly recommend that you enable multi-factor authentication (MFA). |
| 55 | + |
| 56 | +Based on which kind of credentials you have, you will need to gather different |
| 57 | +information with which to configure Leapp. Whoever is in charge of setting up |
| 58 | +your access to AWS should be able to give you the information you need. |
| 59 | + |
| 60 | +##### Federated Role |
| 61 | + |
| 62 | +If using Federated Login, you will need |
| 63 | +- Your IdP Single Sign-On URL. |
| 64 | + - For Google Workspaces, it looks something like |
| 65 | + `https://accounts.google.com/o/saml2/initsso?idpid=C0asdfasdfal&spid=12344321`. |
| 66 | + - For Okta, it looks something like `https://company.okta.com/app/company_samlidp_1/Hka1abcke6h4P1WQr5d7/sso/saml`. |
| 67 | + - Most importantly,it should not be confused with the AWS Single Sign-On URLs |
| 68 | + like these (**do not use these**) |
| 69 | + - `https://signin.aws.amazon.com/saml` (this is used by your IdP admin) |
| 70 | + - `https://my-sso-portal.awsapps.com/start` (this means you are using AWS SSO) |
| 71 | +- The AWS Identity Provider ARN assigned by AWS to your IdP. Something like |
| 72 | + - `arn:aws:iam::123434211234:saml-provider/company-name` |
| 73 | +- Your assigned/authorized AWS IAM Role ARN. Something like |
| 74 | + - `arn:aws:iam::123434211234:role/role-name` |
| 75 | + |
| 76 | +##### AWS SSO |
| 77 | + |
| 78 | +If using AWS SSO, you will need: |
| 79 | + |
| 80 | +- Your AWS SSO "start URL", also known as your "portal URL". It should be |
| 81 | +very close to: |
| 82 | + - `https://something.awsapps.com/start` |
| 83 | +- The region in which AWS SSO has been deployed. This may or may not be the same |
| 84 | +region you will be working in. |
| 85 | + |
| 86 | +##### AWS IAM User |
| 87 | + |
| 88 | +If you are a regular IAM User who can log into the AWS Console, you should |
| 89 | +log into the AWS Console while setting up Leapp. Choose "My Security Credentials" |
| 90 | +from the Account drop-down menu: |
| 91 | +- Copy and paste your MFA ARN or Serial Number from "Assigned MFA device" |
| 92 | +- Click on "Create access key" to create a new access key and copy the |
| 93 | +Access Key ID and Secret Access Key from the console and paste directly into |
| 94 | +the appropriate fields in Leapp. |
| 95 | + |
| 96 | +## How-To |
| 97 | + |
| 98 | +### Start Geodesic |
| 99 | + |
| 100 | +If you are a Cloud Posse client, you will have a customized version of Geodesic |
| 101 | +that sets an initial value for the environment variable `AWS_PROFILE`. Alternatively, |
| 102 | +you may have customized it yourself, or you may want to. In any case, we will |
| 103 | +go with what you have. So start Geodesic, and at the command prompt, type |
| 104 | + |
| 105 | +```bash |
| 106 | +echo $AWS_PROFILE |
| 107 | +``` |
| 108 | + |
| 109 | +This is the value you will give to the profile in Leapp when you configure it. |
| 110 | +If the output of `echo` is blank, as would be expected if you are running |
| 111 | +our public tutorial image, use "default" for the profile name. |
| 112 | + |
| 113 | +### Install and Configure Leapp |
| 114 | + |
| 115 | +Please refer to the official Leapp documentation |
| 116 | +for the latest instructions on installing and configuring Leapp. |
| 117 | +Now that you are armed with the information from |
| 118 | +the previous steps, it should be pretty easy. |
| 119 | + |
| 120 | +- Visit the [Leapp website](https://leapp.cloud) |
| 121 | +- Download and install Leapp as instructed by the website |
| 122 | +- Follow the instructions (under "Docs") for configuring AWS |
| 123 | + |
| 124 | +Below is some guidance to the Leapp documentation that applies as of the |
| 125 | +time of this writing. By the time you read this it may be out of date, but |
| 126 | +hopefully will still be of help in guiding you through the Leapp site. |
| 127 | + |
| 128 | +##### Key Points |
| 129 | + |
| 130 | +- The "AWS Profile" setting in Leapp must match _exactly_ the value of |
| 131 | +`$AWS_PROFILE` you found in Geodesic in the earlier step. |
| 132 | +- The "AWS Region" you set in the Leapp session should be the AWS Region you |
| 133 | +most often use, as discussed [above](#aws-region-and-credentials). |
| 134 | +- The "Session Alias" is completely up to you: it is the name for this |
| 135 | +set of credentials that you will see in the UI. |
| 136 | + |
| 137 | +The Leapp documentation is at [https://docs.leapp.cloud/](https://docs.leapp.cloud/) |
| 138 | +and the best set of instructions to follow are the ones under a sub-menu on the left |
| 139 | +side of the page: **Tutorials > AWS** |
| 140 | + |
| 141 | +- If you have a **Federated Login**, pick "AWS IAM Federated Role". Most of the |
| 142 | +tutorial is about how to configure Federated Login itself, and you can skip |
| 143 | +all that. Just follow the last step: "Setup in Leapp". |
| 144 | +- Otherwise, pick "AWS SSO" or "AWS IAM User" and follow the steps. |
| 145 | + |
| 146 | + |
| 147 | +### Log in using Leapp |
| 148 | + |
| 149 | +Leapp provides 2 UIs for logging into or out of a session. There is a system-wide menu item |
| 150 | +in the taskbar on Windows systems or as a "status menu" on the Mac menu bar. Click on it |
| 151 | +and a menu will appear with all your configured session names and their corresponding |
| 152 | +profile names. An icon for each session will appear either in gray if logged out |
| 153 | +or orange if logged in (at least those are the current defaults for the "Light" color |
| 154 | +scheme on macOS). Just select the menu item to toggle the state. |
| 155 | + |
| 156 | +Alternately, you can select "Show" from the menu and be shown a richer UI where |
| 157 | +you can do more, but still the main thing is that you click on a session name |
| 158 | +to change its state and the indicator shows gray for logged out and orange for logged in. |
| 159 | + |
| 160 | +If you are not using IAM user access keys then in order to access AWS you will have |
| 161 | +to log in to your "identity provider" (e.g. Okta, Google) like you do for access |
| 162 | +to other resources. Therefore, when you try to activate a session in Leapp, |
| 163 | +it may open a small web browser window popup or open a window or tab in your |
| 164 | +default browser so you can complete the login flow, including supplying |
| 165 | +a second factor if you are using MFA, and perhaps solving a CAPTCHA puzzle. This |
| 166 | +is normal and expected behavior, not a virus or hacking attempt. When you finish |
| 167 | +logging in via the web browser, Leapp uses the credentials provided by your |
| 168 | +identity provider to authenticate to AWS, just as if you were logging into |
| 169 | +the AWS web console or SSO portal. |
| 170 | + |
| 171 | +Like your web browser, Leapp can store cookies and other information, and |
| 172 | +in addition, Leapp is able to use your system keychain for secure |
| 173 | +storage of other things like your Secret Access Key. Because of this, |
| 174 | +and depending on your identity provider and their settings, simply being |
| 175 | +logged into your computer may be enough authentication for Leapp to grant |
| 176 | +you access when you enable a session without asking you for anything. |
| 177 | +However, AWS requires periodic refreshing of session keys and if you are |
| 178 | +using MFA with AWS, you should enable Leapp notifications |
| 179 | +so you can receive prompts when your AWS session expires and |
| 180 | +Leapp needs a new MFA token in order to start a new session for you. |
| 181 | + |
| 182 | +### It should just work |
| 183 | + |
| 184 | +Once you log in to AWS using Leapp, go back into Geodesic and simply hit return |
| 185 | +at the prompt. The prompt should change from having a red ✗ and `[none]` to |
| 186 | +having a green √ and `[default]` or whatever your profile name is. This is |
| 187 | +Geodesic's way of letting you know you are authorized with AWS, and what |
| 188 | +profile you have active. |
| 189 | + |
| 190 | +You can always confirm your current authentication status by running: |
| 191 | + |
| 192 | +```bash |
| 193 | +aws sts get-caller-identity |
| 194 | +``` |
| 195 | + |
| 196 | +When you are properly authenticated, it will output your IAM role and other |
| 197 | +information. When you are logged out, it will print some kind of error message, |
| 198 | +usually: |
| 199 | +```text |
| 200 | +Unable to locate credentials. You can configure credentials by running "aws configure". |
| 201 | +``` |
0 commit comments