Authenticate with AWS using Leapp
Learn how to use Leapp to supply AWS credentials to tools used within Geodesic.
In this how-to, we will help you get started using Geodesic to work with AWS resources by helping you set up and use Leapp to handle credentials and authentication. Leapp is an open-source tool that makes this easier.
We expect you’ve gone through the tutorial on “Getting started with Geodesic” prior to this How-To since that contains some important understanding of what Geodesic is, how it works, and what it’s doing.
AWS Region and Credentials
It will be helpful to know which AWS Region you will be primarily working in. This should be fairly common knowledge among people with AWS access at your company. If you are doing this on your own, choose the region closest to you geographically. If you are still in doubt, pick
ca-central-1if in Canada,
us-east-2if in the United States east of the Mississippi,
us-west-2if anywhere else in the North America or anywhere in Central America,
sa-east-1if in South America,
eu-north-1if in Europe,
af-south-1if in Africa,
ap-south-1if in Asia, or
ap-southeast-2if in Australia or Antarctica.
You will have to have some way of authenticating to AWS already set up, and you need to know the nature of your credentials. Whoever gave you access to AWS should be able to tell you what kind of access you have. It should be one of the following:
- Federated Role (recommended). This means you log into something you use to identify yourself to a lot of places (usually refered to as Single Sign-On or SSO), and it is set up to log you into AWS with a specific IAM Role as well. At a company, this is usually Google Workspaces (formerly GSuite), Okta, or Active Directory. This is also known as a SAML IdP.
- AWS SSO. This means your company has configured AWS as a Single Sign-On provider. This is AWS as a Single Sign-On provider, allowing you to access multiple permission sets within AWS, not using some other Single Sign-On provider to sign in to AWS as a single IAM Role. 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.
- AWS IAM User. This is the older way of authenticating to AWS, with a basic username and password to log into the AWS console, and a long-lived “Access Key” for API access. If you are going to use this method, we strongly recommend that you enable multi-factor authentication (MFA).
Based on which kind of credentials you have, you will need to gather different information with which to configure Leapp. Whoever is in charge of setting up your access to AWS should be able to give you the information you need.
If using Federated Login, you will need
- Your IdP Single Sign-On URL.
- For Google Workspaces, it looks something like
- For Okta, it looks something like
- Most importantly,it should not be confused with the AWS Single Sign-On URLs
like these (do not use these)
https://signin.aws.amazon.com/saml(this is used by your IdP admin)
https://my-sso-portal.awsapps.com/start(this means you are using AWS SSO)
- For Google Workspaces, it looks something like
- The AWS Identity Provider ARN assigned by AWS to your IdP. Something like
- Your assigned/authorized AWS IAM Role ARN. Something like
If using AWS SSO, you will need:
- Your AWS SSO “start URL”, also known as your “portal URL”. It should be
very close to:
- The region in which AWS SSO has been deployed. This may or may not be the same region you will be working in.
AWS IAM User
If you are a regular IAM User who can log into the AWS Console, you should log into the AWS Console while setting up Leapp. Choose “My Security Credentials” from the Account drop-down menu:
- Copy and paste your MFA ARN or Serial Number from “Assigned MFA device”
- Click on “Create access key” to create a new access key and copy the Access Key ID and Secret Access Key from the console and paste directly into the appropriate fields in Leapp.
If you are a Cloud Posse client, you will have a customized version of Geodesic
that sets an initial value for the environment variable
you may have customized it yourself, or you may want to. In any case, we will
go with what you have. So start Geodesic, and at the command prompt, type
This is the value you will give to the profile in Leapp when you configure it.
If the output of
echo is blank, as would be expected if you are running
our public tutorial image, use “default” for the profile name.
Install and Configure Leapp
Please refer to the official Leapp documentation for the latest instructions on installing and configuring Leapp. Now that you are armed with the information from the previous steps, it should be pretty easy.
- Visit the Leapp website
- Download and install Leapp as instructed by the website
- Follow the instructions (under “Docs”) for configuring AWS
Below is some guidance to the Leapp documentation that applies as of the time of this writing. By the time you read this it may be out of date, but hopefully will still be of help in guiding you through the Leapp site.
- The “AWS Profile” setting in Leapp must match exactly the value of
$AWS_PROFILEyou found in Geodesic in the earlier step.
- The “AWS Region” you set in the Leapp session should be the AWS Region you most often use, as discussed above.
- The “Session Alias” is completely up to you: it is the name for this set of credentials that you will see in the UI.
The Leapp documentation is at https://docs.leapp.cloud/ and the best set of instructions to follow are the ones under a sub-menu on the left side of the page: Tutorials > AWS
- If you have a Federated Login, pick “AWS IAM Federated Role”. Most of the tutorial is about how to configure Federated Login itself, and you can skip all that. Just follow the last step: “Setup in Leapp”.
- Otherwise, pick “AWS SSO” or “AWS IAM User” and follow the steps.
Log in using Leapp
Leapp provides 2 UIs for logging into or out of a session. There is a system-wide menu item in the taskbar on Windows systems or as a “status menu” on the Mac menu bar. Click on it and a menu will appear with all your configured session names and their corresponding profile names. An icon for each session will appear either in gray if logged out or orange if logged in (at least those are the current defaults for the “Light” color scheme on macOS). Just select the menu item to toggle the state.
Alternately, you can select “Show” from the menu and be shown a richer UI where you can do more, but still the main thing is that you click on a session name to change its state and the indicator shows gray for logged out and orange for logged in.
If you are not using IAM user access keys then in order to access AWS you will have to log in to your “identity provider” (e.g. Okta, Google) like you do for access to other resources. Therefore, when you try to activate a session in Leapp, it may open a small web browser window popup or open a window or tab in your default browser so you can complete the login flow, including supplying a second factor if you are using MFA, and perhaps solving a CAPTCHA puzzle. This is normal and expected behavior, not a virus or hacking attempt. When you finish logging in via the web browser, Leapp uses the credentials provided by your identity provider to authenticate to AWS, just as if you were logging into the AWS web console or SSO portal.
Like your web browser, Leapp can store cookies and other information, and in addition, Leapp is able to use your system keychain for secure storage of other things like your Secret Access Key. Because of this, and depending on your identity provider and their settings, simply being logged into your computer may be enough authentication for Leapp to grant you access when you enable a session without asking you for anything. However, AWS requires periodic refreshing of session keys and if you are using MFA with AWS, you should enable Leapp notifications so you can receive prompts when your AWS session expires and Leapp needs a new MFA token in order to start a new session for you.
It should just work
Once you log in to AWS using Leapp, go back into Geodesic and simply hit return
at the prompt. The prompt should change from having a red ✗ and
having a green √ and
[default] or whatever your profile name is. This is
Geodesic’s way of letting you know you are authorized with AWS, and what
profile you have active.
You can always confirm your current authentication status by running:
aws sts get-caller-identity
When you are properly authenticated, it will output your IAM role and other information. When you are logged out, it will print some kind of error message, usually:
Unable to locate credentials. You can configure credentials by running "aws configure".