diff --git a/0.20.1/search/search_index.json b/0.20.1/search/search_index.json
index e5ebd2e9b..2a25d69da 100644
--- a/0.20.1/search/search_index.json
+++ b/0.20.1/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Overview","text":""},{"location":"#overview","title":"Overview","text":""},{"location":"#welcome-to-leapp","title":"Welcome to Leapp","text":"
Leapp is a tool for developers to manage, secure, and access the cloud.
All data is persisted and encrypted on your workstation. Head to our Security section to know how we guarantee the highest level of security.
Leapp Main Window
The name Leapp is based on the word leap and is pronounced /l:ip/. We chose this name because the project enables you to be one step away from your cloud environments.
"},{"location":"edit-session/","title":"Editing a session","text":"
Leapp allows the user to edit an existing session excluding those generated from an AWS integration.
Info
Integration derived Sessions can\u2019t be changed
To edit an existing session just right-click on a session in the Leapp list (see below), and select \"edit session\". A new modal will appear, allowing the user to choose which parameters to change.
edit session
Below are the configuration options for every type of session:
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Mfa Device (optional): can be left empty or, if you add a valid device name or AWS ARN, it will prompt a modal for MFA code
Access Key ID: Replace your session Access Key ID in the system vault
Secret Access Key: Replace your session Secret Access Key in the system vault
"},{"location":"edit-session/#iam-role-chained","title":"IAM Role Chained","text":"
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Role ARN: The role that you'll assume when chaining from an assumer window
Role Session Name: (optional), it will be used to identify the chained session
Assumer Session: select a session from the list, it will be the Principal assuming the role
Info
You can also generate a new IAM Role Chained session from any other AWS session by right-clicking on a session and chosing \"Create Chained Session\"
"},{"location":"edit-session/#iam-role-federated","title":"IAM Role Federated","text":"
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Role ARN: Role of the Principal in AWS
SAML 2.0 Url: Federated URL needed for authentication to AWS
Identity Provider: the identity provider ARN that you have set up on AWS
After modifying all the parameters, a user can test their validity with test credential generation:
Clicking this button allows Leapp to do a dry run on your parameters, and if valid, a new set of credentials will be generated (but not used) and an informative toast will appear to tell you that they can be used successfully.
"},{"location":"edit-session/#how-we-handle-secrets-when-editing-a-session","title":"How we handle Secrets when Editing a Session","text":"
No secrets will be saved in plain text on your machine. Leapp saves secrets by replacing values in the system keychain, using a combination of an informative name plus the session hidden id.
This way we reduce potential blast radius of an attacker tampering your machine.
When editing a session, Leapp will hide your secrets and you are also unable to copy/paste them from the App.
This section provides an overview of Leapp's integrations, useful to extend the functionality of Leapp to 3rd party services.
Integrations help manage access and identities on your service of choice while using Leapp during your daily activities. They are automatically mapped into Sessions.
Integrations have four main actions available: Create, Delete, Sync, and Logout.
Action Description CREATE Configure a new Integration with the data needed to start the authentication flow. Required to Sync and map the service response into Sessions. DELETE Remove an existing Integration. Removes all the associated Sessions as well and wipes everything related to the Integration from the system (tokens, cache, etc.) SYNC Start the authentication flow to log into the Integration Provider. Leapp will automatically retrieve all the related data and map the response into Sessions. Any change in your service of choice requires a manual Sync to reflect the current status. LOGOUT Disable the Integration. Removes all the Sessions but keeps the Integration data. Running a Sync will restore all the Sessions tied to it."},{"location":"integrations/#supported-services","title":"Supported Services","text":"Service Supported AWS SSO Okta Coming Soon OneLogin Coming Soon AzureAD"},{"location":"sessions/","title":"Sessions","text":""},{"location":"sessions/#sessions","title":"Sessions","text":"
A Session contains all the relevant information to let the dev connect to a cloud provider. Three standard actions should be implemented for each session: start, stop, and rotate.
"},{"location":"sessions/#actions","title":"Actions","text":"Method Description START \u00a0Make the temporary credentials available to the provider chain STOP \u00a0Removes the temporary credentials from the provider chain ROTATE \u00a0Generate new temporary credentials, and substitute the previous ones in the provider chain
The process of setting up Leapp Sessions is managed either manually, for each access method, or through integrations with third-party tools. Leapp stores all the Sessions available to the users locally, inside a configuration file called Workspace.
A Workspace is a global configuration that contains all the relevant information about your Leapp setup (sessions, integrations, app preferences, etc.).
There are two types of workspace: Local and Remote.
A Local workspace is the default workspace that comes with your Leapp installation. It's a private configuration that contains your personal preferences and all sessions and integrations that you created yourself.
A local workspace is associated to a single machine and if you need to migrate your configuration to another one you will have to do it manually.
A Remote workspace is a Leapp Team configuration set created remotely by a Leapp Team manager.
When you sync a remote workspace, you will receive sessions and integrations automatically, without having to configure them yourself.
A remote workspace is persisted online by using Zero-Knowledge encryption.
You will have access to the same configurations instantly on any machine, by logging in to your Leapp Team account after having been invited by your Leapp Team manager.
Info
Both your local and remote workspaces are saved on your machine as encrypted files inside your /.Leapp directory.
The actions below only applies to Remote workspaces.
Action Description Sign-in \u00a0Connect to a Remote workspace. This action will not switch your Local workspace Switch \u00a0Switch to the selected workspace by clicking on its name in the workspace menu Lock \u00a0Switch back to the Local workspace disabling all the Remote ones Sign-out \u00a0Sign-out from a Remote workspace removing all your login details
Info
The Lock action also removes the encrypted files associated to your remote workspaces.
"},{"location":"built-in-features/aws-ec2-connect/","title":"Configure AWS EC2 Connect","text":""},{"location":"built-in-features/aws-ec2-connect/#what-is-aws-ec2-connect","title":"What is AWS EC2 Connect","text":"
Amazon EC2 Instance Connect is a simple and secure way to connect to your instances using Secure Shell (SSH). With EC2 Instance Connect, you can control SSH access to your instances using AWS Identity and Access Management (IAM) policies as well as audit connection requests with AWS CloudTrail events.
"},{"location":"built-in-features/aws-ec2-connect/#how-to-configure-aws-ec2-connect-in-leapp","title":"How To configure AWS EC2 Connect in Leapp","text":"
Warning
If your Leapp Desktop App is warning you that you're missing the AWS Session Manager Plugin, please install it following this official guide.
You can directly connect to an AWS EC2 instance from Leapp through AWS System Manager (AWS SSM).
Info
To setup SSM follow this SSM guide on AWS guide.
example image from AWS
To correctly connect follow these steps:
Right-click on a suitable AWS session to open the contextual menu.
Click on View SSM sessions.
Select the AWS region in which your instance is located.
Wait for Leapp to load your instances.
Select the instance and click connect.
Wait for the terminal to open.
Focus the terminal window and write /bin/bash; press Enter and you'll be inside the terminal of your instance.
If the user is not granted the right permissions, the operation will fail and Leapp will throw an error message.
"},{"location":"built-in-features/aws-named-profiles/","title":"Configure Named Profiles","text":""},{"location":"built-in-features/aws-named-profiles/#what-is-a-named-profile","title":"What is a Named Profile","text":"
Named Profiles are used by AWS to maintain more than one set of active credentials for you to use with AWS-CLI, SDK, or other third-party tools. Named profiles are stored in ~/.aws/credentials file in the ini file format.
Named Profiles have a default profile which is the one you get from aws configure command.
With Leapp you can group and activate more than one credential set at a time through Named Profiles.
"},{"location":"built-in-features/aws-named-profiles/#how-to-configure-a-named-profile-in-leapp","title":"How to configure a Named Profile in Leapp","text":"
Named Profiles can be created in 3 ways:
Option PanelWhen creating a new SessionEdit Profile in Contextual Menu
Click on the gear icon and select the Profiles tab. Insert the name of the new Named Profile in the input form, then click on the plus icon.
When creating a new session, the user will have the option to choose a Named Profile or add a new one.
Right-click on a session and select Change then Named Profile: an option to select or add a new Named Profile will be available.
The new name is directly added to the Named Profile list and can then be used for other sessions too.
Info
AWS SSO sessions will have the Named Profile default when obtained via Login or Sync. To change the Named Profile associated to a session you have to use the \"Change Profile\" option in the session list.
Named profiles can be managed from the Option menu.
In the Option menu, under the Profiles tab, you can add or edit a new Named Profile, and you can also remove unwanted ones. When removing a Named Profile, Leapp will warn you about which sessions are using that profile, and those sessions will be reverted to the default Named Profile.
The input form can be used to add or edit a Named Profile: if it's empty, you can use it to add a new named profile. When selecting the button, you will be able to edit the name of the Named Profile from within the input form.
Warning
Remember that when you change the profile of a session, the session will be immediately put in stop mode. That's because Leapp would have to change the credential file, so you will need to restart the session again.
Once you've opened the Leapp option menu - which can be accessed by clicking the top right gear icon - you can edit the following settings in the General tab
This option allows you to set the default AWS or Azure region/location for every new session.
Each time you create a new session, this will be the default region assigned to it.
You can still change it if you need a different one, by selecting a different region while creating the session or by changing the region once a session is created.
This option is used to select the terminal in which to open an SSM session.
Info
This setting is currently only available on MacOS. If you want to contribute and add a new terminal for a specific OS, please refer to the contributing guide
This option is used to set the default Webconsole session duration in hours.
Info
The minimum session duration is 1 hour, and can be set to a maximum of 12 hours. Set session duration
"},{"location":"built-in-features/multi-console/","title":"Configure Multi Console","text":""},{"location":"built-in-features/multi-console/#what-is-multi-console","title":"What is Multi Console","text":"
The Leapp Multi-Console Browser Extension allows you to open multiple instances of the AWS Web Console in the same browser window and helps you in managing them.
Get it on Firefox \u21e9 Get it on Chrome \u21e9"},{"location":"built-in-features/multi-console/#list-of-supported-browsers","title":"List of Supported Browsers","text":"Browser Supported Firefox Chrome Edge Brave Safari"},{"location":"built-in-features/multi-console/#how-to-configure-multi-console-in-leapp","title":"How to Configure Multi Console in Leapp","text":""},{"location":"built-in-features/multi-console/#install-the-extension","title":"Install the Extension","text":""},{"location":"built-in-features/multi-console/#firefox","title":"Firefox","text":"
You can get the extension on the official Mozilla Addons Store and install it from there:
Visit the page by clicking the button below
Then Click on Add to Firefox
Get it on Firefox \u21e9
"},{"location":"built-in-features/multi-console/#chrome-edge-and-other-chromium-based-browsers","title":"Chrome, Edge and other Chromium based browsers","text":"
Info
Because the extension at the moment relies on Manifest V2, we are unable to upload the extension on the official stores. For more info see Chrome extension documentation
The extension can only be installed manually. To do so, follow these instructions:
Download the zip archive by clicking on the button below
Unzip the file
Open your browser and navigate to about://extensions
Enable Developer mode in the top right corner
Then click on Load unpacked in the top left corner
Finally, Select the folder extracted previously
Get it on Chrome/Others \u21e9
"},{"location":"built-in-features/multi-console/#uninstall-the-extension","title":"Uninstall the Extension","text":""},{"location":"built-in-features/multi-console/#firefox_1","title":"Firefox","text":"
Visit about:addons
Select Leapp Browser Extension and click on the 3 dots
Click on Remove
"},{"location":"built-in-features/multi-console/#chrome-edge-and-other-chromium-based-browsers_1","title":"Chrome, Edge and other Chromium based browsers","text":"
Visit about://extensions
Search for Leapp Browser Extension and click on Remove
See warning section below
Warning
If you are using the Chrome version and you uninstalled or disabled the extension, you have to manually clear cookies for the AWS Console. To do so, when accessing the login page of the AWS Console, on the left of the address bar, click the lock icon and select \"Cookies\". Then, remove all cookies by clicking \"Remove\" until the cookie list is empty and finally click on Done
"},{"location":"built-in-features/multi-console/#how-to-use-it","title":"How to use it","text":"
Once you've installed the extension on your browser, you need to enable the Multi-Console Extension on the Leapp Desktop App in order to use it.
Click on the top-right cog icon to access the settings, click on the Multi-Console tab and then click Enable Multi-Console Extension.
enable option
From the contextual menu of a session (accessed by right-clicking on it), simply select Open Web Console.
Info
If any communication error occurs, your browser is not open or you don't have the extension installed/enabled on it, the web console will be opened in your default browser without using the extension (and will be limited to a single session).
By clicking on the Leapp Multi-Console Extension icon in your browser, a list of all currently active sessions will be shown.
This list contains information obtained from Leapp about the session, including Session Name, Session Role and Session Region.
leapp browser ui
In the extension interface, click on a row to select and focus the tab in which you opened the related AWS Console, so you can easily navigate among many AWS Consoles at the same time.
"},{"location":"built-in-features/opening-web-console/","title":"Configure Open Web Console","text":""},{"location":"built-in-features/opening-web-console/#what-is-open-web-console","title":"What is Open Web Console","text":"
Open Web Console is a Leapp feature that allows you to open the AWS Web Console of a session that you've created in Leapp.
"},{"location":"built-in-features/opening-web-console/#how-to-configure-open-web-console-in-leapp","title":"How to Configure Open Web Console in Leapp","text":"
You can open the AWS Web Console directly from Leapp, without having to log in, input your credentials, or select the role to assume.
To do that just right-click or select the session you want to open in the web console, and click on the icon either in the context-menu or in the bottom-bar below.
Alternatively, you can Command + left-click on a session (or Control + left-click for Windows/Linux ) to open the web console.
Leapp will open your default browser with the Region and the Role already prepared for you in the account you've selected.
note: to use this feature correctly, remember to logout from any web console already opened in the browser.
note: the feature currently is available for IAM Role Federated Sessions, Single Sign-On Sessions, and IAM Role Chained Sessions.
"},{"location":"cli/","title":"Index","text":"
Leapp's Command Line Interface.
Warning
Leapp CLI works only if the Desktop App is installed and running. Note that version >= v0.11.0 of the Desktop App is required. Check the installation guide to install the Desktop App.
"},{"location":"cli/scopes/help/#leapp-help-commands","title":"leapp help [COMMANDS]","text":"
Display help for leapp.
USAGE\n $ leapp help [COMMANDS] [-n]\n\nARGUMENTS\n COMMANDS Command to show help for.\n\nFLAGS\n -n, --nested-commands Include all nested commands in the output.\n\nDESCRIPTION\n Display help for leapp.\n
USAGE\n $ leapp idp-url delete [--idpUrlId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --idpUrlId=<value> the idp url id that we want to pass to the function like the delete one\n\nDESCRIPTION\n Delete an identity provider URL\n\nEXAMPLES\n $leapp idp-url delete\n\n $leapp idp-url delete --idpUrlId ID\n\n $leapp idp-url delete --idpUrlId ID [--force, -f]\n
USAGE\n $ leapp idp-url edit [--idpUrlId <value>] [--idpUrl <value>]\n\nFLAGS\n --idpUrl=<value> the idp url address we want to create\n --idpUrlId=<value> the idp url id that we want to pass to the function like the delete one\n\nDESCRIPTION\n Edit an identity provider URL\n\nEXAMPLES\n $leapp idp-url edit\n\n $leapp idp-url edit --idpUrlId ID --idpUrl ADDRESS\n
USAGE\n $ leapp idp-url list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show identity providers list\n\nEXAMPLES\n $leapp idp-url list\n
USAGE\n $ leapp integration create [--integrationAlias <value>] [--integrationPortalUrl <value>] [--integrationRegion <value>]\n [--integrationType AWS-SSO|AZURE] [--integrationTenantId <value>] [--integrationLocation <value>]\n\nFLAGS\n --integrationAlias=<value> alias that identifies an integration\n --integrationLocation=<value> Location of an Azure Integration\n --integrationPortalUrl=<value> url that identifies the integration portal where you authenticate\n --integrationRegion=<value> an AWS valid region code for the integration\n --integrationTenantId=<value> Tenant ID of an Azure Integration\n --integrationType=<option> Identify the type of your integration. Valid types are [AWS-SSO, AZURE]\n <options: AWS-SSO|AZURE>\n\nDESCRIPTION\n Create a new integration\n\nEXAMPLES\n $leapp integration create\n\n $leapp integration create --integrationType AWS-SSO --integrationAlias ALIAS --integrationPortalUrl URL --integrationRegion REGION\n\n $leapp integration create --integrationType AZURE --integrationAlias ALIAS --integrationTenantId TENANT --integrationLocation LOCATION\n
USAGE\n $ leapp integration delete [--integrationId <value>]\n\nFLAGS\n --integrationId=<value> the Integration Id used to identify the integration inside Leapp\n\nDESCRIPTION\n Delete an integration\n\nEXAMPLES\n $leapp integration delete\n\n $leapp integration delete --integrationId ID\n
USAGE\n $ leapp integration list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show integrations list\n\nEXAMPLES\n $leapp integration list\n
USAGE\n $ leapp integration logout [--integrationId <value>]\n\nFLAGS\n --integrationId=<value> the Integration Id used to identify the integration inside Leapp\n\nDESCRIPTION\n Logout from an integration\n\nEXAMPLES\n $leapp integration logout\n\n $leapp integration logout --integrationId ID\n
USAGE\n $ leapp profile create [--profileName <value>]\n\nFLAGS\n --profileName=<value> an AWS named profile Alias used to identify the profile in both config and credential file\n\nDESCRIPTION\n Create a new AWS named profile\n\nEXAMPLES\n $leapp profile create\n\n $leapp profile create --profileName PROFILENAME\n
USAGE\n $ leapp profile delete [--profileId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --profileId=<value> an AWS named profile ID in Leapp\n\nDESCRIPTION\n Delete an AWS named profile\n\nEXAMPLES\n $leapp profile delete\n\n $leapp profile delete --profileId PROFILEID\n\n $leapp profile delete --profileId PROFILEID [--force, -f]\n
USAGE\n $ leapp profile edit [--profileId <value>] [--profileName <value>]\n\nFLAGS\n --profileId=<value> an AWS named profile ID in Leapp\n --profileName=<value> an AWS named profile Alias used to identify the profile in both config and credential file\n\nDESCRIPTION\n Rename an AWS named profile\n\nEXAMPLES\n $leapp profile edit\n\n $leapp profile edit --profileId ID --profileName PROFILENAME\n
USAGE\n $ leapp profile list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show profile list\n\nEXAMPLES\n $leapp profile list\n
"},{"location":"cli/scopes/region/#leapp-region-get-default","title":"leapp region get-default","text":"
Displays the default region
USAGE\n $ leapp region get-default\n\nDESCRIPTION\n Displays the default region\n\nEXAMPLES\n $leapp region get-default\n
"},{"location":"cli/scopes/region/#leapp-region-set-default","title":"leapp region set-default","text":"
Change the default region
USAGE\n $ leapp region set-default [--region <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n\nDESCRIPTION\n Change the default region\n\nEXAMPLES\n $leapp region set-default\n\n $leapp region set-default --region AWSREGION\n
USAGE\n $ leapp session add [--providerType aws] [--accessKey <value>] [--idpArn <value>] [--idpUrl <value>]\n [--mfaDevice <value>] [--sessionName <value>] [--parentSessionId <value>] [--profileId <value>] [--region <value>]\n [--roleArn <value>] [--roleSessionName <value>] [--secretKey <value>] [--sessionType\n awsIamRoleFederated|awsIamUser|awsIamRoleChained]\n\nFLAGS\n --accessKey=<value> AWS Access Key ID of the IAM User\n --idpArn=<value> AWS IAM Federated Role IdP Arn value, obtain it from your AWS Account\n --idpUrl=<value> the idp url address we want to create\n --mfaDevice=<value> MFA Device Arn retrieved from your AWS Account\n --parentSessionId=<value> For AWS IAM Role Chained is the session Id of the session that will assume the chained\n role. Retrieve it using $leapp session list -x\n --profileId=<value> an AWS named profile ID in Leapp\n --providerType=<option> Identify the provider for your sessions. Valid types are [aws]\n <options: aws>\n --region=<value> Session Region for AWS sessions in Leapp\n --roleArn=<value> AWS IAM Federated Role Arn value, obtain it from your AWS Account\n --roleSessionName=<value> Optional Alias for the Assumed Role Session name\n --secretKey=<value> AWS Secret Access Key of the IAM User\n --sessionName=<value> Session Alias to identify the session in Leapp\n --sessionType=<option> Identify the AWS session type. Valid types are [awsIamRoleFederated, awsIamUser,\n awsIamRoleChained]\n <options: awsIamRoleFederated|awsIamUser|awsIamRoleChained>\n\nDESCRIPTION\n Add a new session\n\nEXAMPLES\n $leapp session add\n\n $leapp session add --providerType [aws] --sessionType [awsIamRoleFederated, awsIamRoleChained, awsIamUser] --region [AWSREGION] --sessionName NAME ...[combination of flags relative to the session]\n\n $leapp session add --providerType aws --sessionType awsIamRoleFederated --sessionName NAME --region AWSREGION --idpArn IDPARN --idpUrl IDPURL --profileId PROFILEID --roleArn ROLEARN\n\n $leapp session add --providerType aws --sessionType awsIamRoleChained --sessionName NAME --region AWSREGION --profileId PROFILEID --roleArn ROLEARN --parentSessionId ID (--roleSessionName ROLESESSIONNAME)\n\n $leapp session add --providerType aws --sessionType awsIamUser --sessionName NAME --region AWSREGION --profileId PROFILEID --accessKey ACCESSKEY --secretKey SECRETKEY (--mfaDevice MFADEVICEARN)\n
USAGE\n $ leapp session change-profile [--sessionId <value>] [--profileId <value>]\n\nFLAGS\n --profileId=<value> an AWS named profile ID in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Change a session named-profile\n\nEXAMPLES\n $leapp session change-profile\n\n $leapp session change-profile --profileId PROFILEID --sessionId SESSIONID\n
USAGE\n $ leapp session change-region [--sessionId <value>] [--region <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Change a session region\n\nEXAMPLES\n $leapp session change-region\n\n $leapp session change-region --sessionId SESSIONID --region REGION\n
Provides info about the current active session for a selected profile (if no profile is provided, it uses the profile default)
USAGE\n $ leapp session current [-i] [-p <value>] [-r aws|azure] [-f <value>]\n\nFLAGS\n -f, --format=<value> allows formatting data to show\n - aws -> id alias, accountNumber, roleArn\n - azure -> id tenantId, subscriptionId\n -i, --inline\n -p, --profile=<value> [default: default] aws named profile of which gets info\n -r, --provider=<option> filters sessions by the cloud provider service\n <options: aws|azure>\n\nDESCRIPTION\n Provides info about the current active session for a selected profile (if no profile is provided, it uses the profile\n default)\n\nEXAMPLES\n $leapp session current --format \"alias accountNumber\" --inline --provider aws\n
USAGE\n $ leapp session delete [--sessionId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Delete a session\n\nEXAMPLES\n $leapp session delete\n\n $leapp session delete --sessionId SESSIONID\n\n $leapp session delete --sessionId SESSIONID [--force, -f]\n
Generate STS temporary credentials for the given AWS session id
USAGE\n $ leapp session generate SESSIONID\n\nARGUMENTS\n SESSIONID id of the session\n\nDESCRIPTION\n Generate STS temporary credentials for the given AWS session id\n\nEXAMPLES\n $leapp session generate 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d\n
Show sessions list with all properties; filter query is case sensitive
USAGE\n $ leapp session list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show sessions list with all properties; filter query is case sensitive\n\nEXAMPLES\n $leapp session list\n\n $leapp session list --filter=\"ID=Foo\" -x\n\n $leapp session list --filter=\"Session Name=Foo\"\n\n $leapp session list --filter=\"Type=Foo\"\n\n $leapp session list --filter=\"Named Profile=Foo\"\n\n $leapp session list --filter=\"Region/Location=Foo\"\n\n $leapp session list --filter=\"Status=Foo\"\n
USAGE\n $ leapp session open-web-console [--sessionId <value>] [-p]\n\nFLAGS\n -p, --print Print an AWS Web Console login URL in the terminal instead of opening the web browser\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Open an AWS Web Console\n\nEXAMPLES\n $leapp session open-web-console\n\n $leapp session open-web-console --sessionId SESSIONID [--print, -p]\n
USAGE\n $ leapp session run-aws-credential-plugin [--sessionId <value>] [--pluginName <value>]\n\nFLAGS\n --pluginName=<value> Unique name of a Leapp Plugin\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Run a Leapp Plugin\n\nEXAMPLES\n $leapp session run-plugin\n\n $leapp session run-plugin --sessionName SESSIONAME --pluginName PLUGINNAME\n
USAGE\n $ leapp session start [SESSIONNAME] [--sessionId <value>] [--sessionRole <value>] [--noInteractive]\n\nARGUMENTS\n SESSIONNAME Name of the Leapp session\n\nFLAGS\n --noInteractive If the specified session is not unique or doesn't exist, throw an error without starting the\n interactive session selection mode\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --sessionRole=<value> Session Role of one or more sessions in Leapp\n\nDESCRIPTION\n Start a session\n\nEXAMPLES\n $leapp session start\n\n $leapp session start SESSIONNAME\n\n $leapp session start SESSIONNAME --sessionRole SESSIONROLE\n\n $leapp session start SESSIONNAME --noInteractive\n\n $leapp session start --sessionId SESSIONID\n
USAGE\n $ leapp session start-ssm-session [--sessionId <value>] [--region <value>] [--ssmInstanceId <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --ssmInstanceId=<value> Instance ID for EC2 instance we want to access with SSM\n\nDESCRIPTION\n Start an AWS SSM session\n\nEXAMPLES\n $leapp session start-ssm-session\n\n $leapp session start-ssm-session --sessionId SESSIONID --region AWSREGION --ssmInstanceId EC2INSTANCEID\n
USAGE\n $ leapp session stop [SESSIONNAME] [--sessionId <value>] [--sessionRole <value>] [--noInteractive]\n\nARGUMENTS\n SESSIONNAME Name of the Leapp session\n\nFLAGS\n --noInteractive If the specified session is not unique or doesn't exist, throw an error without starting the\n interactive session selection mode\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --sessionRole=<value> Session Role of one or more sessions in Leapp\n\nDESCRIPTION\n Stop a session\n\nEXAMPLES\n $leapp session stop\n\n $leapp session stop SESSIONNAME\n\n $leapp session stop SESSIONNAME --sessionRole SESSIONROLE\n\n $leapp session stop SESSIONNAME --noInteractive\n\n $leapp session stop --sessionId SESSIONID\n
USAGE\n $ leapp set-workspace [WORKSPACENAME]\n\nARGUMENTS\n WORKSPACENAME name of the Leapp Team remote workspace or local\n\nDESCRIPTION\n Set the current Leapp workspace\n\nEXAMPLES\n $leapp team set-workspace\n\n $leapp team set-workspace local\n\n $leapp team set-workspace WORKSPACE-NAME\n
USAGE\n $ leapp workspace\n\nDESCRIPTION\n Show the current workspace\n\nEXAMPLES\n $leapp workspace\n
See code: dist/commands/workspace.ts
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/","title":"Configure an AWS Identity Center (ex AWS Single Sign-On) integration","text":""},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#what-is-aws-identity-center-ex-aws-single-sign-on","title":"What is AWS Identity Center (ex AWS Single Sign-On)","text":"
AWS Identity Center (ex AWS Single Sign-On) is a cloud service that allows you to grant your users access to AWS resources across multiple AWS accounts.
AWS SSO provides a directory that you can use to create users, organize them in groups, and set permissions across those groups; alternatively, you can obtain them from your Microsoft Active Directory or any standards-based identity provider, such as Okta Universal Directory or Azure AD.
After logging in the first time, Leapp will map all your roles and users into Sessions.
Info
To get started using AWS SSO refer to this guide.
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#how-to-configure-an-aws-identity-center-ex-aws-single-sign-on-integration-in-leapp","title":"How to configure an AWS Identity Center (ex AWS Single Sign-On) integration in Leapp","text":"
Click on the Add Integration button in the sidebar.
Select AWS Single Sign-On as the Integration type.
Provide the required information (described in the next section).
Click on the Add integration button.
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#required-information","title":"Required information","text":"Field Description INTEGRATION TYPE Set as AWS Single Sign-on AWS SSO URL The portal URL to begin the authentication flow. It usually follows this pattern: d-xxxxxxxxxx.awsapps.com/start. REGION The region on which AWS SSO is administered and configured. This is NOT where your generated credentials will be valid; it's only used for the login part."},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-integration/configure-azure-integration/","title":"Configure an Azure integration","text":""},{"location":"configuring-integration/configure-azure-integration/#what-is-an-azure-integration","title":"What is an Azure integration","text":"
Our Leapp integration refers to Azure Tenant which is a dedicated and trusted instance of Azure AD.
The tenant is automatically created when your organization signs up for a Microsoft cloud service subscription.
These subscriptions include Microsoft Azure, Microsoft Intune, or Microsoft 365.
An Azure tenant represents a single organization and can have multiple subscriptions.
Please refer to How to find your Azure Active Directory tenant ID and other Azure AD documentation for more information.
Warning
For azure-cli users with version < 2.30.0: Leapp no longer supports this version of the CLI. Please update to a newer version.
To create a new Azure Integration, go to the left sidebar of Leapp Desktop and click on the icon. A new modal will be presented with the following option to compile. After submitting the new Integration and have logged into your Azure Portal, Subscriptions will be automatically retrieved and mapped into Leapp Azure Sessions.
"},{"location":"configuring-integration/configure-azure-integration/#how-to-configure-an-azure-integration-in-leapp","title":"How to configure an Azure integration in Leapp","text":"
Click on the Add Integration button in the sidebar.
Select Azure as the Integration type.
Provide the required information (described in the next section).
Click on the Add integration button.
"},{"location":"configuring-integration/configure-azure-integration/#required-information","title":"Required information","text":"Field Description INTEGRATION TYPE Set as Azure ALIAS Your friendly integration name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. TENANT ID A tenant ID identifies a tenant. You can have multiple clients on a given tenant database. LOCATION The Azure datacenters are located around the world in strategic places that best meet the customer demands. These areas are known as Azure locations. Specific services requires the user to select a specific location. The value is retrieved from your default location in general options."},{"location":"configuring-integration/configure-azure-integration/#video-tutorial","title":"Video tutorial","text":"
Info
Azure sessions are not available anymore for direct creation. Instead you can create a new Azure Integration.
"},{"location":"configuring-session/configure-aws-iam-role-chained/","title":"Configure AWS IAM Role Chained","text":""},{"location":"configuring-session/configure-aws-iam-role-chained/#what-is-an-aws-iam-role-chained-session","title":"What is an AWS IAM Role Chained session","text":"
An AWS IAM Role Chained session represents an AWS role chaining access. Role chaining is the process of assuming a role starting from another IAM role or user.
An IAM role has some similarities to an IAM user. Roles and users are both AWS identities with permissions policies that determine what the identity can and cannot do in AWS. However, instead of being uniquely associated with one person, a role is intended to be assumable by anyone who needs it.
A role does not have standard long-term credentials such as a password or access keys associated with it. Instead, when you assume a role, it provides you with temporary security credentials for your role session.
Role chaining occurs when you use a role to assume a second role through the AWS CLI or API, even in other accounts.
Info
Refer to this guide to delegate access across AWS accounts using IAM Roles chaining.
"},{"location":"configuring-session/configure-aws-iam-role-chained/#how-to-configure-an-aws-iam-role-chained-in-leapp","title":"How to configure an AWS IAM Role Chained in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM Role Chained as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-role-chained/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. ROLE ARN Your IAM Role unique ID. The active Session will refer to this Role. ROLE SESSION NAME Your session name. You can query and search this on AWS Cloudtrail or any other linked audit service to find out what action were performed by the linked Identity. ASSUMER SESSION Your session from which this Role will be assumed. The assume-role call will be automatically made by Leapp."},{"location":"configuring-session/configure-aws-iam-role-chained/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-aws-iam-role-federated/","title":"Configure AWS IAM Role Federated","text":""},{"location":"configuring-session/configure-aws-iam-role-federated/#what-is-an-aws-iam-role-federated-session","title":"What is an AWS IAM Role Federated session","text":"
An AWS IAM Role Federated session represents an access type that relies on a federation between an AWS account and an external Identity Provider.
AWS Identity and Access Management (IAM) supports identity federation for delegated access to the AWS Management Console or AWS APIs. With identity federation, external identities are granted secure access to resources in your AWS accounts through IAM roles.
These external identities can come from your corporate identity provider (such as Microsoft Active Directory or from the AWS Directory Service) or from a web identity provider (such as Amazon Cognito, Login with Amazon, Facebook, Google, or any OpenID Connect-compatible provider).
We currently only support SAML 2.0 federation.
Info
Refer to this guide to provision your own federated roles.
Refer to this guide to configure and trust your SAML 2.0 Identity Provider.
Is your SAML 2.0 Identity Provider not included in the above list? Please, refer to the FAQ to add a new one.
"},{"location":"configuring-session/configure-aws-iam-role-federated/#how-to-configure-an-aws-iam-role-federated-in-leapp","title":"How to configure an AWS IAM Role Federated in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM Role Federated as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-role-federated/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. SAML 2.0 URL Your SAML URL interface to start the authentication flow and log into your Identity provider. AWS IDENTIY PROVIDER ARN Your Identity Provider ID in AWS. You can find it in IAM section Identity Providers. ROLE ARN Your IAM Role unique ID. The active Session will refer to this Role."},{"location":"configuring-session/configure-aws-iam-role-federated/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-aws-iam-user/","title":"Configure AWS IAM User","text":""},{"location":"configuring-session/configure-aws-iam-user/#what-is-an-aws-iam-user-session","title":"What is an AWS IAM User session","text":"
An AWS Identity and Access Management (IAM) user is an entity that you create in AWS to represent the person or application that uses it to interact with AWS.
An IAM User in AWS consists of a name and a set of long-term credentials. Leapp never sets these values in the configuration files, and automatically generates and refreshes a set of short-term credentials.
Info
If you want to know how Leapp generates and refresh short-term credentials refer to the credentials generation section in the documentation.
"},{"location":"configuring-session/configure-aws-iam-user/#how-to-configure-an-aws-iam-user-in-leapp","title":"How to configure an AWS IAM User in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM User as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-user/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. MFA DEVICE Your MFA device ID to set up multi-factor authentication. ACCESS KEY ID Your long-term Access Key. It will be used to generate a short-term set of credentials. Don't disclose it to anyone. SECRET ACCESS KEY Your long-term Secret Key. It will be used to generate a short-term set of credentials. Don't disclose it to anyone. Add AWS IAM User Screen"},{"location":"configuring-session/configure-aws-iam-user/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-localstack/","title":"Configure LocalStack","text":""},{"location":"configuring-session/configure-localstack/#what-is-a-localstack-session","title":"What is a LocalStack session","text":"
With LocalStack you can emulate AWS cloud services with a fully functional cloud stack on your local machine. Develop and test your cloud applications with the full cloud experience, but without the hassle of the remote cloud.
You can use Leapp to create a LocalStack session that can then be used to set your local credential file and access your LocalStack resources.
Info
You need to install LocalStack in order to use the AWS cloud emulation features
"},{"location":"configuring-session/configure-localstack/#how-to-configure-a-localstack-session-in-leapp","title":"How to configure a LocalStack session in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select LocalStack as the Cloud Provider.
Provide a name for the session.
Click on the Create Session button.
Warning
LocalStack sessions work only with AWS Credential Method configured with the credential-file-method option. The option is available in the Options menu > General > Generics > AWS Credential Method.
Warning
In order to use the credential file to access LocalStack from your AWS CLI, you must update the AWS CLI to the latest version.
Contributions and questions are not just welcome, they\u2019re essential! Please open issues with ideas on how to improve Leapp, including feedback, critiques, and information about how you\u2019re using it. Discussion is at the heart of the project and your thoughts and ideas will help make it better for everyone, thank you.
Read our contribution guide to learn more.
You can chat with us in our community, so join us, or feel free to contact us via the website!
Join our Community
"},{"location":"installation/install-leapp/","title":"Install Leapp","text":""},{"location":"installation/install-leapp/#install-leapp-app","title":"Install Leapp App","text":""},{"location":"installation/install-leapp/#macos-windows-and-linux","title":"MacOS, Windows, and Linux","text":"
You can install Leapp by downloading the pre-built binaries for your OS on the website release page:
Download Leapp \u21e9
Unzip the package and double-click the executable to install.
You can install Leapp CLI through a Homebrew Formula:
brew install Noovolari/brew/leapp-cli\n
In Linux it may happen that the command leapp is not recognized. In that case we suggest to run the following command:
brew link leapp-cli\n
"},{"location":"installation/install-leapp/#install-leapp-cli-on-macos-with-arm64-chip-m1-m2","title":"Install Leapp CLI on macOS with ARM64 chip (M1, M2)","text":"
On macOS with ARM64 chip you can use the Homebrew Formula:
All the available commands are listed in the Leapp CLI section of the documentation.
Warning
Leapp CLI will work only if the Desktop App is installed and running.
"},{"location":"installation/requirements/","title":"Requirements","text":""},{"location":"installation/requirements/#requirements","title":"Requirements","text":""},{"location":"installation/requirements/#macos-and-windows","title":"MacOS and Windows","text":"
There are no requirements for macOS and Windows users.
Leapp uses libsecret and gnome-keyring as dependencies to store all sensitive data into the keyring. Depending on your distribution, you may need to install them using these commands before running Leapp.
"},{"location":"installation/requirements/#logging-into-ec2-instances-via-aws-ssm-with-leapp","title":"Logging into EC2 Instances via AWS SSM with Leapp","text":"
In order to use AWS SSM on your System through Leapp, you must be able to execute this command on your own at least once, when the correct credentials are active.
Leapp checks if a new version is available every 10 minutes (starting from the application launch). If so, a dialog message will pop up and show a version number, the release date and the changelog
In this modal, a user can do the following:
Remind me laterDownload updateClick on X
Leapp will close the modal and notify the user that a new update is available by adding a notification dot to the Dock Bar icon. Users will not be bothered anymore until the next release is available. This option is convenient for users that want to stick to a specific version. Note that you can do this for every version and maintain the one you prefer.
Leapp will open the Release URL in your default browser to let the User manually download the release for their specific OS and install it.
Leapp will close the modal and another one will appear in 10 minutes.
"},{"location":"installation/update-leapp/#macos-homebrew-linux-linuxbrew-and-windows-via-wsl","title":"macOS (Homebrew), Linux (Linuxbrew) and Windows (via WSL)","text":"
Leapp can also be updated via Homebrew Cask with: brew upgrade leapp
Depending on which method you used to install the CLI (npm or Homebrew on macOS), you can update it with the following commands:
npmHomebrew (macOS)
npm update -g @noovolari/leapp-cli\n
brew upgrade Noovolari/brew/leapp-cli\n
"},{"location":"leapp-pro/security-and-password/","title":"Security and password","text":""},{"location":"leapp-pro/security-and-password/#password-issues","title":"Password issues","text":""},{"location":"leapp-pro/security-and-password/#can-i-recover-my-password","title":"Can I recover my password?","text":"
Unfortunately, it is not possible to recover the master password. The master password is very important as it's the key point of our zero-knowledge encryption mechanism. If you forget it, you'll lose access to the previously encrypted Leapp Sessions and Integrations. That's why it is crucial that you keep your password safe; we suggest you to store it in a password manager like 1Password.
"},{"location":"leapp-pro/security-and-password/#how-is-my-data-encrypted","title":"How is my data encrypted?","text":"
All information associated with your stored data is protected with end-to-end encryption. Leapp Sessions and Integrations are encrypted before being forwarded to the backend. Specifically, Leapp Pro uses AES 256-bit encryption as well as PBKDF-SHA512 to secure your data.
AES is a standard in cryptography and is used by the U.S. government and other government agencies around the world for protecting top-secret data. With proper implementation and a strong encryption key (your Master Password), AES is considered unbreakable.
PBKDF-SHA512 is used to derive the encryption key from your master password. Then this key is salted and hashed for authenticating with the Leapp Pro backend. The default iteration count used with PBKDF2 is 500,000 iterations on the client. Each Secret has its own generated symmetric key; this symmetric key is encrypted using the user\u2019s public RSA key (this is also the foundation of the Secret sharing system). This encryption and decryption are done entirely on the Leapp Pro clients because your master password is never stored on or transmitted to Leapp Team backend.
It is important to highlight the fact that the backend does not act as a credentials broker, i.e. it has no visibility on the long-term/short-term credentials used by Leapp Pro Desktop App/CLI to access the cloud providers. In addition, the secrets retrieved from the backend, are an encrypted version of access configurations; access configurations DO NOT include temporary credentials. There is a single edge case: the IAM User. Indeed, the IAM User Session access configuration contains IAM User\u2019s access keys, which are long-term credentials. Still, the Leapp Pro backend has no visibility on these long-term credentials, as they\u2019re encrypted by the client before being forwarded to the Leapp Team backend.
When you unlock Leapp Pro, using a longer and more secure account password is easier than you might otherwise have chosen.
"},{"location":"leapp-pro/security-and-password/#your-fingerprint-is-not-stored-in-leapp","title":"Your fingerprint is not stored in Leapp.","text":"
Leapp never scans or stores your fingerprint. Touch ID is provided by macOS, which only tells Leapp Pro if your fingerprint was recognized or not.
Learn more about Touch ID's advanced security technology.
"},{"location":"leapp-pro/synchronization/","title":"Synchronization","text":""},{"location":"leapp-pro/synchronization/#whats-a-pro-workspace","title":"What's a Pro Workspace","text":"
A Pro Workspace is a new Workspace that is created upon first login with your registered Pro User. This workspace is synchronized with your Cloud account every time you create, edit, or delete an integration or a session; this way it is possible to use Leapp Pro on different devices, maintaining all your saved integrations and sessions.
"},{"location":"leapp-pro/synchronization/#how-the-synchronization-works","title":"How the Synchronization works","text":"
Synchronization works by encrypting all your sessions and integrations with your master password, created during your sign-up process. This way we maintain a 0-knowlegde approach on your data through all the lifecycle of your Pro workspace.
The encrypted data is then saved in the Cloud on your Leapp Pro personal space.
You, as a Leapp Pro user, can always keep an eye on the status of synchronization using the synchronization widget in the bottom-left area of Leapp.
Synchronization widget - synchronization active and done
When all the data is correctly synchronized you'll see the image above.
When Leapp Pro is synchronizing you'll see the icon and text changing to the one in the image below.
Synchronization widget - synchronization in progress
If you eventually lose connection or have a problem in synchronizing your data the widget will turn yellow as shown below.
Synchronization widget - synchronization failed
You have the possibility to manually trigger another synchronization process and see if the problem is resolved.
Info
When Leapp Pro is restarted it will try to synchronize your data in the Cloud if you're logged in, so you can also close Leapp safely even if in synch failed state.
"},{"location":"leapp-pro/synchronization/#do-you-have-any-trouble-with-synchronization","title":"Do you have any trouble with Synchronization","text":"
In case of any troubles locking Leapp Pro workspace please contact us.
Leapp Pro enable Users to protect their Cloud access with Username and password.
With Leapp Pro you can back up and synchronize your Leapp workspace and access to any device you want without losing your access configurations.
"},{"location":"leapp-pro/getting-started/#getting-started-guide","title":"Getting started guide","text":"
Sign up to Leapp Pro
Sign in to Leapp Pro
Lock your Leapp Pro Workspace
"},{"location":"leapp-pro/getting-started/#security-and-syncronization","title":"Security and syncronization","text":"
Once you updgrade your Plan to Leapp Pro, your local Workspace will be moved to the Pro Workspace. All the data inside your workspace are secured with end-to-end encryption through your Master password.
"},{"location":"leapp-pro/getting-started/lock/","title":"Lock your Workspace","text":"
Leapp Pro allows the user to temporary lock the workspace, making it accessible only by typing again your master-password. This feature provides a further security level on top of the standard Leapp Community edition.
"},{"location":"leapp-pro/getting-started/lock/#how-to-lock-the-leapp-pro-workspace","title":"How to lock the Leapp Pro workspace","text":"
To lock your Leapp Pro workspace you should click on the Workspace button located in the top-left area and select the Lock option.
Workspace button Lock option
The Leapp Pro lock screen should appear, prompting for your master-password.
Leapp Pro lock screen"},{"location":"leapp-pro/getting-started/lock/#touch-id","title":"Touch ID","text":"
You can also use your fingerprint to unlock Leapp if your PC is Touch ID compatible. After Logging to your Pro workspace for the first time, Leapp will associate your workspace with your system Touch ID. After that the option will be available and can also be tweaked in the general tab of the option menu.
"},{"location":"leapp-pro/getting-started/lock/#troubles-in-locking-your-workspace","title":"Troubles in locking your Workspace","text":"
In case of any troubles locking Leapp Pro workspace please contact us.
With Leapp Pro you can always sign-in from any location, gaining instant access to your personal workspace.
"},{"location":"leapp-pro/getting-started/sign-in/#sign-in-to-leapp-pro","title":"Sign-in to Leapp Pro","text":"
After upgrading Leapp Community edition, you can sign-in at any time, just clicking on the Workspace button located in the top-left area and selecting the Sign-in Workspace option.
Workspace button Sign-in Workspace option
The Sign-in Workspace dialog will appear. Enter your Email address, master-password and click on the Add Workspace button.
Sign-in dialog
If the information entered is correct, your Leapp Pro workspace will be displayed and you can immediately use it to manage your cloud credentials.
Leapp Pro Workspace
To avoid unwanted access, you can lock your Leapp Pro workspace at any time.
"},{"location":"leapp-pro/getting-started/sign-in/#troubles-in-signing-in-to-leapp-pro","title":"Troubles in signing in to Leapp Pro?","text":"
In case of any troubles signing in to Leapp Pro please contact us.
A Leapp Pro upgrade is required to enable new workspace features like Cloud access from multiple locations and Workspace locking.
"},{"location":"leapp-pro/getting-started/sign-up/#sign-up-to-leapp-pro","title":"Sign-up to Leapp Pro","text":"
To sign up for Leapp Pro you should upgrade your version of Leapp Community edition. Click on the Options button in the top-right area.
Settings button
In the Options dialog, select the Plans tab and click on Upgrade to Pro button.
Plans tab
The upgrade window should appear. Enter your email (it will be the email address associated with your Leapp Pro account) and click on the Upgrade now button.
Upgrade window
At this point a window will appear, so you can specify a payment method to complete the Leapp Pro upgrade. After the payment process you will receive a confirmation email containing the Complete the registration link.
Upgrade email
Clicking the link in the confirmation email will open a web page that will allow you to enter your personal info and the master-password, essential to provide the security requirements of Leapp Pro.
Sign-up page
After entering your personal info and the master-password click the Continue button. You can now finally sign in to Leapp Pro.
"},{"location":"leapp-pro/getting-started/sign-up/#troubles-in-signing-up-to-leapp-pro","title":"Troubles in signing up to Leapp Pro?","text":"
In case of any troubles signing up to Leapp Pro please contact us.
"},{"location":"leapp-pro/getting-started/sign-up/#how-to-sign-in","title":"How to Sign-in","text":"
Take a look to this page to sign-in your Leapp Pro workspace.
argument type description message string the message to show level LogLevel severity of the message display boolean shows the message in a toast in the desktop app when true. Otherwise, log it in the log files"},{"location":"plugins/plugins-development/#fetch","title":"fetch","text":"
fetch(url: string): any
Retrieve the content of a URL. Returns a promise for the URL
argument type description url string a valid HTTP URL to fetch from"},{"location":"plugins/plugins-development/#openexternalurl","title":"openExternalUrl","text":"
openExternalUrl(url: string): void
Open an external URL in the default browser
argument type description url string a valid HTTP URL to open in the default browser"},{"location":"plugins/plugins-development/#createsession","title":"createSession","text":"
Creates a new Leapp Session based on given SessionData
argument type description createSessionData SessionData the metadata used to create the Leapp Session"},{"location":"plugins/plugins-development/#clonesession","title":"cloneSession","text":"
cloneSession(session: Session): Promise<string>
This method allows you to clone the given Leapp Session. This operation is allowed for the following Leapp Session types:
AwsIamUserSession
AwsIamRoleFederatedSession
AwsIamRoleChainedSession
argument type description session Session the Leapp Session that I want to clone"},{"location":"plugins/plugins-development/#updatesession","title":"updateSession","text":"
This method allows you to update the given session with the given updateSessionData. This operation is allowed for the following Leapp Session types:
AwsIamUserSession
AwsIamRoleFederatedSession
AwsIamRoleChainedSession
argument type description updateSessionData SessionData the metadata used to update the given Leapp Session session Session the Leapp Session that I want to update"},{"location":"plugins/plugins-development/#openterminal","title":"openTerminal","text":"
Execute the given command in the platform-specific terminal; optionally, it is possible to set an env key/value object containing the env variables to export in the terminal, before the command execution.
The terminal window base path is set to the home directory.
argument type description command string the command that I want to execute in the platform-specific terminal env any optional key/value env variables object"},{"location":"plugins/plugins-development/#getprofileidbyname","title":"getProfileIdByName","text":"
getProfileIdByName(profileName: string): string
Returns the id of a named profile from its name if it exists, otherwise creates a new profile and returns its id.
Can be used when creating/editing a session since SessionData requires the id of a named profile
argument type description profileName string a valid named profile"},{"location":"plugins/plugins-development/#getidpurlidbyurl","title":"getIdpUrlIdByUrl","text":"
getIdpUrlIdByUrl(url: string): string
Return the ID of the IdpUrl object from the given URL if it exists, otherwise creates a new IdP URL and returns its ID.
Can be used when creating/editing Federated Sessions since SessionData requires the ID of an IdP URL.
argument type description url string the URL associated with the IdpUrl I want to retrieve"},{"location":"plugins/plugins-development/#example-display-a-toast-message-in-leapp","title":"Example: display a toast message in Leapp","text":"
Return a valid FontAwesome 5 code. Override default value in package.json
"},{"location":"plugins/plugins-development/#example-display-a-session-based-message-in-leapp","title":"Example: display a session-based message in Leapp","text":"
async applySessionAction(session: Session, credentials: any): Promise<void> {\nif(session.type === Session.awsIamUser) {\nthis.pluginEnvironment.log(`This is an IAM User session: ${session.sessionName}`, LogLevel.info, true); }\nelse {\nthis.pluginEnvironment.log(`This is NOT an IAM User session: ${session.sessionName}`, LogLevel.info, true);\n}\n}\n
"},{"location":"plugins/plugins-development/#packagejson-metadata","title":"package.json metadata","text":"property values description constraints name a custom string the name of the plugin the same used in the plugin folder author a custom string the name of the author none version a custom string the version of the plugin must be a semver string description a custom string the description of the plugin none keywords a string array the name of the plugin must contain at least \"leapp-plugin\" leappPlugin an object the plugin custom configuration must contain at least \"supportedOS\" and \"supportedSessions\" leappPlugin.supportedOS a string array [\"mac\", \"windows\", \"linux\"] if not specified, all OSs will be considered compatible leappPlugin.supportedSessions a string array [\"anyType, \"aws\", \"azure\", \"awsIamRoleFederated\", \"awsIamRoleChained\", \"awsSsoRole\", \"awsIamUser\"] at least one of these values must be specified leappPlugin.icon a custom string fontAwesome code for an icon (e.g. \"fa fa-globe\") must be a valid FontAwesome 5 code"},{"location":"plugins/plugins-development/#plugin-examples","title":"Plugin Examples","text":""},{"location":"plugins/plugins-development/#open-web-console","title":"Open Web Console","text":"
import { Session } from \"@noovolari/leapp-core/models/session\";\nimport { AwsCredentialsPlugin } from \"@noovolari/leapp-core/plugin-sdk/aws-credentials-plugin\";\nimport { PluginLogLevel } from \"@noovolari/leapp-core/plugin-sdk/plugin-log-level\";\n\nexport class WebConsolePlugin extends AwsCredentialsPlugin {\nget actionName(): string {\nreturn \"Open web console\";\n}\n\nget actionIcon(): string {\nreturn \"fa fa-globe\";\n}\n\nasync applySessionAction(session: Session, credentials: any): Promise<void> {\nthis.pluginEnvironment.log(\"Opening web console for session: \" + session.sessionName, PluginLogLevel.info, true);\n\nconst sessionRegion = session.region;\nconst sessionDuration = 3200;\nconst isUSGovCloud = sessionRegion.startsWith(\"us-gov-\");\nlet federationUrl;\nlet consoleHomeURL;\n\nif (!isUSGovCloud) {\nfederationUrl = \"https://signin.aws.amazon.com/federation\";\nconsoleHomeURL = `https://${sessionRegion}.console.aws.amazon.com/console/home?region=${sessionRegion}`;\n} else {\nfederationUrl = \"https://signin.amazonaws-us-gov.com/federation\";\nconsoleHomeURL = `https://console.amazonaws-us-gov.com/console/home?region=${sessionRegion}`;\n}\n\nif (sessionRegion.startsWith(\"cn-\")) {\nthrow new Error(\"Unsupported Region\");\n}\n\nthis.pluginEnvironment.log(\"Starting opening Web Console\", PluginLogLevel.info, true);\n\nconst sessionStringJSON = {\nsessionId: credentials.sessionToken.aws_access_key_id,\nsessionKey: credentials.sessionToken.aws_secret_access_key,\nsessionToken: credentials.sessionToken.aws_session_token,\n};\n\nconst queryParametersSigninToken = `?Action=getSigninToken&SessionDuration=${sessionDuration}&Session=${encodeURIComponent(\nJSON.stringify(sessionStringJSON)\n)}`;\n\nconst res = await this.pluginEnvironment.fetch(`${federationUrl}${queryParametersSigninToken}`);\nconst response = await res.json();\n\nconst loginURL = `${federationUrl}?Action=login&Issuer=Leapp&Destination=${consoleHomeURL}&SigninToken=${(response as any).SigninToken}`;\nthis.pluginEnvironment.openExternalUrl(loginURL);\n}\n}\n
"},{"location":"plugins/plugins-introduction/","title":"Introduction to Plugins","text":"
This section provides an overview of Leapp\u2019s plugins, which can be used to extend the functionality of Leapp.
Plugins are commonly used when more advanced and custom behavior is needed, for example using Leapp-generated temporary credentials to run custom actions.
You can create your own plugins or import custom ones created by the community. You can also publish your plugins on npm to make them available to everyone easily.
"},{"location":"plugins/plugins-introduction/#add-a-plugin","title":"Add a Plugin","text":"
To add a plugin you can use one of the following methods:
"},{"location":"plugins/plugins-introduction/#add-from-npm","title":"Add from npm","text":"
From the Leapp option menu, go to the Plugins tab. Insert the name of the npm package for the plugin and click on the plus icon to add it to your plugins
Go to Options by clicking the top right gear icon then click the Plugins tab. Click the Folder Icon. This will open the plugin folder inside .Leapp.
Here, manually create a folder with the same name as your plugin package.json name property and move your package.json and bundled plugin.js files inside this folder.
Alternatively, you can simply move your entire plugin folder cloned from the example template.
Lastly, from the Leapp Plugins tab in the Option menu, click on the refresh icon to reload all plugins.
Warning
Adding plugins is at your own risk! We cannot currently guarantee that a plugin is safe, so BE CAREFUL when you install something from an unknown source. A plugin verification system is under development and will be available later this year.
"},{"location":"plugins/plugins-introduction/#disable-a-plugin","title":"Disable a Plugin","text":"
To disable a Leapp plugin, go to Options by clicking the top right gear icon then click the Plugins tab.
Toggle Enabled for the plugin you want to disable.
"},{"location":"plugins/plugins-introduction/#remove-a-plugin","title":"Remove a Plugin","text":"
To remove a Leapp plugin, go to Options by clicking the top right gear icon then click the Plugins tab.
Click the Folder Icon. This will open the plugin folder inside .Leapp. From here, locate the folder containing the plugin you want to remove and simply delete the folder.
"},{"location":"plugins/plugins-introduction/#run-a-plugin","title":"Run a Plugin","text":"
You can run a plugin both from Leapp Desktop App and Leapp CLI.
From Leapp Desktop App, right click on a session to open the contextual menu, click on Plugins, and select the plugin you want to run
Info
This contextual menu option is not available if you have no plugins that you can run on the selected session and/or your operating system.
From Leapp CLI, you can use the command leapp session run-plugin. For more information on how to use this CLI command, see the documentation.
Click on the top right gear icon to go to the Leapp option menu and then select the tab Plugin.
From there, you can see a list of currently installed plugins, check whether a plugin is compatible with your system or not, which session types it supports and disable/enable it if you need.
"},{"location":"plugins/plugins-introduction/#create-your-plugin","title":"Create your Plugin","text":"
You can start creating a plugin from the template.
Leapp plugins are written in TypeScript. They must contain at least a class that extends a base class provided by the Plugin SDK.
There's currently only one of these classes, AwsCredentialsPlugin , that can be used to create a plugin that generates temporary credentials.
Every Leapp plugin must at least have a package.json file and a plugin.js file.
leapp-plugin/ \n \u251c\u2500\u2500 package.json # Plugin metadata\n \u2514\u2500\u2500 plugin.js # A webpack bundle for the main logic\n
Create your Plugin
"},{"location":"security/credential-process/","title":"Credential Process","text":""},{"location":"security/credential-process/#what-is-credential-process","title":"What is Credential Process?","text":"
Credential Process is a configuration option (in the AWS config file) that instruct the AWS CLI and SDKs to use an external command to generate valid credentials in a specific format.
It is a way to generate AWS compatible credentials on the fly, only when requested by tools that respect the AWS credential chain.
Credential Process is perfect if you have a way to generate or look up credentials that isn't directly supported by the AWS CLI or third-party tools; for example, you can configure the AWS CLI to use it by configuring the credential_process setting in the config file.
The difference between Credential Process and Standard Credential file is that credentials in the \"credential file\" are written in plain text and so, they are potentially unsecure, even if temporary. Credential Process instead, generates credentials that are consumed only when they are effectively needed.
No credential is written in any file. They are printed on the stdout and consumed upon request.
"},{"location":"security/credential-process/#how-credential-process-works","title":"How Credential Process works?","text":"
Credential Process asks an external process to generate an AWS compatible temporary credential set in this format:
{\n\"Version\": 1,\n\"AccessKeyId\": \"an AWS access key\",\n\"SecretAccessKey\": \"your AWS secret access key\",\n\"SessionToken\": \"the AWS session token for temporary credentials\", \"Expiration\": \"ISO8601 timestamp when the credentials expire\"\n}
The Expiration field allows the generated credentials to be cached and reused until they are no more valid (by default the value is 3600s=1h).
Ensures that no credential set is written on your machine in neither the ~/.aws/credentials or ~/.aws/config files.
Ensures your long-running tasks always have valid credentials during their lifecycle.
Is compatible with named-profiles.
Is a way to make third-party tool compatible with AWS SSO and SAML Federated IAM Principals even if they don't support them natively.
As stated by this article by Ben Kehoe, Credential Process is a good way to avoid cluttering the credential file with temporary credentials.
Warning
Temporary credentials in the credentials file reduce potential blast radius in case of machine exploit but they require to be refreshed every time they expire.
"},{"location":"security/credential-process/#how-leapp-works-with-credential-process","title":"How Leapp works with Credential Process","text":"
Info
Requirements: this credentials generation method requires that both Leapp desktop app and CLI are installed.
1) Open your Leapp desktop app and go to the settings panel ().
2) In the general section change the AWS Credential Generation from \"credential-file-method\" to \"credential-process-method\".
3) An informative panel will show up telling that you need the CLI installed (see below), click on \"I acknowledge it\"
warning modal
4) Now, everytime you click on start () an entry will be created in the ~/.aws/config file with the following format:
5) You can start more than one session, depending on how many named-profile you've created; for every session started with a unique named-profile, a new entry will be created in the config file.
Info
AWS CLI, SDks, and third-party tools that can read credentials from the config file can reach AWS services with this method.
Leapp is built with a security-first approach. Every piece of information that has to be persisted is encrypted and saved on your workstation.
We devised two main methods to store data, based on its sensitiveness.
Data Persistence and encryption Examples Operational All information used to make Leapp work, not strictly tied to direct access to cloud environments. Stored and encrypted in a configuration file within the user workspace. Named profiles, proxy configurations, etc. Sensitive Information that can be used, or potentially exploited, to gain access to cloud environments. Stored in the System Vault, leveraging its own integrated encryption. Static credentials, access tokens, cached data, etc."},{"location":"security/intro/#end-to-end-encryption","title":"End-to-end Encryption","text":"
We leverage Zero-Knowledge to provide end-to-end encryption on tiers that require to save your data outside of your workstation to deliver specific features.
Zero Knowledge is designed so that no one, except you, can access your secured data.
Warning
We CAN'T access your data under any circumstances, even if you ask us to!
Information that can be used, or potentially exploited, to gain access to cloud environments are stored your workstation's System Vault, leveraging its own integrated encryption. The user can access the secrets stored in the System Vault at any time, using their user password.
Leapp uses Keytar as an interface to the secure vault on macOS, Windows and Linux systems.
Every key is stored in the vault under the name Leapp. In the description, you will find the underlying name used by Leapp to retrieve the secret.
"},{"location":"security/system-vault/#supported-system-vaults","title":"Supported System Vaults","text":"OS System Vault MacOS Keychain Windows Credential Vault Linux API/Libsecret
Info
We're currently supporting only System Vaults installed by default on the OS. We're planning on extending support to other vaults and online password managers (LastPass, BitWarden, 1Password, etc.). If you'd like other services to be supported feel free to open an Issue or make a Pull Request (check our contributing guidelines).
To persist your configuration online, we implemented Zero-Knowledge encryption to prevent access to your information. But how can you trust a company to keep all of your secrets secret? The answer lies in end-to-end encryption, which lays the groundwork for applications with Zero-Knowledge architectures.
Zero-knowledge refers to policies and architecture that eliminate the possibility for secret managers themselves to access your password.
Warning
This is implemented to save your configuration online in the PRO and TEAM versions of Leapp. Don't know yet about the PRO and TEAM versions? Check our roadmap.
Info
This same process is leveraged by Bitwarden to store their password.
"},{"location":"security/zero-knowledge/#users-have-key-control","title":"Users have key control","text":"
When users have complete control of the encryption key, they control access to the data, providing encrypted information to Leapp without Leapp having access to or knowledge of that data.
Info
To know more about this, you can find the whitepaper on which we based our implementation of Zero-Knowledge end-to-end encryption.
During any phase of the registration and login process the client does not provide any password-related info to the server.
The server does not store any information that can be used to guess the password in a convenient way. In other words, the system must not be prone to brute force or dictionary attacks.
Any sensible data is encrypted client-side, the server will work with encrypted blocks only.
All the implementation is released as open-source.
Temporary security credentials created by AssumeRoleWithSAMLResponse last for one hour. However, you can use the optional DurationSeconds parameter to specify the duration of your session.
Your role session lasts for the specified duration, or until the time specified in the SAML authentication response's SessionNotOnOrAfter value, whichever is shorter. You can provide a DurationSeconds value from 900 seconds (15 minutes) up to the maximum session duration setting for the role. This setting can have a value from 1 hour to 12 hours.
Leapp sets the token duration to 1 hour.
Info
\u26a0\ufe0f In this case, generated credentials are not \"cached\" in the keychain.
The GetSessionToken operation must be called by using the long-term AWS security credentials of the AWS IAM user. Credentials that are created by IAM users are valid for the duration that you specify. This duration can range from 900 seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours), with a default of 43,200 seconds (12 hours). Credentials based on account credentials can range from 900 seconds (15 minutes) up to 3,600 seconds (1 hour), with a default of 1 hour.
Leapp sets the token duration to 10 hours.
Info
These are the only temporary credentials that are stored in the System vault and not rotated, unless expired.
The access token is valid for 8 hours as noted in the expiresAt timestamp in the JSON file. Expired tokens must be re-authenticated using the get-role-credentials API call.
Azure generates a set of access and refresh tokens that are put inside the msal_token_cache.json file inside the .azure directory. Following is the procedure used to generate a set of credentials.
Info
In Windows OS the msal_token_cache is persisted on an encrypted file with dpapi API. Starting from release 2.30 of Azure CLI, credentials are no more persisted in the original accessToken.json
Azure Users profile info is saved in the azureProfile.json file inside the .azure directory.
Before accessing Azure sessions, you now have to create an Azure integration. After that, these are the steps required to log in and then retrieve Azure sessions.
msal_token_cache and azureProfile.json files are cleaned for security reasons.
We execute az login --tenantId <TENANTID>. We do this to obtain the updated user profile and the refresh token (associated to this integration).
We extract all the Azure subscriptions associated with the integration and for each one we map a Leapp Azure session.
We extract the refresh token, account, and profile information from msal_token_cache and azureProfile.json and persist them in the System's vault.
We also remove the previous information from the original files, to increase security and avoid external tampering.
In the current version of Leapp we can only start one Azure session at a time.
For each subscription retrieved upon login to a specific integration, we define a new Leapp Azure Session. To start an Azure session we follow these steps.
Recover refresh token, account, and profile information from the Vault and we use them alongside sessionId (Subscription id) in the start operation.
azureProfile.json is only filled with profile information from the current subscription.
We write the account information and the refresh token back in the msal_token_cache
We execute az account get-access-token --subscriptionId <SUBSCRIPTIONID>, to retrieve the access token and the id token of the subscription.
The previous command also writes access and id token back to the msal_token_cache file.
We update the expiration time of the session to the current datetime.
We update the refresh token in the Vault with the new information.
We remove the refresh token from the msal_token_cache.
We finally start the session.
Info
The refresh token is a long term credential that potentially lasts for 90 days. The access token is a short term credential and lasts for 70 minutes. Source
Please always add logs to any issue you want to fill whenever possible, so you can help the team identify the problem quickly
"},{"location":"troubleshooting/faq/","title":"FAQ","text":""},{"location":"troubleshooting/faq/#im-using-the-open-source-app-do-you-store-my-data-online","title":"I'm using the open-source app, do you store my data online?","text":"
NO.
The open-source software doesn't transfer, persist, or share anything with other services. All your data is secured and encrypted on your workstation.
Nobody can access it, not even ourselves.
"},{"location":"troubleshooting/faq/#ive-got-a-paid-tier-how-do-you-manage-my-data-can-you-access-it","title":"I've got a paid tier, how do you manage my data? Can you access it?","text":"
We can't and don't want to see any of your access data.
We need to store your data online to enable some features (syncing, managing other users, etc.) but we implement a Zero-Knowledge encryption system that prevents even ourselves to access your data.
"},{"location":"troubleshooting/faq/#i-dont-feel-secure-using-a-built-in-window-for-authentication-cant-you-use-the-default-browser","title":"I don't feel secure using a built-in window for authentication, can't you use the default browser?","text":"
In the future, Leapp will only use the default browser to authenticate. Right now, this is a compromise to deliver the authentication flow. We already ported the AWS SSO authentication flow on the default browser, and we're working on migrating the other ones as soon as possible.
"},{"location":"troubleshooting/faq/#how-can-i-find-leapp-data-in-the-system-vault","title":"How can I find Leapp data in the System Vault?","text":"
Every key stored by Leapp in the vault is named Leapp. The account name shows the description of the element saved by our software.
"},{"location":"troubleshooting/faq/#where-do-i-find-the-leapp-logs","title":"Where do I find the Leapp logs?","text":"
Head to the Application data section.
"},{"location":"troubleshooting/faq/#ssm-terminal-is-opening-but-no-session-is-starting-what-can-i-do","title":"SSM terminal is opening but no session is starting, what can I do?","text":"
Just close the terminal and relaunch the SSM command.
"},{"location":"troubleshooting/faq/#aws-cli-or-az-cli-is-installed-but-leapp-cant-find-it-what-can-i-do","title":"AWS CLI (or AZ CLI) is installed but Leapp can't find it, what can I do?","text":"
Leapp on macOS works in sandbox mode, so some terminal commands must be symlinked in order to work on some installations. Just make a symlink pointing from /usr/local/bin/aws to the actual aws binary or, for AZ CLI, from /usr/local/bin/az to the actual az binary. To create symlinks on macOS, use this command ln -s /any/file/on/the/disk linked-file. The command is called ln. If used with the option -s it will create a symbolic link in the current directory.
"},{"location":"troubleshooting/faq/#i-use-leapp-session-current-but-want-to-see-the-alias-and-not-the-id","title":"I use leapp session current but want to see the alias and not the id.","text":""},{"location":"troubleshooting/faq/#setting-up-leappalias-command","title":"Setting up leappalias command","text":"
Follow these steps to set up the leappalias command in your Zsh shell:
Create a script file named leappalias.sh using a text editor:
Save the file and make it executable by running the following command in the terminal:
chmod +x leappalias.sh\n
Move the script to a directory in your system's PATH. For example, /usr/local/bin/:
sudo mv leappalias.sh /usr/local/bin/leappalias\n
Open your zshrc file using a text editor:
nano ~/.zshrc\n
Define an alias for executing the script by adding the following line to the zshrc file:
alias leappalias='/usr/local/bin/leappalias'\n
Save the changes and close the zshrc file.
Reload the zshrc file in the terminal using the following command:
source ~/.zshrc\n
Once you have completed these steps, you can use the leappalias command in your terminal to extract and display the alias from the output of leapp session current. Credit goes to bspansinQdo.
"},{"location":"troubleshooting/faq/#how-can-i-add-support-to-a-new-saml-20-identity-provider","title":"How can I add support to a new SAML 2.0 Identity Provider?","text":"
To add support to a new SAML 2.0 Identity Provider, you have to perform the following steps:
create a Fork of the Noovolari/leapp GitHub repository;
create a Pull Request and set up your local environment following Install dependencies and build packages section of the DEVELOPMENT.md;
add the Identity Provider-specific authentication URL RegEx filter to the Leapp Core authenticationUrlRegexes Map;
follow the last part of the Install dependencies and build packages section of the DEVELOPMENT.md to build the solution for both the CLI and the Desktop App;
push your changes to your forked repository and propose to merge them to the main repository.
If you need more details about the implementation, please check the How to add a new SAML IdP preset authentication URL section of the DEVELOPMENT.md.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Overview","text":""},{"location":"#overview","title":"Overview","text":""},{"location":"#welcome-to-leapp","title":"Welcome to Leapp","text":"
Leapp is a tool for developers to manage, secure, and access the cloud.
All data is persisted and encrypted on your workstation. Head to our Security section to know how we guarantee the highest level of security.
Leapp Main Window
The name Leapp is based on the word leap and is pronounced /l:ip/. We chose this name because the project enables you to be one step away from your cloud environments.
"},{"location":"edit-session/","title":"Editing a session","text":"
Leapp allows the user to edit an existing session excluding those generated from an AWS integration.
Info
Integration derived Sessions can\u2019t be changed
To edit an existing session just right-click on a session in the Leapp list (see below), and select \"edit session\". A new modal will appear, allowing the user to choose which parameters to change.
edit session
Below are the configuration options for every type of session:
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Mfa Device (optional): can be left empty or, if you add a valid device name or AWS ARN, it will prompt a modal for MFA code
Access Key ID: Replace your session Access Key ID in the system vault
Secret Access Key: Replace your session Secret Access Key in the system vault
"},{"location":"edit-session/#iam-role-chained","title":"IAM Role Chained","text":"
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Role ARN: The role that you'll assume when chaining from an assumer window
Role Session Name: (optional), it will be used to identify the chained session
Assumer Session: select a session from the list, it will be the Principal assuming the role
Info
You can also generate a new IAM Role Chained session from any other AWS session by right-clicking on a session and chosing \"Create Chained Session\"
"},{"location":"edit-session/#iam-role-federated","title":"IAM Role Federated","text":"
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Role ARN: Role of the Principal in AWS
SAML 2.0 Url: Federated URL needed for authentication to AWS
Identity Provider: the identity provider ARN that you have set up on AWS
After modifying all the parameters, a user can test their validity with test credential generation:
Clicking this button allows Leapp to do a dry run on your parameters, and if valid, a new set of credentials will be generated (but not used) and an informative toast will appear to tell you that they can be used successfully.
"},{"location":"edit-session/#how-we-handle-secrets-when-editing-a-session","title":"How we handle Secrets when Editing a Session","text":"
No secrets will be saved in plain text on your machine. Leapp saves secrets by replacing values in the system keychain, using a combination of an informative name plus the session hidden id.
This way we reduce potential blast radius of an attacker tampering your machine.
When editing a session, Leapp will hide your secrets and you are also unable to copy/paste them from the App.
This section provides an overview of Leapp's integrations, useful to extend the functionality of Leapp to 3rd party services.
Integrations help manage access and identities on your service of choice while using Leapp during your daily activities. They are automatically mapped into Sessions.
Integrations have four main actions available: Create, Delete, Sync, and Logout.
Action Description CREATE Configure a new Integration with the data needed to start the authentication flow. Required to Sync and map the service response into Sessions. DELETE Remove an existing Integration. Removes all the associated Sessions as well and wipes everything related to the Integration from the system (tokens, cache, etc.) SYNC Start the authentication flow to log into the Integration Provider. Leapp will automatically retrieve all the related data and map the response into Sessions. Any change in your service of choice requires a manual Sync to reflect the current status. LOGOUT Disable the Integration. Removes all the Sessions but keeps the Integration data. Running a Sync will restore all the Sessions tied to it."},{"location":"integrations/#supported-services","title":"Supported Services","text":"Service Supported AWS SSO Okta Coming Soon OneLogin Coming Soon AzureAD"},{"location":"sessions/","title":"Sessions","text":""},{"location":"sessions/#sessions","title":"Sessions","text":"
A Session contains all the relevant information to let the dev connect to a cloud provider. Three standard actions should be implemented for each session: start, stop, and rotate.
"},{"location":"sessions/#actions","title":"Actions","text":"Method Description START \u00a0Make the temporary credentials available to the provider chain STOP \u00a0Removes the temporary credentials from the provider chain ROTATE \u00a0Generate new temporary credentials, and substitute the previous ones in the provider chain
The process of setting up Leapp Sessions is managed either manually, for each access method, or through integrations with third-party tools. Leapp stores all the Sessions available to the users locally, inside a configuration file called Workspace.
A Workspace is a global configuration that contains all the relevant information about your Leapp setup (sessions, integrations, app preferences, etc.).
There are two types of workspace: Local and Remote.
A Local workspace is the default workspace that comes with your Leapp installation. It's a private configuration that contains your personal preferences and all sessions and integrations that you created yourself.
A local workspace is associated to a single machine and if you need to migrate your configuration to another one you will have to do it manually.
A Remote workspace is a Leapp Team configuration set created remotely by a Leapp Team manager.
When you sync a remote workspace, you will receive sessions and integrations automatically, without having to configure them yourself.
A remote workspace is persisted online by using Zero-Knowledge encryption.
You will have access to the same configurations instantly on any machine, by logging in to your Leapp Team account after having been invited by your Leapp Team manager.
Info
Both your local and remote workspaces are saved on your machine as encrypted files inside your /.Leapp directory.
The actions below only applies to Remote workspaces.
Action Description Sign-in \u00a0Connect to a Remote workspace. This action will not switch your Local workspace Switch \u00a0Switch to the selected workspace by clicking on its name in the workspace menu Lock \u00a0Switch back to the Local workspace disabling all the Remote ones Sign-out \u00a0Sign-out from a Remote workspace removing all your login details
Info
The Lock action also removes the encrypted files associated to your remote workspaces.
"},{"location":"built-in-features/aws-ec2-connect/","title":"Configure AWS EC2 Connect","text":""},{"location":"built-in-features/aws-ec2-connect/#what-is-aws-ec2-connect","title":"What is AWS EC2 Connect","text":"
Amazon EC2 Instance Connect is a simple and secure way to connect to your instances using Secure Shell (SSH). With EC2 Instance Connect, you can control SSH access to your instances using AWS Identity and Access Management (IAM) policies as well as audit connection requests with AWS CloudTrail events.
"},{"location":"built-in-features/aws-ec2-connect/#how-to-configure-aws-ec2-connect-in-leapp","title":"How To configure AWS EC2 Connect in Leapp","text":"
Warning
If your Leapp Desktop App is warning you that you're missing the AWS Session Manager Plugin, please install it following this official guide.
You can directly connect to an AWS EC2 instance from Leapp through AWS System Manager (AWS SSM).
Info
To setup SSM follow this SSM guide on AWS guide.
example image from AWS
To correctly connect follow these steps:
Right-click on a suitable AWS session to open the contextual menu.
Click on View SSM sessions.
Select the AWS region in which your instance is located.
Wait for Leapp to load your instances.
Select the instance and click connect.
Wait for the terminal to open.
Focus the terminal window and write /bin/bash; press Enter and you'll be inside the terminal of your instance.
If the user is not granted the right permissions, the operation will fail and Leapp will throw an error message.
"},{"location":"built-in-features/aws-named-profiles/","title":"Configure Named Profiles","text":""},{"location":"built-in-features/aws-named-profiles/#what-is-a-named-profile","title":"What is a Named Profile","text":"
Named Profiles are used by AWS to maintain more than one set of active credentials for you to use with AWS-CLI, SDK, or other third-party tools. Named profiles are stored in ~/.aws/credentials file in the ini file format.
Named Profiles have a default profile which is the one you get from aws configure command.
With Leapp you can group and activate more than one credential set at a time through Named Profiles.
"},{"location":"built-in-features/aws-named-profiles/#how-to-configure-a-named-profile-in-leapp","title":"How to configure a Named Profile in Leapp","text":"
Named Profiles can be created in 3 ways:
Option PanelWhen creating a new SessionEdit Profile in Contextual Menu
Click on the gear icon and select the Profiles tab. Insert the name of the new Named Profile in the input form, then click on the plus icon.
When creating a new session, the user will have the option to choose a Named Profile or add a new one.
Right-click on a session and select Change then Named Profile: an option to select or add a new Named Profile will be available.
The new name is directly added to the Named Profile list and can then be used for other sessions too.
Info
AWS SSO sessions will have the Named Profile default when obtained via Login or Sync. To change the Named Profile associated to a session you have to use the \"Change Profile\" option in the session list.
Named profiles can be managed from the Option menu.
In the Option menu, under the Profiles tab, you can add or edit a new Named Profile, and you can also remove unwanted ones. When removing a Named Profile, Leapp will warn you about which sessions are using that profile, and those sessions will be reverted to the default Named Profile.
The input form can be used to add or edit a Named Profile: if it's empty, you can use it to add a new named profile. When selecting the button, you will be able to edit the name of the Named Profile from within the input form.
Warning
Remember that when you change the profile of a session, the session will be immediately put in stop mode. That's because Leapp would have to change the credential file, so you will need to restart the session again.
Once you've opened the Leapp option menu - which can be accessed by clicking the top right gear icon - you can edit the following settings in the General tab
This option allows you to set the default AWS or Azure region/location for every new session.
Each time you create a new session, this will be the default region assigned to it.
You can still change it if you need a different one, by selecting a different region while creating the session or by changing the region once a session is created.
This option is used to select the terminal in which to open an SSM session.
Info
This setting is currently only available on MacOS. If you want to contribute and add a new terminal for a specific OS, please refer to the contributing guide
This option is used to set the default Webconsole session duration in hours.
Info
The minimum session duration is 1 hour, and can be set to a maximum of 12 hours. Set session duration
"},{"location":"built-in-features/multi-console/","title":"Configure Multi Console","text":""},{"location":"built-in-features/multi-console/#what-is-multi-console","title":"What is Multi Console","text":"
The Leapp Multi-Console Browser Extension allows you to open multiple instances of the AWS Web Console in the same browser window and helps you in managing them.
Get it on Firefox \u21e9 Get it on Chrome \u21e9"},{"location":"built-in-features/multi-console/#list-of-supported-browsers","title":"List of Supported Browsers","text":"Browser Supported Firefox Chrome Edge Brave Safari"},{"location":"built-in-features/multi-console/#how-to-configure-multi-console-in-leapp","title":"How to Configure Multi Console in Leapp","text":""},{"location":"built-in-features/multi-console/#install-the-extension","title":"Install the Extension","text":""},{"location":"built-in-features/multi-console/#firefox","title":"Firefox","text":"
You can get the extension on the official Mozilla Addons Store and install it from there:
Visit the page by clicking the button below
Then Click on Add to Firefox
Get it on Firefox \u21e9
"},{"location":"built-in-features/multi-console/#chrome-edge-and-other-chromium-based-browsers","title":"Chrome, Edge and other Chromium based browsers","text":"
Info
Because the extension at the moment relies on Manifest V2, we are unable to upload the extension on the official stores. For more info see Chrome extension documentation
The extension can only be installed manually. To do so, follow these instructions:
Download the zip archive by clicking on the button below
Unzip the file
Open your browser and navigate to about://extensions
Enable Developer mode in the top right corner
Then click on Load unpacked in the top left corner
Finally, Select the folder extracted previously
Get it on Chrome/Others \u21e9
"},{"location":"built-in-features/multi-console/#uninstall-the-extension","title":"Uninstall the Extension","text":""},{"location":"built-in-features/multi-console/#firefox_1","title":"Firefox","text":"
Visit about:addons
Select Leapp Browser Extension and click on the 3 dots
Click on Remove
"},{"location":"built-in-features/multi-console/#chrome-edge-and-other-chromium-based-browsers_1","title":"Chrome, Edge and other Chromium based browsers","text":"
Visit about://extensions
Search for Leapp Browser Extension and click on Remove
See warning section below
Warning
If you are using the Chrome version and you uninstalled or disabled the extension, you have to manually clear cookies for the AWS Console. To do so, when accessing the login page of the AWS Console, on the left of the address bar, click the lock icon and select \"Cookies\". Then, remove all cookies by clicking \"Remove\" until the cookie list is empty and finally click on Done
"},{"location":"built-in-features/multi-console/#how-to-use-it","title":"How to use it","text":"
Once you've installed the extension on your browser, you need to enable the Multi-Console Extension on the Leapp Desktop App in order to use it.
Click on the top-right cog icon to access the settings, click on the Multi-Console tab and then click Enable Multi-Console Extension.
enable option
From the contextual menu of a session (accessed by right-clicking on it), simply select Open Web Console.
Info
If any communication error occurs, your browser is not open or you don't have the extension installed/enabled on it, the web console will be opened in your default browser without using the extension (and will be limited to a single session).
By clicking on the Leapp Multi-Console Extension icon in your browser, a list of all currently active sessions will be shown.
This list contains information obtained from Leapp about the session, including Session Name, Session Role and Session Region.
leapp browser ui
In the extension interface, click on a row to select and focus the tab in which you opened the related AWS Console, so you can easily navigate among many AWS Consoles at the same time.
"},{"location":"built-in-features/opening-web-console/","title":"Configure Open Web Console","text":""},{"location":"built-in-features/opening-web-console/#what-is-open-web-console","title":"What is Open Web Console","text":"
Open Web Console is a Leapp feature that allows you to open the AWS Web Console of a session that you've created in Leapp.
"},{"location":"built-in-features/opening-web-console/#how-to-configure-open-web-console-in-leapp","title":"How to Configure Open Web Console in Leapp","text":"
You can open the AWS Web Console directly from Leapp, without having to log in, input your credentials, or select the role to assume.
To do that just right-click or select the session you want to open in the web console, and click on the icon either in the context-menu or in the bottom-bar below.
Alternatively, you can Command + left-click on a session (or Control + left-click for Windows/Linux ) to open the web console.
Leapp will open your default browser with the Region and the Role already prepared for you in the account you've selected.
note: to use this feature correctly, remember to logout from any web console already opened in the browser.
note: the feature currently is available for IAM Role Federated Sessions, Single Sign-On Sessions, and IAM Role Chained Sessions.
"},{"location":"cli/","title":"Index","text":"
Leapp's Command Line Interface.
Warning
Leapp CLI works only if the Desktop App is installed and running. Note that version >= v0.11.0 of the Desktop App is required. Check the installation guide to install the Desktop App.
"},{"location":"cli/scopes/help/#leapp-help-commands","title":"leapp help [COMMANDS]","text":"
Display help for leapp.
USAGE\n $ leapp help [COMMANDS] [-n]\n\nARGUMENTS\n COMMANDS Command to show help for.\n\nFLAGS\n -n, --nested-commands Include all nested commands in the output.\n\nDESCRIPTION\n Display help for leapp.\n
USAGE\n $ leapp idp-url delete [--idpUrlId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --idpUrlId=<value> the idp url id that we want to pass to the function like the delete one\n\nDESCRIPTION\n Delete an identity provider URL\n\nEXAMPLES\n $leapp idp-url delete\n\n $leapp idp-url delete --idpUrlId ID\n\n $leapp idp-url delete --idpUrlId ID [--force, -f]\n
USAGE\n $ leapp idp-url edit [--idpUrlId <value>] [--idpUrl <value>]\n\nFLAGS\n --idpUrl=<value> the idp url address we want to create\n --idpUrlId=<value> the idp url id that we want to pass to the function like the delete one\n\nDESCRIPTION\n Edit an identity provider URL\n\nEXAMPLES\n $leapp idp-url edit\n\n $leapp idp-url edit --idpUrlId ID --idpUrl ADDRESS\n
USAGE\n $ leapp idp-url list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show identity providers list\n\nEXAMPLES\n $leapp idp-url list\n
USAGE\n $ leapp integration create [--integrationAlias <value>] [--integrationPortalUrl <value>] [--integrationRegion <value>]\n [--integrationType AWS-SSO|AZURE] [--integrationTenantId <value>] [--integrationLocation <value>]\n\nFLAGS\n --integrationAlias=<value> alias that identifies an integration\n --integrationLocation=<value> Location of an Azure Integration\n --integrationPortalUrl=<value> url that identifies the integration portal where you authenticate\n --integrationRegion=<value> an AWS valid region code for the integration\n --integrationTenantId=<value> Tenant ID of an Azure Integration\n --integrationType=<option> Identify the type of your integration. Valid types are [AWS-SSO, AZURE]\n <options: AWS-SSO|AZURE>\n\nDESCRIPTION\n Create a new integration\n\nEXAMPLES\n $leapp integration create\n\n $leapp integration create --integrationType AWS-SSO --integrationAlias ALIAS --integrationPortalUrl URL --integrationRegion REGION\n\n $leapp integration create --integrationType AZURE --integrationAlias ALIAS --integrationTenantId TENANT --integrationLocation LOCATION\n
USAGE\n $ leapp integration delete [--integrationId <value>]\n\nFLAGS\n --integrationId=<value> the Integration Id used to identify the integration inside Leapp\n\nDESCRIPTION\n Delete an integration\n\nEXAMPLES\n $leapp integration delete\n\n $leapp integration delete --integrationId ID\n
USAGE\n $ leapp integration list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show integrations list\n\nEXAMPLES\n $leapp integration list\n
USAGE\n $ leapp integration logout [--integrationId <value>]\n\nFLAGS\n --integrationId=<value> the Integration Id used to identify the integration inside Leapp\n\nDESCRIPTION\n Logout from an integration\n\nEXAMPLES\n $leapp integration logout\n\n $leapp integration logout --integrationId ID\n
USAGE\n $ leapp profile create [--profileName <value>]\n\nFLAGS\n --profileName=<value> an AWS named profile Alias used to identify the profile in both config and credential file\n\nDESCRIPTION\n Create a new AWS named profile\n\nEXAMPLES\n $leapp profile create\n\n $leapp profile create --profileName PROFILENAME\n
USAGE\n $ leapp profile delete [--profileId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --profileId=<value> an AWS named profile ID in Leapp\n\nDESCRIPTION\n Delete an AWS named profile\n\nEXAMPLES\n $leapp profile delete\n\n $leapp profile delete --profileId PROFILEID\n\n $leapp profile delete --profileId PROFILEID [--force, -f]\n
USAGE\n $ leapp profile edit [--profileId <value>] [--profileName <value>]\n\nFLAGS\n --profileId=<value> an AWS named profile ID in Leapp\n --profileName=<value> an AWS named profile Alias used to identify the profile in both config and credential file\n\nDESCRIPTION\n Rename an AWS named profile\n\nEXAMPLES\n $leapp profile edit\n\n $leapp profile edit --profileId ID --profileName PROFILENAME\n
USAGE\n $ leapp profile list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show profile list\n\nEXAMPLES\n $leapp profile list\n
"},{"location":"cli/scopes/region/#leapp-region-get-default","title":"leapp region get-default","text":"
Displays the default region
USAGE\n $ leapp region get-default\n\nDESCRIPTION\n Displays the default region\n\nEXAMPLES\n $leapp region get-default\n
"},{"location":"cli/scopes/region/#leapp-region-set-default","title":"leapp region set-default","text":"
Change the default region
USAGE\n $ leapp region set-default [--region <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n\nDESCRIPTION\n Change the default region\n\nEXAMPLES\n $leapp region set-default\n\n $leapp region set-default --region AWSREGION\n
USAGE\n $ leapp session add [--providerType aws] [--accessKey <value>] [--idpArn <value>] [--idpUrl <value>]\n [--mfaDevice <value>] [--sessionName <value>] [--parentSessionId <value>] [--profileId <value>] [--region <value>]\n [--roleArn <value>] [--roleSessionName <value>] [--secretKey <value>] [--sessionType\n awsIamRoleFederated|awsIamUser|awsIamRoleChained]\n\nFLAGS\n --accessKey=<value> AWS Access Key ID of the IAM User\n --idpArn=<value> AWS IAM Federated Role IdP Arn value, obtain it from your AWS Account\n --idpUrl=<value> the idp url address we want to create\n --mfaDevice=<value> MFA Device Arn retrieved from your AWS Account\n --parentSessionId=<value> For AWS IAM Role Chained is the session Id of the session that will assume the chained\n role. Retrieve it using $leapp session list -x\n --profileId=<value> an AWS named profile ID in Leapp\n --providerType=<option> Identify the provider for your sessions. Valid types are [aws]\n <options: aws>\n --region=<value> Session Region for AWS sessions in Leapp\n --roleArn=<value> AWS IAM Federated Role Arn value, obtain it from your AWS Account\n --roleSessionName=<value> Optional Alias for the Assumed Role Session name\n --secretKey=<value> AWS Secret Access Key of the IAM User\n --sessionName=<value> Session Alias to identify the session in Leapp\n --sessionType=<option> Identify the AWS session type. Valid types are [awsIamRoleFederated, awsIamUser,\n awsIamRoleChained]\n <options: awsIamRoleFederated|awsIamUser|awsIamRoleChained>\n\nDESCRIPTION\n Add a new session\n\nEXAMPLES\n $leapp session add\n\n $leapp session add --providerType [aws] --sessionType [awsIamRoleFederated, awsIamRoleChained, awsIamUser] --region [AWSREGION] --sessionName NAME ...[combination of flags relative to the session]\n\n $leapp session add --providerType aws --sessionType awsIamRoleFederated --sessionName NAME --region AWSREGION --idpArn IDPARN --idpUrl IDPURL --profileId PROFILEID --roleArn ROLEARN\n\n $leapp session add --providerType aws --sessionType awsIamRoleChained --sessionName NAME --region AWSREGION --profileId PROFILEID --roleArn ROLEARN --parentSessionId ID (--roleSessionName ROLESESSIONNAME)\n\n $leapp session add --providerType aws --sessionType awsIamUser --sessionName NAME --region AWSREGION --profileId PROFILEID --accessKey ACCESSKEY --secretKey SECRETKEY (--mfaDevice MFADEVICEARN)\n
USAGE\n $ leapp session change-profile [--sessionId <value>] [--profileId <value>]\n\nFLAGS\n --profileId=<value> an AWS named profile ID in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Change a session named-profile\n\nEXAMPLES\n $leapp session change-profile\n\n $leapp session change-profile --profileId PROFILEID --sessionId SESSIONID\n
USAGE\n $ leapp session change-region [--sessionId <value>] [--region <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Change a session region\n\nEXAMPLES\n $leapp session change-region\n\n $leapp session change-region --sessionId SESSIONID --region REGION\n
Provides info about the current active session for a selected profile (if no profile is provided, it uses the profile default)
USAGE\n $ leapp session current [-i] [-p <value>] [-r aws|azure] [-f <value>]\n\nFLAGS\n -f, --format=<value> allows formatting data to show\n - aws -> id alias, accountNumber, roleArn\n - azure -> id tenantId, subscriptionId\n -i, --inline\n -p, --profile=<value> [default: default] aws named profile of which gets info\n -r, --provider=<option> filters sessions by the cloud provider service\n <options: aws|azure>\n\nDESCRIPTION\n Provides info about the current active session for a selected profile (if no profile is provided, it uses the profile\n default)\n\nEXAMPLES\n $leapp session current --format \"alias accountNumber\" --inline --provider aws\n
USAGE\n $ leapp session delete [--sessionId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Delete a session\n\nEXAMPLES\n $leapp session delete\n\n $leapp session delete --sessionId SESSIONID\n\n $leapp session delete --sessionId SESSIONID [--force, -f]\n
Generate STS temporary credentials for the given AWS session id
USAGE\n $ leapp session generate SESSIONID\n\nARGUMENTS\n SESSIONID id of the session\n\nDESCRIPTION\n Generate STS temporary credentials for the given AWS session id\n\nEXAMPLES\n $leapp session generate 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d\n
Show sessions list with all properties; filter query is case sensitive
USAGE\n $ leapp session list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show sessions list with all properties; filter query is case sensitive\n\nEXAMPLES\n $leapp session list\n\n $leapp session list --filter=\"ID=Foo\" -x\n\n $leapp session list --filter=\"Session Name=Foo\"\n\n $leapp session list --filter=\"Type=Foo\"\n\n $leapp session list --filter=\"Named Profile=Foo\"\n\n $leapp session list --filter=\"Region/Location=Foo\"\n\n $leapp session list --filter=\"Status=Foo\"\n
USAGE\n $ leapp session open-web-console [--sessionId <value>] [-p]\n\nFLAGS\n -p, --print Print an AWS Web Console login URL in the terminal instead of opening the web browser\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Open an AWS Web Console\n\nEXAMPLES\n $leapp session open-web-console\n\n $leapp session open-web-console --sessionId SESSIONID [--print, -p]\n
USAGE\n $ leapp session run-aws-credential-plugin [--sessionId <value>] [--pluginName <value>]\n\nFLAGS\n --pluginName=<value> Unique name of a Leapp Plugin\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Run a Leapp Plugin\n\nEXAMPLES\n $leapp session run-plugin\n\n $leapp session run-plugin --sessionName SESSIONAME --pluginName PLUGINNAME\n
USAGE\n $ leapp session start [SESSIONNAME] [--sessionId <value>] [--sessionRole <value>] [--noInteractive]\n\nARGUMENTS\n SESSIONNAME Name of the Leapp session\n\nFLAGS\n --noInteractive If the specified session is not unique or doesn't exist, throw an error without starting the\n interactive session selection mode\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --sessionRole=<value> Session Role of one or more sessions in Leapp\n\nDESCRIPTION\n Start a session\n\nEXAMPLES\n $leapp session start\n\n $leapp session start SESSIONNAME\n\n $leapp session start SESSIONNAME --sessionRole SESSIONROLE\n\n $leapp session start SESSIONNAME --noInteractive\n\n $leapp session start --sessionId SESSIONID\n
USAGE\n $ leapp session start-ssm-session [--sessionId <value>] [--region <value>] [--ssmInstanceId <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --ssmInstanceId=<value> Instance ID for EC2 instance we want to access with SSM\n\nDESCRIPTION\n Start an AWS SSM session\n\nEXAMPLES\n $leapp session start-ssm-session\n\n $leapp session start-ssm-session --sessionId SESSIONID --region AWSREGION --ssmInstanceId EC2INSTANCEID\n
USAGE\n $ leapp session stop [SESSIONNAME] [--sessionId <value>] [--sessionRole <value>] [--noInteractive]\n\nARGUMENTS\n SESSIONNAME Name of the Leapp session\n\nFLAGS\n --noInteractive If the specified session is not unique or doesn't exist, throw an error without starting the\n interactive session selection mode\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --sessionRole=<value> Session Role of one or more sessions in Leapp\n\nDESCRIPTION\n Stop a session\n\nEXAMPLES\n $leapp session stop\n\n $leapp session stop SESSIONNAME\n\n $leapp session stop SESSIONNAME --sessionRole SESSIONROLE\n\n $leapp session stop SESSIONNAME --noInteractive\n\n $leapp session stop --sessionId SESSIONID\n
USAGE\n $ leapp set-workspace [WORKSPACENAME]\n\nARGUMENTS\n WORKSPACENAME name of the Leapp Team remote workspace or local\n\nDESCRIPTION\n Set the current Leapp workspace\n\nEXAMPLES\n $leapp team set-workspace\n\n $leapp team set-workspace local\n\n $leapp team set-workspace WORKSPACE-NAME\n
USAGE\n $ leapp workspace\n\nDESCRIPTION\n Show the current workspace\n\nEXAMPLES\n $leapp workspace\n
See code: dist/commands/workspace.ts
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/","title":"Configure an AWS Identity Center (ex AWS Single Sign-On) integration","text":""},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#what-is-aws-identity-center-ex-aws-single-sign-on","title":"What is AWS Identity Center (ex AWS Single Sign-On)","text":"
AWS Identity Center (ex AWS Single Sign-On) is a cloud service that allows you to grant your users access to AWS resources across multiple AWS accounts.
AWS SSO provides a directory that you can use to create users, organize them in groups, and set permissions across those groups; alternatively, you can obtain them from your Microsoft Active Directory or any standards-based identity provider, such as Okta Universal Directory or Azure AD.
After logging in the first time, Leapp will map all your roles and users into Sessions.
Info
To get started using AWS SSO refer to this guide.
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#how-to-configure-an-aws-identity-center-ex-aws-single-sign-on-integration-in-leapp","title":"How to configure an AWS Identity Center (ex AWS Single Sign-On) integration in Leapp","text":"
Click on the Add Integration button in the sidebar.
Select AWS Single Sign-On as the Integration type.
Provide the required information (described in the next section).
Click on the Add integration button.
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#required-information","title":"Required information","text":"Field Description INTEGRATION TYPE Set as AWS Single Sign-on AWS SSO URL The portal URL to begin the authentication flow. It usually follows this pattern: d-xxxxxxxxxx.awsapps.com/start. REGION The region on which AWS SSO is administered and configured. This is NOT where your generated credentials will be valid; it's only used for the login part."},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-integration/configure-azure-integration/","title":"Configure an Azure integration","text":""},{"location":"configuring-integration/configure-azure-integration/#what-is-an-azure-integration","title":"What is an Azure integration","text":"
Our Leapp integration refers to Azure Tenant which is a dedicated and trusted instance of Azure AD.
The tenant is automatically created when your organization signs up for a Microsoft cloud service subscription.
These subscriptions include Microsoft Azure, Microsoft Intune, or Microsoft 365.
An Azure tenant represents a single organization and can have multiple subscriptions.
Please refer to How to find your Azure Active Directory tenant ID and other Azure AD documentation for more information.
Warning
For azure-cli users with version < 2.30.0: Leapp no longer supports this version of the CLI. Please update to a newer version.
To create a new Azure Integration, go to the left sidebar of Leapp Desktop and click on the icon. A new modal will be presented with the following option to compile. After submitting the new Integration and have logged into your Azure Portal, Subscriptions will be automatically retrieved and mapped into Leapp Azure Sessions.
"},{"location":"configuring-integration/configure-azure-integration/#how-to-configure-an-azure-integration-in-leapp","title":"How to configure an Azure integration in Leapp","text":"
Click on the Add Integration button in the sidebar.
Select Azure as the Integration type.
Provide the required information (described in the next section).
Click on the Add integration button.
"},{"location":"configuring-integration/configure-azure-integration/#required-information","title":"Required information","text":"Field Description INTEGRATION TYPE Set as Azure ALIAS Your friendly integration name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. TENANT ID A tenant ID identifies a tenant. You can have multiple clients on a given tenant database. LOCATION The Azure datacenters are located around the world in strategic places that best meet the customer demands. These areas are known as Azure locations. Specific services requires the user to select a specific location. The value is retrieved from your default location in general options."},{"location":"configuring-integration/configure-azure-integration/#video-tutorial","title":"Video tutorial","text":"
Info
Azure sessions are not available anymore for direct creation. Instead you can create a new Azure Integration.
"},{"location":"configuring-session/configure-aws-iam-role-chained/","title":"Configure AWS IAM Role Chained","text":""},{"location":"configuring-session/configure-aws-iam-role-chained/#what-is-an-aws-iam-role-chained-session","title":"What is an AWS IAM Role Chained session","text":"
An AWS IAM Role Chained session represents an AWS role chaining access. Role chaining is the process of assuming a role starting from another IAM role or user.
An IAM role has some similarities to an IAM user. Roles and users are both AWS identities with permissions policies that determine what the identity can and cannot do in AWS. However, instead of being uniquely associated with one person, a role is intended to be assumable by anyone who needs it.
A role does not have standard long-term credentials such as a password or access keys associated with it. Instead, when you assume a role, it provides you with temporary security credentials for your role session.
Role chaining occurs when you use a role to assume a second role through the AWS CLI or API, even in other accounts.
Info
Refer to this guide to delegate access across AWS accounts using IAM Roles chaining.
"},{"location":"configuring-session/configure-aws-iam-role-chained/#how-to-configure-an-aws-iam-role-chained-in-leapp","title":"How to configure an AWS IAM Role Chained in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM Role Chained as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-role-chained/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. ROLE ARN Your IAM Role unique ID. The active Session will refer to this Role. ROLE SESSION NAME Your session name. You can query and search this on AWS Cloudtrail or any other linked audit service to find out what action were performed by the linked Identity. ASSUMER SESSION Your session from which this Role will be assumed. The assume-role call will be automatically made by Leapp."},{"location":"configuring-session/configure-aws-iam-role-chained/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-aws-iam-role-federated/","title":"Configure AWS IAM Role Federated","text":""},{"location":"configuring-session/configure-aws-iam-role-federated/#what-is-an-aws-iam-role-federated-session","title":"What is an AWS IAM Role Federated session","text":"
An AWS IAM Role Federated session represents an access type that relies on a federation between an AWS account and an external Identity Provider.
AWS Identity and Access Management (IAM) supports identity federation for delegated access to the AWS Management Console or AWS APIs. With identity federation, external identities are granted secure access to resources in your AWS accounts through IAM roles.
These external identities can come from your corporate identity provider (such as Microsoft Active Directory or from the AWS Directory Service) or from a web identity provider (such as Amazon Cognito, Login with Amazon, Facebook, Google, or any OpenID Connect-compatible provider).
We currently only support SAML 2.0 federation.
Info
Refer to this guide to provision your own federated roles.
Refer to this guide to configure and trust your SAML 2.0 Identity Provider.
Is your SAML 2.0 Identity Provider not included in the above list? Please, refer to the FAQ to add a new one.
"},{"location":"configuring-session/configure-aws-iam-role-federated/#how-to-configure-an-aws-iam-role-federated-in-leapp","title":"How to configure an AWS IAM Role Federated in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM Role Federated as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-role-federated/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. SAML 2.0 URL Your SAML URL interface to start the authentication flow and log into your Identity provider. AWS IDENTIY PROVIDER ARN Your Identity Provider ID in AWS. You can find it in IAM section Identity Providers. ROLE ARN Your IAM Role unique ID. The active Session will refer to this Role."},{"location":"configuring-session/configure-aws-iam-role-federated/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-aws-iam-user/","title":"Configure AWS IAM User","text":""},{"location":"configuring-session/configure-aws-iam-user/#what-is-an-aws-iam-user-session","title":"What is an AWS IAM User session","text":"
An AWS Identity and Access Management (IAM) user is an entity that you create in AWS to represent the person or application that uses it to interact with AWS.
An IAM User in AWS consists of a name and a set of long-term credentials. Leapp never sets these values in the configuration files, and automatically generates and refreshes a set of short-term credentials.
Info
If you want to know how Leapp generates and refresh short-term credentials refer to the credentials generation section in the documentation.
"},{"location":"configuring-session/configure-aws-iam-user/#how-to-configure-an-aws-iam-user-in-leapp","title":"How to configure an AWS IAM User in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM User as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-user/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. MFA DEVICE Your MFA device ID to set up multi-factor authentication. ACCESS KEY ID Your long-term Access Key. It will be used to generate a short-term set of credentials. Don't disclose it to anyone. SECRET ACCESS KEY Your long-term Secret Key. It will be used to generate a short-term set of credentials. Don't disclose it to anyone. Add AWS IAM User Screen"},{"location":"configuring-session/configure-aws-iam-user/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-localstack/","title":"Configure LocalStack","text":""},{"location":"configuring-session/configure-localstack/#what-is-a-localstack-session","title":"What is a LocalStack session","text":"
With LocalStack you can emulate AWS cloud services with a fully functional cloud stack on your local machine. Develop and test your cloud applications with the full cloud experience, but without the hassle of the remote cloud.
You can use Leapp to create a LocalStack session that can then be used to set your local credential file and access your LocalStack resources.
Info
You need to install LocalStack in order to use the AWS cloud emulation features
"},{"location":"configuring-session/configure-localstack/#how-to-configure-a-localstack-session-in-leapp","title":"How to configure a LocalStack session in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select LocalStack as the Cloud Provider.
Provide a name for the session.
Click on the Create Session button.
Warning
LocalStack sessions work only with AWS Credential Method configured with the credential-file-method option. The option is available in the Options menu > General > Generics > AWS Credential Method.
Warning
In order to use the credential file to access LocalStack from your AWS CLI, you must update the AWS CLI to the latest version.
Contributions and questions are not just welcome, they\u2019re essential! Please open issues with ideas on how to improve Leapp, including feedback, critiques, and information about how you\u2019re using it. Discussion is at the heart of the project and your thoughts and ideas will help make it better for everyone, thank you.
Read our contribution guide to learn more.
You can chat with us in our community, so join us, or feel free to contact us via the website!
Join our Community
"},{"location":"installation/install-leapp/","title":"Install Leapp","text":""},{"location":"installation/install-leapp/#install-leapp-app","title":"Install Leapp App","text":""},{"location":"installation/install-leapp/#macos-windows-and-linux","title":"MacOS, Windows, and Linux","text":"
You can install Leapp by downloading the pre-built binaries for your OS on the website release page:
Download Leapp \u21e9
Unzip the package and double-click the executable to install.
You can install Leapp CLI through a Homebrew Formula:
brew install Noovolari/brew/leapp-cli\n
In Linux it may happen that the command leapp is not recognized. In that case we suggest to run the following command:
brew link leapp-cli\n
"},{"location":"installation/install-leapp/#install-leapp-cli-on-macos-with-arm64-chip-m1-m2","title":"Install Leapp CLI on macOS with ARM64 chip (M1, M2)","text":"
On macOS with ARM64 chip you can use the Homebrew Formula:
All the available commands are listed in the Leapp CLI section of the documentation.
Warning
Leapp CLI will work only if the Desktop App is installed and running.
"},{"location":"installation/requirements/","title":"Requirements","text":""},{"location":"installation/requirements/#requirements","title":"Requirements","text":""},{"location":"installation/requirements/#macos-and-windows","title":"MacOS and Windows","text":"
There are no requirements for macOS and Windows users.
Leapp uses libsecret and gnome-keyring as dependencies to store all sensitive data into the keyring. Depending on your distribution, you may need to install them using these commands before running Leapp.
"},{"location":"installation/requirements/#logging-into-ec2-instances-via-aws-ssm-with-leapp","title":"Logging into EC2 Instances via AWS SSM with Leapp","text":"
In order to use AWS SSM on your System through Leapp, you must be able to execute this command on your own at least once, when the correct credentials are active.
Leapp checks if a new version is available every 10 minutes (starting from the application launch). If so, a dialog message will pop up and show a version number, the release date and the changelog
In this modal, a user can do the following:
Remind me laterDownload updateClick on X
Leapp will close the modal and notify the user that a new update is available by adding a notification dot to the Dock Bar icon. Users will not be bothered anymore until the next release is available. This option is convenient for users that want to stick to a specific version. Note that you can do this for every version and maintain the one you prefer.
Leapp will open the Release URL in your default browser to let the User manually download the release for their specific OS and install it.
Leapp will close the modal and another one will appear in 10 minutes.
"},{"location":"installation/update-leapp/#macos-homebrew-linux-linuxbrew-and-windows-via-wsl","title":"macOS (Homebrew), Linux (Linuxbrew) and Windows (via WSL)","text":"
Leapp can also be updated via Homebrew Cask with: brew upgrade leapp
Depending on which method you used to install the CLI (npm or Homebrew on macOS), you can update it with the following commands:
npmHomebrew (macOS)
npm update -g @noovolari/leapp-cli\n
brew upgrade Noovolari/brew/leapp-cli\n
"},{"location":"leapp-pro/security-and-password/","title":"Security and password","text":""},{"location":"leapp-pro/security-and-password/#password-issues","title":"Password issues","text":""},{"location":"leapp-pro/security-and-password/#can-i-recover-my-password","title":"Can I recover my password?","text":"
Unfortunately, it is not possible to recover the master password. The master password is very important as it's the key point of our zero-knowledge encryption mechanism. If you forget it, you'll lose access to the previously encrypted Leapp Sessions and Integrations. That's why it is crucial that you keep your password safe; we suggest you to store it in a password manager like 1Password.
"},{"location":"leapp-pro/security-and-password/#how-is-my-data-encrypted","title":"How is my data encrypted?","text":"
All information associated with your stored data is protected with end-to-end encryption. Leapp Sessions and Integrations are encrypted before being forwarded to the backend. Specifically, Leapp Pro uses AES 256-bit encryption as well as PBKDF-SHA512 to secure your data.
AES is a standard in cryptography and is used by the U.S. government and other government agencies around the world for protecting top-secret data. With proper implementation and a strong encryption key (your Master Password), AES is considered unbreakable.
PBKDF-SHA512 is used to derive the encryption key from your master password. Then this key is salted and hashed for authenticating with the Leapp Pro backend. The default iteration count used with PBKDF2 is 500,000 iterations on the client. Each Secret has its own generated symmetric key; this symmetric key is encrypted using the user\u2019s public RSA key (this is also the foundation of the Secret sharing system). This encryption and decryption are done entirely on the Leapp Pro clients because your master password is never stored on or transmitted to Leapp Team backend.
It is important to highlight the fact that the backend does not act as a credentials broker, i.e. it has no visibility on the long-term/short-term credentials used by Leapp Pro Desktop App/CLI to access the cloud providers. In addition, the secrets retrieved from the backend, are an encrypted version of access configurations; access configurations DO NOT include temporary credentials. There is a single edge case: the IAM User. Indeed, the IAM User Session access configuration contains IAM User\u2019s access keys, which are long-term credentials. Still, the Leapp Pro backend has no visibility on these long-term credentials, as they\u2019re encrypted by the client before being forwarded to the Leapp Team backend.
When you unlock Leapp Pro, using a longer and more secure account password is easier than you might otherwise have chosen.
"},{"location":"leapp-pro/security-and-password/#your-fingerprint-is-not-stored-in-leapp","title":"Your fingerprint is not stored in Leapp.","text":"
Leapp never scans or stores your fingerprint. Touch ID is provided by macOS, which only tells Leapp Pro if your fingerprint was recognized or not.
Learn more about Touch ID's advanced security technology.
"},{"location":"leapp-pro/synchronization/","title":"Synchronization","text":""},{"location":"leapp-pro/synchronization/#whats-a-pro-workspace","title":"What's a Pro Workspace","text":"
A Pro Workspace is a new Workspace that is created upon first login with your registered Pro User. This workspace is synchronized with your Cloud account every time you create, edit, or delete an integration or a session; this way it is possible to use Leapp Pro on different devices, maintaining all your saved integrations and sessions.
"},{"location":"leapp-pro/synchronization/#how-the-synchronization-works","title":"How the Synchronization works","text":"
Synchronization works by encrypting all your sessions and integrations with your master password, created during your sign-up process. This way we maintain a 0-knowlegde approach on your data through all the lifecycle of your Pro workspace.
The encrypted data is then saved in the Cloud on your Leapp Pro personal space.
You, as a Leapp Pro user, can always keep an eye on the status of synchronization using the synchronization widget in the bottom-left area of Leapp.
Synchronization widget - synchronization active and done
When all the data is correctly synchronized you'll see the image above.
When Leapp Pro is synchronizing you'll see the icon and text changing to the one in the image below.
Synchronization widget - synchronization in progress
If you eventually lose connection or have a problem in synchronizing your data the widget will turn yellow as shown below.
Synchronization widget - synchronization failed
You have the possibility to manually trigger another synchronization process and see if the problem is resolved.
Info
When Leapp Pro is restarted it will try to synchronize your data in the Cloud if you're logged in, so you can also close Leapp safely even if in synch failed state.
"},{"location":"leapp-pro/synchronization/#do-you-have-any-trouble-with-synchronization","title":"Do you have any trouble with Synchronization","text":"
In case of any troubles locking Leapp Pro workspace please contact us.
Leapp Pro enable Users to protect their Cloud access with Username and password.
With Leapp Pro you can back up and synchronize your Leapp workspace and access to any device you want without losing your access configurations.
"},{"location":"leapp-pro/getting-started/#getting-started-guide","title":"Getting started guide","text":"
Sign up to Leapp Pro
Sign in to Leapp Pro
Lock your Leapp Pro Workspace
"},{"location":"leapp-pro/getting-started/#security-and-syncronization","title":"Security and syncronization","text":"
Once you updgrade your Plan to Leapp Pro, your local Workspace will be moved to the Pro Workspace. All the data inside your workspace are secured with end-to-end encryption through your Master password.
"},{"location":"leapp-pro/getting-started/lock/","title":"Lock your Workspace","text":"
Leapp Pro allows the user to temporary lock the workspace, making it accessible only by typing again your master-password. This feature provides a further security level on top of the standard Leapp Community edition.
"},{"location":"leapp-pro/getting-started/lock/#how-to-lock-the-leapp-pro-workspace","title":"How to lock the Leapp Pro workspace","text":"
To lock your Leapp Pro workspace you should click on the Workspace button located in the top-left area and select the Lock option.
Workspace button Lock option
The Leapp Pro lock screen should appear, prompting for your master-password.
Leapp Pro lock screen"},{"location":"leapp-pro/getting-started/lock/#touch-id","title":"Touch ID","text":"
You can also use your fingerprint to unlock Leapp if your PC is Touch ID compatible. After Logging to your Pro workspace for the first time, Leapp will associate your workspace with your system Touch ID. After that the option will be available and can also be tweaked in the general tab of the option menu.
"},{"location":"leapp-pro/getting-started/lock/#troubles-in-locking-your-workspace","title":"Troubles in locking your Workspace","text":"
In case of any troubles locking Leapp Pro workspace please contact us.
With Leapp Pro you can always sign-in from any location, gaining instant access to your personal workspace.
"},{"location":"leapp-pro/getting-started/sign-in/#sign-in-to-leapp-pro","title":"Sign-in to Leapp Pro","text":"
After upgrading Leapp Community edition, you can sign-in at any time, just clicking on the Workspace button located in the top-left area and selecting the Sign-in Workspace option.
Workspace button Sign-in Workspace option
The Sign-in Workspace dialog will appear. Enter your Email address, master-password and click on the Add Workspace button.
Sign-in dialog
If the information entered is correct, your Leapp Pro workspace will be displayed and you can immediately use it to manage your cloud credentials.
Leapp Pro Workspace
To avoid unwanted access, you can lock your Leapp Pro workspace at any time.
"},{"location":"leapp-pro/getting-started/sign-in/#troubles-in-signing-in-to-leapp-pro","title":"Troubles in signing in to Leapp Pro?","text":"
In case of any troubles signing in to Leapp Pro please contact us.
A Leapp Pro upgrade is required to enable new workspace features like Cloud access from multiple locations and Workspace locking.
"},{"location":"leapp-pro/getting-started/sign-up/#sign-up-to-leapp-pro","title":"Sign-up to Leapp Pro","text":"
To sign up for Leapp Pro you should upgrade your version of Leapp Community edition. Click on the Options button in the top-right area.
Settings button
In the Options dialog, select the Plans tab and click on Upgrade to Pro button.
Plans tab
The upgrade window should appear. Enter your email (it will be the email address associated with your Leapp Pro account) and click on the Upgrade now button.
Upgrade window
At this point a window will appear, so you can specify a payment method to complete the Leapp Pro upgrade. After the payment process you will receive a confirmation email containing the Complete the registration link.
Upgrade email
Clicking the link in the confirmation email will open a web page that will allow you to enter your personal info and the master-password, essential to provide the security requirements of Leapp Pro.
Sign-up page
After entering your personal info and the master-password click the Continue button. You can now finally sign in to Leapp Pro.
"},{"location":"leapp-pro/getting-started/sign-up/#troubles-in-signing-up-to-leapp-pro","title":"Troubles in signing up to Leapp Pro?","text":"
In case of any troubles signing up to Leapp Pro please contact us.
"},{"location":"leapp-pro/getting-started/sign-up/#how-to-sign-in","title":"How to Sign-in","text":"
Take a look to this page to sign-in your Leapp Pro workspace.
argument type description message string the message to show level LogLevel severity of the message display boolean shows the message in a toast in the desktop app when true. Otherwise, log it in the log files"},{"location":"plugins/plugins-development/#fetch","title":"fetch","text":"
fetch(url: string): any
Retrieve the content of a URL. Returns a promise for the URL
argument type description url string a valid HTTP URL to fetch from"},{"location":"plugins/plugins-development/#openexternalurl","title":"openExternalUrl","text":"
openExternalUrl(url: string): void
Open an external URL in the default browser
argument type description url string a valid HTTP URL to open in the default browser"},{"location":"plugins/plugins-development/#createsession","title":"createSession","text":"
Creates a new Leapp Session based on given SessionData
argument type description createSessionData SessionData the metadata used to create the Leapp Session"},{"location":"plugins/plugins-development/#clonesession","title":"cloneSession","text":"
cloneSession(session: Session): Promise<string>
This method allows you to clone the given Leapp Session. This operation is allowed for the following Leapp Session types:
AwsIamUserSession
AwsIamRoleFederatedSession
AwsIamRoleChainedSession
argument type description session Session the Leapp Session that I want to clone"},{"location":"plugins/plugins-development/#updatesession","title":"updateSession","text":"
This method allows you to update the given session with the given updateSessionData. This operation is allowed for the following Leapp Session types:
AwsIamUserSession
AwsIamRoleFederatedSession
AwsIamRoleChainedSession
argument type description updateSessionData SessionData the metadata used to update the given Leapp Session session Session the Leapp Session that I want to update"},{"location":"plugins/plugins-development/#openterminal","title":"openTerminal","text":"
Execute the given command in the platform-specific terminal; optionally, it is possible to set an env key/value object containing the env variables to export in the terminal, before the command execution.
The terminal window base path is set to the home directory.
argument type description command string the command that I want to execute in the platform-specific terminal env any optional key/value env variables object"},{"location":"plugins/plugins-development/#getprofileidbyname","title":"getProfileIdByName","text":"
getProfileIdByName(profileName: string): string
Returns the id of a named profile from its name if it exists, otherwise creates a new profile and returns its id.
Can be used when creating/editing a session since SessionData requires the id of a named profile
argument type description profileName string a valid named profile"},{"location":"plugins/plugins-development/#getidpurlidbyurl","title":"getIdpUrlIdByUrl","text":"
getIdpUrlIdByUrl(url: string): string
Return the ID of the IdpUrl object from the given URL if it exists, otherwise creates a new IdP URL and returns its ID.
Can be used when creating/editing Federated Sessions since SessionData requires the ID of an IdP URL.
argument type description url string the URL associated with the IdpUrl I want to retrieve"},{"location":"plugins/plugins-development/#example-display-a-toast-message-in-leapp","title":"Example: display a toast message in Leapp","text":"
Return a valid FontAwesome 5 code. Override default value in package.json
"},{"location":"plugins/plugins-development/#example-display-a-session-based-message-in-leapp","title":"Example: display a session-based message in Leapp","text":"
async applySessionAction(session: Session, credentials: any): Promise<void> {\nif(session.type === Session.awsIamUser) {\nthis.pluginEnvironment.log(`This is an IAM User session: ${session.sessionName}`, LogLevel.info, true); }\nelse {\nthis.pluginEnvironment.log(`This is NOT an IAM User session: ${session.sessionName}`, LogLevel.info, true);\n}\n}\n
"},{"location":"plugins/plugins-development/#packagejson-metadata","title":"package.json metadata","text":"property values description constraints name a custom string the name of the plugin the same used in the plugin folder author a custom string the name of the author none version a custom string the version of the plugin must be a semver string description a custom string the description of the plugin none keywords a string array the name of the plugin must contain at least \"leapp-plugin\" leappPlugin an object the plugin custom configuration must contain at least \"supportedOS\" and \"supportedSessions\" leappPlugin.supportedOS a string array [\"mac\", \"windows\", \"linux\"] if not specified, all OSs will be considered compatible leappPlugin.supportedSessions a string array [\"anyType, \"aws\", \"azure\", \"awsIamRoleFederated\", \"awsIamRoleChained\", \"awsSsoRole\", \"awsIamUser\"] at least one of these values must be specified leappPlugin.icon a custom string fontAwesome code for an icon (e.g. \"fa fa-globe\") must be a valid FontAwesome 5 code"},{"location":"plugins/plugins-development/#plugin-examples","title":"Plugin Examples","text":""},{"location":"plugins/plugins-development/#open-web-console","title":"Open Web Console","text":"
import { Session } from \"@noovolari/leapp-core/models/session\";\nimport { AwsCredentialsPlugin } from \"@noovolari/leapp-core/plugin-sdk/aws-credentials-plugin\";\nimport { PluginLogLevel } from \"@noovolari/leapp-core/plugin-sdk/plugin-log-level\";\n\nexport class WebConsolePlugin extends AwsCredentialsPlugin {\nget actionName(): string {\nreturn \"Open web console\";\n}\n\nget actionIcon(): string {\nreturn \"fa fa-globe\";\n}\n\nasync applySessionAction(session: Session, credentials: any): Promise<void> {\nthis.pluginEnvironment.log(\"Opening web console for session: \" + session.sessionName, PluginLogLevel.info, true);\n\nconst sessionRegion = session.region;\nconst sessionDuration = 3200;\nconst isUSGovCloud = sessionRegion.startsWith(\"us-gov-\");\nlet federationUrl;\nlet consoleHomeURL;\n\nif (!isUSGovCloud) {\nfederationUrl = \"https://signin.aws.amazon.com/federation\";\nconsoleHomeURL = `https://${sessionRegion}.console.aws.amazon.com/console/home?region=${sessionRegion}`;\n} else {\nfederationUrl = \"https://signin.amazonaws-us-gov.com/federation\";\nconsoleHomeURL = `https://console.amazonaws-us-gov.com/console/home?region=${sessionRegion}`;\n}\n\nif (sessionRegion.startsWith(\"cn-\")) {\nthrow new Error(\"Unsupported Region\");\n}\n\nthis.pluginEnvironment.log(\"Starting opening Web Console\", PluginLogLevel.info, true);\n\nconst sessionStringJSON = {\nsessionId: credentials.sessionToken.aws_access_key_id,\nsessionKey: credentials.sessionToken.aws_secret_access_key,\nsessionToken: credentials.sessionToken.aws_session_token,\n};\n\nconst queryParametersSigninToken = `?Action=getSigninToken&SessionDuration=${sessionDuration}&Session=${encodeURIComponent(\nJSON.stringify(sessionStringJSON)\n)}`;\n\nconst res = await this.pluginEnvironment.fetch(`${federationUrl}${queryParametersSigninToken}`);\nconst response = await res.json();\n\nconst loginURL = `${federationUrl}?Action=login&Issuer=Leapp&Destination=${consoleHomeURL}&SigninToken=${(response as any).SigninToken}`;\nthis.pluginEnvironment.openExternalUrl(loginURL);\n}\n}\n
"},{"location":"plugins/plugins-introduction/","title":"Introduction to Plugins","text":"
This section provides an overview of Leapp\u2019s plugins, which can be used to extend the functionality of Leapp.
Plugins are commonly used when more advanced and custom behavior is needed, for example using Leapp-generated temporary credentials to run custom actions.
You can create your own plugins or import custom ones created by the community. You can also publish your plugins on npm to make them available to everyone easily.
"},{"location":"plugins/plugins-introduction/#add-a-plugin","title":"Add a Plugin","text":"
To add a plugin you can use one of the following methods:
"},{"location":"plugins/plugins-introduction/#add-from-npm","title":"Add from npm","text":"
From the Leapp option menu, go to the Plugins tab. Insert the name of the npm package for the plugin and click on the plus icon to add it to your plugins
Go to Options by clicking the top right gear icon then click the Plugins tab. Click the Folder Icon. This will open the plugin folder inside .Leapp.
Here, manually create a folder with the same name as your plugin package.json name property and move your package.json and bundled plugin.js files inside this folder.
Alternatively, you can simply move your entire plugin folder cloned from the example template.
Lastly, from the Leapp Plugins tab in the Option menu, click on the refresh icon to reload all plugins.
Warning
Adding plugins is at your own risk! We cannot currently guarantee that a plugin is safe, so BE CAREFUL when you install something from an unknown source. A plugin verification system is under development and will be available later this year.
"},{"location":"plugins/plugins-introduction/#disable-a-plugin","title":"Disable a Plugin","text":"
To disable a Leapp plugin, go to Options by clicking the top right gear icon then click the Plugins tab.
Toggle Enabled for the plugin you want to disable.
"},{"location":"plugins/plugins-introduction/#remove-a-plugin","title":"Remove a Plugin","text":"
To remove a Leapp plugin, go to Options by clicking the top right gear icon then click the Plugins tab.
Click the Folder Icon. This will open the plugin folder inside .Leapp. From here, locate the folder containing the plugin you want to remove and simply delete the folder.
"},{"location":"plugins/plugins-introduction/#run-a-plugin","title":"Run a Plugin","text":"
You can run a plugin both from Leapp Desktop App and Leapp CLI.
From Leapp Desktop App, right click on a session to open the contextual menu, click on Plugins, and select the plugin you want to run
Info
This contextual menu option is not available if you have no plugins that you can run on the selected session and/or your operating system.
From Leapp CLI, you can use the command leapp session run-plugin. For more information on how to use this CLI command, see the documentation.
Click on the top right gear icon to go to the Leapp option menu and then select the tab Plugin.
From there, you can see a list of currently installed plugins, check whether a plugin is compatible with your system or not, which session types it supports and disable/enable it if you need.
"},{"location":"plugins/plugins-introduction/#create-your-plugin","title":"Create your Plugin","text":"
You can start creating a plugin from the template.
Leapp plugins are written in TypeScript. They must contain at least a class that extends a base class provided by the Plugin SDK.
There's currently only one of these classes, AwsCredentialsPlugin , that can be used to create a plugin that generates temporary credentials.
Every Leapp plugin must at least have a package.json file and a plugin.js file.
leapp-plugin/ \n \u251c\u2500\u2500 package.json # Plugin metadata\n \u2514\u2500\u2500 plugin.js # A webpack bundle for the main logic\n
Create your Plugin
"},{"location":"security/credential-process/","title":"Credential Process","text":""},{"location":"security/credential-process/#what-is-credential-process","title":"What is Credential Process?","text":"
Credential Process is a configuration option (in the AWS config file) that instruct the AWS CLI and SDKs to use an external command to generate valid credentials in a specific format.
It is a way to generate AWS compatible credentials on the fly, only when requested by tools that respect the AWS credential chain.
Credential Process is perfect if you have a way to generate or look up credentials that isn't directly supported by the AWS CLI or third-party tools; for example, you can configure the AWS CLI to use it by configuring the credential_process setting in the config file.
The difference between Credential Process and Standard Credential file is that credentials in the \"credential file\" are written in plain text and so, they are potentially unsecure, even if temporary. Credential Process instead, generates credentials that are consumed only when they are effectively needed.
No credential is written in any file. They are printed on the stdout and consumed upon request.
"},{"location":"security/credential-process/#how-credential-process-works","title":"How Credential Process works?","text":"
Credential Process asks an external process to generate an AWS compatible temporary credential set in this format:
{\n\"Version\": 1,\n\"AccessKeyId\": \"an AWS access key\",\n\"SecretAccessKey\": \"your AWS secret access key\",\n\"SessionToken\": \"the AWS session token for temporary credentials\", \"Expiration\": \"ISO8601 timestamp when the credentials expire\"\n}
The Expiration field allows the generated credentials to be cached and reused until they are no more valid (by default the value is 3600s=1h).
Ensures that no credential set is written on your machine in neither the ~/.aws/credentials or ~/.aws/config files.
Ensures your long-running tasks always have valid credentials during their lifecycle.
Is compatible with named-profiles.
Is a way to make third-party tool compatible with AWS SSO and SAML Federated IAM Principals even if they don't support them natively.
As stated by this article by Ben Kehoe, Credential Process is a good way to avoid cluttering the credential file with temporary credentials.
Warning
Temporary credentials in the credentials file reduce potential blast radius in case of machine exploit but they require to be refreshed every time they expire.
"},{"location":"security/credential-process/#how-leapp-works-with-credential-process","title":"How Leapp works with Credential Process","text":"
Info
Requirements: this credentials generation method requires that both Leapp desktop app and CLI are installed.
1) Open your Leapp desktop app and go to the settings panel ().
2) In the general section change the AWS Credential Generation from \"credential-file-method\" to \"credential-process-method\".
3) An informative panel will show up telling that you need the CLI installed (see below), click on \"I acknowledge it\"
warning modal
4) Now, everytime you click on start () an entry will be created in the ~/.aws/config file with the following format:
5) You can start more than one session, depending on how many named-profile you've created; for every session started with a unique named-profile, a new entry will be created in the config file.
Info
AWS CLI, SDks, and third-party tools that can read credentials from the config file can reach AWS services with this method.
Leapp is built with a security-first approach. Every piece of information that has to be persisted is encrypted and saved on your workstation.
We devised two main methods to store data, based on its sensitiveness.
Data Persistence and encryption Examples Operational All information used to make Leapp work, not strictly tied to direct access to cloud environments. Stored and encrypted in a configuration file within the user workspace. Named profiles, proxy configurations, etc. Sensitive Information that can be used, or potentially exploited, to gain access to cloud environments. Stored in the System Vault, leveraging its own integrated encryption. Static credentials, access tokens, cached data, etc."},{"location":"security/intro/#end-to-end-encryption","title":"End-to-end Encryption","text":"
We leverage Zero-Knowledge to provide end-to-end encryption on tiers that require to save your data outside of your workstation to deliver specific features.
Zero Knowledge is designed so that no one, except you, can access your secured data.
Warning
We CAN'T access your data under any circumstances, even if you ask us to!
Information that can be used, or potentially exploited, to gain access to cloud environments are stored your workstation's System Vault, leveraging its own integrated encryption. The user can access the secrets stored in the System Vault at any time, using their user password.
Leapp uses Keytar as an interface to the secure vault on macOS, Windows and Linux systems.
Every key is stored in the vault under the name Leapp. In the description, you will find the underlying name used by Leapp to retrieve the secret.
"},{"location":"security/system-vault/#supported-system-vaults","title":"Supported System Vaults","text":"OS System Vault MacOS Keychain Windows Credential Vault Linux API/Libsecret
Info
We're currently supporting only System Vaults installed by default on the OS. We're planning on extending support to other vaults and online password managers (LastPass, BitWarden, 1Password, etc.). If you'd like other services to be supported feel free to open an Issue or make a Pull Request (check our contributing guidelines).
To persist your configuration online, we implemented Zero-Knowledge encryption to prevent access to your information. But how can you trust a company to keep all of your secrets secret? The answer lies in end-to-end encryption, which lays the groundwork for applications with Zero-Knowledge architectures.
Zero-knowledge refers to policies and architecture that eliminate the possibility for secret managers themselves to access your password.
Warning
This is implemented to save your configuration online in the PRO and TEAM versions of Leapp. Don't know yet about the PRO and TEAM versions? Check our roadmap.
Info
This same process is leveraged by Bitwarden to store their password.
"},{"location":"security/zero-knowledge/#users-have-key-control","title":"Users have key control","text":"
When users have complete control of the encryption key, they control access to the data, providing encrypted information to Leapp without Leapp having access to or knowledge of that data.
Info
To know more about this, you can find the whitepaper on which we based our implementation of Zero-Knowledge end-to-end encryption.
During any phase of the registration and login process the client does not provide any password-related info to the server.
The server does not store any information that can be used to guess the password in a convenient way. In other words, the system must not be prone to brute force or dictionary attacks.
Any sensible data is encrypted client-side, the server will work with encrypted blocks only.
All the implementation is released as open-source.
Temporary security credentials created by AssumeRoleWithSAMLResponse last for one hour. However, you can use the optional DurationSeconds parameter to specify the duration of your session.
Your role session lasts for the specified duration, or until the time specified in the SAML authentication response's SessionNotOnOrAfter value, whichever is shorter. You can provide a DurationSeconds value from 900 seconds (15 minutes) up to the maximum session duration setting for the role. This setting can have a value from 1 hour to 12 hours.
Leapp sets the token duration to 1 hour.
Info
\u26a0\ufe0f In this case, generated credentials are not \"cached\" in the keychain.
The GetSessionToken operation must be called by using the long-term AWS security credentials of the AWS IAM user. Credentials that are created by IAM users are valid for the duration that you specify. This duration can range from 900 seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours), with a default of 43,200 seconds (12 hours). Credentials based on account credentials can range from 900 seconds (15 minutes) up to 3,600 seconds (1 hour), with a default of 1 hour.
Leapp sets the token duration to 10 hours.
Info
These are the only temporary credentials that are stored in the System vault and not rotated, unless expired.
The access token is valid for 8 hours as noted in the expiresAt timestamp in the JSON file. Expired tokens must be re-authenticated using the get-role-credentials API call.
Azure generates a set of access and refresh tokens that are put inside the msal_token_cache.json file inside the .azure directory. Following is the procedure used to generate a set of credentials.
Info
In Windows OS the msal_token_cache is persisted on an encrypted file with dpapi API. Starting from release 2.30 of Azure CLI, credentials are no more persisted in the original accessToken.json
Azure Users profile info is saved in the azureProfile.json file inside the .azure directory.
Before accessing Azure sessions, you now have to create an Azure integration. After that, these are the steps required to log in and then retrieve Azure sessions.
msal_token_cache and azureProfile.json files are cleaned for security reasons.
We execute az login --tenantId <TENANTID>. We do this to obtain the updated user profile and the refresh token (associated to this integration).
We extract all the Azure subscriptions associated with the integration and for each one we map a Leapp Azure session.
We extract the refresh token, account, and profile information from msal_token_cache and azureProfile.json and persist them in the System's vault.
We also remove the previous information from the original files, to increase security and avoid external tampering.
In the current version of Leapp we can only start one Azure session at a time.
For each subscription retrieved upon login to a specific integration, we define a new Leapp Azure Session. To start an Azure session we follow these steps.
Recover refresh token, account, and profile information from the Vault and we use them alongside sessionId (Subscription id) in the start operation.
azureProfile.json is only filled with profile information from the current subscription.
We write the account information and the refresh token back in the msal_token_cache
We execute az account get-access-token --subscriptionId <SUBSCRIPTIONID>, to retrieve the access token and the id token of the subscription.
The previous command also writes access and id token back to the msal_token_cache file.
We update the expiration time of the session to the current datetime.
We update the refresh token in the Vault with the new information.
We remove the refresh token from the msal_token_cache.
We finally start the session.
Info
The refresh token is a long term credential that potentially lasts for 90 days. The access token is a short term credential and lasts for 70 minutes. Source
Please always add logs to any issue you want to fill whenever possible, so you can help the team identify the problem quickly
"},{"location":"troubleshooting/faq/","title":"FAQ","text":""},{"location":"troubleshooting/faq/#im-using-the-open-source-app-do-you-store-my-data-online","title":"I'm using the open-source app, do you store my data online?","text":"
NO.
The open-source software doesn't transfer, persist, or share anything with other services. All your data is secured and encrypted on your workstation.
Nobody can access it, not even ourselves.
"},{"location":"troubleshooting/faq/#ive-got-a-paid-tier-how-do-you-manage-my-data-can-you-access-it","title":"I've got a paid tier, how do you manage my data? Can you access it?","text":"
We can't and don't want to see any of your access data.
We need to store your data online to enable some features (syncing, managing other users, etc.) but we implement a Zero-Knowledge encryption system that prevents even ourselves to access your data.
"},{"location":"troubleshooting/faq/#i-dont-feel-secure-using-a-built-in-window-for-authentication-cant-you-use-the-default-browser","title":"I don't feel secure using a built-in window for authentication, can't you use the default browser?","text":"
In the future, Leapp will only use the default browser to authenticate. Right now, this is a compromise to deliver the authentication flow. We already ported the AWS SSO authentication flow on the default browser, and we're working on migrating the other ones as soon as possible.
"},{"location":"troubleshooting/faq/#how-can-i-find-leapp-data-in-the-system-vault","title":"How can I find Leapp data in the System Vault?","text":"
Every key stored by Leapp in the vault is named Leapp. The account name shows the description of the element saved by our software.
"},{"location":"troubleshooting/faq/#where-do-i-find-the-leapp-logs","title":"Where do I find the Leapp logs?","text":"
Head to the Application data section.
"},{"location":"troubleshooting/faq/#ssm-terminal-is-opening-but-no-session-is-starting-what-can-i-do","title":"SSM terminal is opening but no session is starting, what can I do?","text":"
Just close the terminal and relaunch the SSM command.
"},{"location":"troubleshooting/faq/#aws-cli-or-az-cli-is-installed-but-leapp-cant-find-it-what-can-i-do","title":"AWS CLI (or AZ CLI) is installed but Leapp can't find it, what can I do?","text":"
Leapp on macOS works in sandbox mode, so some terminal commands must be symlinked in order to work on some installations. Just make a symlink pointing from /usr/local/bin/aws to the actual aws binary or, for AZ CLI, from /usr/local/bin/az to the actual az binary. To create symlinks on macOS, use this command ln -s /any/file/on/the/disk linked-file. The command is called ln. If used with the option -s it will create a symbolic link in the current directory.
"},{"location":"troubleshooting/faq/#i-use-leapp-session-current-but-want-to-see-the-alias-and-not-the-id","title":"I use leapp session current but want to see the alias and not the id.","text":""},{"location":"troubleshooting/faq/#setting-up-leappalias-command","title":"Setting up leappalias command","text":"
Follow these steps to set up the leappalias command in your Zsh shell:
Create a script file named leappalias.sh using a text editor:
Save the file and make it executable by running the following command in the terminal:
chmod +x leappalias.sh\n
Move the script to a directory in your system's PATH. For example, /usr/local/bin/:
sudo mv leappalias.sh /usr/local/bin/leappalias\n
Open your zshrc file using a text editor:
nano ~/.zshrc\n
Define an alias for executing the script by adding the following line to the zshrc file:
alias leappalias='/usr/local/bin/leappalias'\n
Save the changes and close the zshrc file.
Reload the zshrc file in the terminal using the following command:
source ~/.zshrc\n
Once you have completed these steps, you can use the leappalias command in your terminal to extract and display the alias from the output of leapp session current. Credit goes to bspansinQdo.
"},{"location":"troubleshooting/faq/#how-can-i-add-support-to-a-new-saml-20-identity-provider","title":"How can I add support to a new SAML 2.0 Identity Provider?","text":"
To add support to a new SAML 2.0 Identity Provider, you have to perform the following steps:
create a Fork of the Noovolari/leapp GitHub repository;
create a Pull Request and set up your local environment following Install dependencies and build packages section of the DEVELOPMENT.md;
add the Identity Provider-specific authentication URL RegEx filter to the Leapp Core authenticationUrlRegexes Map;
follow the last part of the Install dependencies and build packages section of the DEVELOPMENT.md to build the solution for both the CLI and the Desktop App;
push your changes to your forked repository and propose to merge them to the main repository.
If you need more details about the implementation, please check the How to add a new SAML IdP preset authentication URL section of the DEVELOPMENT.md.
"},{"location":"usefull-scripts/export-profile/","title":"AWS Profile Selector: Simplifying AWS Profile Selection with the Leapp CLI","text":""},{"location":"usefull-scripts/export-profile/#aws-profile-selector-simplifying-aws-profile-selection-with-the-leapp-cli","title":"AWS Profile Selector: Simplifying AWS Profile Selection with the Leapp CLI","text":"
This script enhances the AWS profile selection process by utilizing the Leapp CLI. It provides a streamlined way to switch between AWS profiles in the command line environment, allowing for easy management of multiple AWS configurations.
To use the script, it's important to note that you need to have Leapp installed and running. Leapp is a command-line tool for managing AWS profiles and sessions. Before executing the script, ensure that Leapp is installed on your system and at least one AWS session is active.
Leapp keeps track of your AWS sessions and allows you to switch between different profiles seamlessly. It's a valuable tool for managing multiple AWS accounts and simplifying your workflow. Once Leapp is installed and running, the script utilizes its functionality to retrieve the list of active sessions and display them for selection.
By integrating 'fzf' with Leapp, the script provides an interactive and convenient way to choose the desired AWS profile. With a few keystrokes, you can quickly switch between AWS profiles without manually setting the environment variables each time.
Remember to save the script in your shell configuration file (.bashrc or .zshrc) and restart your terminal or reload the configuration file for the changes to take effect.
In summary, this script simplifies the process of selecting and exporting an AWS profile, making it easier to switch between different AWS configurations when using the command line.
"}]}
\ No newline at end of file
diff --git a/0.20.1/sitemap.xml.gz b/0.20.1/sitemap.xml.gz
index 2ff339ca2..b604fef9f 100644
Binary files a/0.20.1/sitemap.xml.gz and b/0.20.1/sitemap.xml.gz differ
diff --git a/0.20.1/usefull-scripts/export-profile/index.html b/0.20.1/usefull-scripts/export-profile/index.html
new file mode 100644
index 000000000..b8fd8d51c
--- /dev/null
+++ b/0.20.1/usefull-scripts/export-profile/index.html
@@ -0,0 +1,14 @@
+ AWS Profile Selector: Simplifying AWS Profile Selection with the Leapp CLI - Leapp - Docs
AWS Profile Selector: Simplifying AWS Profile Selection with the Leapp CLI
This script enhances the AWS profile selection process by utilizing the Leapp CLI. It provides a streamlined way to switch between AWS profiles in the command line environment, allowing for easy management of multiple AWS configurations.
To use the script, it's important to note that you need to have Leapp installed and running. Leapp is a command-line tool for managing AWS profiles and sessions. Before executing the script, ensure that Leapp is installed on your system and at least one AWS session is active.
Leapp keeps track of your AWS sessions and allows you to switch between different profiles seamlessly. It's a valuable tool for managing multiple AWS accounts and simplifying your workflow. Once Leapp is installed and running, the script utilizes its functionality to retrieve the list of active sessions and display them for selection.
By integrating 'fzf' with Leapp, the script provides an interactive and convenient way to choose the desired AWS profile. With a few keystrokes, you can quickly switch between AWS profiles without manually setting the environment variables each time.
Remember to save the script in your shell configuration file (.bashrc or .zshrc) and restart your terminal or reload the configuration file for the changes to take effect.
In summary, this script simplifies the process of selecting and exporting an AWS profile, making it easier to switch between different AWS configurations when using the command line.
\ No newline at end of file
diff --git a/latest/search/search_index.json b/latest/search/search_index.json
index e5ebd2e9b..2a25d69da 100644
--- a/latest/search/search_index.json
+++ b/latest/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Overview","text":""},{"location":"#overview","title":"Overview","text":""},{"location":"#welcome-to-leapp","title":"Welcome to Leapp","text":"
Leapp is a tool for developers to manage, secure, and access the cloud.
All data is persisted and encrypted on your workstation. Head to our Security section to know how we guarantee the highest level of security.
Leapp Main Window
The name Leapp is based on the word leap and is pronounced /l:ip/. We chose this name because the project enables you to be one step away from your cloud environments.
"},{"location":"edit-session/","title":"Editing a session","text":"
Leapp allows the user to edit an existing session excluding those generated from an AWS integration.
Info
Integration derived Sessions can\u2019t be changed
To edit an existing session just right-click on a session in the Leapp list (see below), and select \"edit session\". A new modal will appear, allowing the user to choose which parameters to change.
edit session
Below are the configuration options for every type of session:
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Mfa Device (optional): can be left empty or, if you add a valid device name or AWS ARN, it will prompt a modal for MFA code
Access Key ID: Replace your session Access Key ID in the system vault
Secret Access Key: Replace your session Secret Access Key in the system vault
"},{"location":"edit-session/#iam-role-chained","title":"IAM Role Chained","text":"
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Role ARN: The role that you'll assume when chaining from an assumer window
Role Session Name: (optional), it will be used to identify the chained session
Assumer Session: select a session from the list, it will be the Principal assuming the role
Info
You can also generate a new IAM Role Chained session from any other AWS session by right-clicking on a session and chosing \"Create Chained Session\"
"},{"location":"edit-session/#iam-role-federated","title":"IAM Role Federated","text":"
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Role ARN: Role of the Principal in AWS
SAML 2.0 Url: Federated URL needed for authentication to AWS
Identity Provider: the identity provider ARN that you have set up on AWS
After modifying all the parameters, a user can test their validity with test credential generation:
Clicking this button allows Leapp to do a dry run on your parameters, and if valid, a new set of credentials will be generated (but not used) and an informative toast will appear to tell you that they can be used successfully.
"},{"location":"edit-session/#how-we-handle-secrets-when-editing-a-session","title":"How we handle Secrets when Editing a Session","text":"
No secrets will be saved in plain text on your machine. Leapp saves secrets by replacing values in the system keychain, using a combination of an informative name plus the session hidden id.
This way we reduce potential blast radius of an attacker tampering your machine.
When editing a session, Leapp will hide your secrets and you are also unable to copy/paste them from the App.
This section provides an overview of Leapp's integrations, useful to extend the functionality of Leapp to 3rd party services.
Integrations help manage access and identities on your service of choice while using Leapp during your daily activities. They are automatically mapped into Sessions.
Integrations have four main actions available: Create, Delete, Sync, and Logout.
Action Description CREATE Configure a new Integration with the data needed to start the authentication flow. Required to Sync and map the service response into Sessions. DELETE Remove an existing Integration. Removes all the associated Sessions as well and wipes everything related to the Integration from the system (tokens, cache, etc.) SYNC Start the authentication flow to log into the Integration Provider. Leapp will automatically retrieve all the related data and map the response into Sessions. Any change in your service of choice requires a manual Sync to reflect the current status. LOGOUT Disable the Integration. Removes all the Sessions but keeps the Integration data. Running a Sync will restore all the Sessions tied to it."},{"location":"integrations/#supported-services","title":"Supported Services","text":"Service Supported AWS SSO Okta Coming Soon OneLogin Coming Soon AzureAD"},{"location":"sessions/","title":"Sessions","text":""},{"location":"sessions/#sessions","title":"Sessions","text":"
A Session contains all the relevant information to let the dev connect to a cloud provider. Three standard actions should be implemented for each session: start, stop, and rotate.
"},{"location":"sessions/#actions","title":"Actions","text":"Method Description START \u00a0Make the temporary credentials available to the provider chain STOP \u00a0Removes the temporary credentials from the provider chain ROTATE \u00a0Generate new temporary credentials, and substitute the previous ones in the provider chain
The process of setting up Leapp Sessions is managed either manually, for each access method, or through integrations with third-party tools. Leapp stores all the Sessions available to the users locally, inside a configuration file called Workspace.
A Workspace is a global configuration that contains all the relevant information about your Leapp setup (sessions, integrations, app preferences, etc.).
There are two types of workspace: Local and Remote.
A Local workspace is the default workspace that comes with your Leapp installation. It's a private configuration that contains your personal preferences and all sessions and integrations that you created yourself.
A local workspace is associated to a single machine and if you need to migrate your configuration to another one you will have to do it manually.
A Remote workspace is a Leapp Team configuration set created remotely by a Leapp Team manager.
When you sync a remote workspace, you will receive sessions and integrations automatically, without having to configure them yourself.
A remote workspace is persisted online by using Zero-Knowledge encryption.
You will have access to the same configurations instantly on any machine, by logging in to your Leapp Team account after having been invited by your Leapp Team manager.
Info
Both your local and remote workspaces are saved on your machine as encrypted files inside your /.Leapp directory.
The actions below only applies to Remote workspaces.
Action Description Sign-in \u00a0Connect to a Remote workspace. This action will not switch your Local workspace Switch \u00a0Switch to the selected workspace by clicking on its name in the workspace menu Lock \u00a0Switch back to the Local workspace disabling all the Remote ones Sign-out \u00a0Sign-out from a Remote workspace removing all your login details
Info
The Lock action also removes the encrypted files associated to your remote workspaces.
"},{"location":"built-in-features/aws-ec2-connect/","title":"Configure AWS EC2 Connect","text":""},{"location":"built-in-features/aws-ec2-connect/#what-is-aws-ec2-connect","title":"What is AWS EC2 Connect","text":"
Amazon EC2 Instance Connect is a simple and secure way to connect to your instances using Secure Shell (SSH). With EC2 Instance Connect, you can control SSH access to your instances using AWS Identity and Access Management (IAM) policies as well as audit connection requests with AWS CloudTrail events.
"},{"location":"built-in-features/aws-ec2-connect/#how-to-configure-aws-ec2-connect-in-leapp","title":"How To configure AWS EC2 Connect in Leapp","text":"
Warning
If your Leapp Desktop App is warning you that you're missing the AWS Session Manager Plugin, please install it following this official guide.
You can directly connect to an AWS EC2 instance from Leapp through AWS System Manager (AWS SSM).
Info
To setup SSM follow this SSM guide on AWS guide.
example image from AWS
To correctly connect follow these steps:
Right-click on a suitable AWS session to open the contextual menu.
Click on View SSM sessions.
Select the AWS region in which your instance is located.
Wait for Leapp to load your instances.
Select the instance and click connect.
Wait for the terminal to open.
Focus the terminal window and write /bin/bash; press Enter and you'll be inside the terminal of your instance.
If the user is not granted the right permissions, the operation will fail and Leapp will throw an error message.
"},{"location":"built-in-features/aws-named-profiles/","title":"Configure Named Profiles","text":""},{"location":"built-in-features/aws-named-profiles/#what-is-a-named-profile","title":"What is a Named Profile","text":"
Named Profiles are used by AWS to maintain more than one set of active credentials for you to use with AWS-CLI, SDK, or other third-party tools. Named profiles are stored in ~/.aws/credentials file in the ini file format.
Named Profiles have a default profile which is the one you get from aws configure command.
With Leapp you can group and activate more than one credential set at a time through Named Profiles.
"},{"location":"built-in-features/aws-named-profiles/#how-to-configure-a-named-profile-in-leapp","title":"How to configure a Named Profile in Leapp","text":"
Named Profiles can be created in 3 ways:
Option PanelWhen creating a new SessionEdit Profile in Contextual Menu
Click on the gear icon and select the Profiles tab. Insert the name of the new Named Profile in the input form, then click on the plus icon.
When creating a new session, the user will have the option to choose a Named Profile or add a new one.
Right-click on a session and select Change then Named Profile: an option to select or add a new Named Profile will be available.
The new name is directly added to the Named Profile list and can then be used for other sessions too.
Info
AWS SSO sessions will have the Named Profile default when obtained via Login or Sync. To change the Named Profile associated to a session you have to use the \"Change Profile\" option in the session list.
Named profiles can be managed from the Option menu.
In the Option menu, under the Profiles tab, you can add or edit a new Named Profile, and you can also remove unwanted ones. When removing a Named Profile, Leapp will warn you about which sessions are using that profile, and those sessions will be reverted to the default Named Profile.
The input form can be used to add or edit a Named Profile: if it's empty, you can use it to add a new named profile. When selecting the button, you will be able to edit the name of the Named Profile from within the input form.
Warning
Remember that when you change the profile of a session, the session will be immediately put in stop mode. That's because Leapp would have to change the credential file, so you will need to restart the session again.
Once you've opened the Leapp option menu - which can be accessed by clicking the top right gear icon - you can edit the following settings in the General tab
This option allows you to set the default AWS or Azure region/location for every new session.
Each time you create a new session, this will be the default region assigned to it.
You can still change it if you need a different one, by selecting a different region while creating the session or by changing the region once a session is created.
This option is used to select the terminal in which to open an SSM session.
Info
This setting is currently only available on MacOS. If you want to contribute and add a new terminal for a specific OS, please refer to the contributing guide
This option is used to set the default Webconsole session duration in hours.
Info
The minimum session duration is 1 hour, and can be set to a maximum of 12 hours. Set session duration
"},{"location":"built-in-features/multi-console/","title":"Configure Multi Console","text":""},{"location":"built-in-features/multi-console/#what-is-multi-console","title":"What is Multi Console","text":"
The Leapp Multi-Console Browser Extension allows you to open multiple instances of the AWS Web Console in the same browser window and helps you in managing them.
Get it on Firefox \u21e9 Get it on Chrome \u21e9"},{"location":"built-in-features/multi-console/#list-of-supported-browsers","title":"List of Supported Browsers","text":"Browser Supported Firefox Chrome Edge Brave Safari"},{"location":"built-in-features/multi-console/#how-to-configure-multi-console-in-leapp","title":"How to Configure Multi Console in Leapp","text":""},{"location":"built-in-features/multi-console/#install-the-extension","title":"Install the Extension","text":""},{"location":"built-in-features/multi-console/#firefox","title":"Firefox","text":"
You can get the extension on the official Mozilla Addons Store and install it from there:
Visit the page by clicking the button below
Then Click on Add to Firefox
Get it on Firefox \u21e9
"},{"location":"built-in-features/multi-console/#chrome-edge-and-other-chromium-based-browsers","title":"Chrome, Edge and other Chromium based browsers","text":"
Info
Because the extension at the moment relies on Manifest V2, we are unable to upload the extension on the official stores. For more info see Chrome extension documentation
The extension can only be installed manually. To do so, follow these instructions:
Download the zip archive by clicking on the button below
Unzip the file
Open your browser and navigate to about://extensions
Enable Developer mode in the top right corner
Then click on Load unpacked in the top left corner
Finally, Select the folder extracted previously
Get it on Chrome/Others \u21e9
"},{"location":"built-in-features/multi-console/#uninstall-the-extension","title":"Uninstall the Extension","text":""},{"location":"built-in-features/multi-console/#firefox_1","title":"Firefox","text":"
Visit about:addons
Select Leapp Browser Extension and click on the 3 dots
Click on Remove
"},{"location":"built-in-features/multi-console/#chrome-edge-and-other-chromium-based-browsers_1","title":"Chrome, Edge and other Chromium based browsers","text":"
Visit about://extensions
Search for Leapp Browser Extension and click on Remove
See warning section below
Warning
If you are using the Chrome version and you uninstalled or disabled the extension, you have to manually clear cookies for the AWS Console. To do so, when accessing the login page of the AWS Console, on the left of the address bar, click the lock icon and select \"Cookies\". Then, remove all cookies by clicking \"Remove\" until the cookie list is empty and finally click on Done
"},{"location":"built-in-features/multi-console/#how-to-use-it","title":"How to use it","text":"
Once you've installed the extension on your browser, you need to enable the Multi-Console Extension on the Leapp Desktop App in order to use it.
Click on the top-right cog icon to access the settings, click on the Multi-Console tab and then click Enable Multi-Console Extension.
enable option
From the contextual menu of a session (accessed by right-clicking on it), simply select Open Web Console.
Info
If any communication error occurs, your browser is not open or you don't have the extension installed/enabled on it, the web console will be opened in your default browser without using the extension (and will be limited to a single session).
By clicking on the Leapp Multi-Console Extension icon in your browser, a list of all currently active sessions will be shown.
This list contains information obtained from Leapp about the session, including Session Name, Session Role and Session Region.
leapp browser ui
In the extension interface, click on a row to select and focus the tab in which you opened the related AWS Console, so you can easily navigate among many AWS Consoles at the same time.
"},{"location":"built-in-features/opening-web-console/","title":"Configure Open Web Console","text":""},{"location":"built-in-features/opening-web-console/#what-is-open-web-console","title":"What is Open Web Console","text":"
Open Web Console is a Leapp feature that allows you to open the AWS Web Console of a session that you've created in Leapp.
"},{"location":"built-in-features/opening-web-console/#how-to-configure-open-web-console-in-leapp","title":"How to Configure Open Web Console in Leapp","text":"
You can open the AWS Web Console directly from Leapp, without having to log in, input your credentials, or select the role to assume.
To do that just right-click or select the session you want to open in the web console, and click on the icon either in the context-menu or in the bottom-bar below.
Alternatively, you can Command + left-click on a session (or Control + left-click for Windows/Linux ) to open the web console.
Leapp will open your default browser with the Region and the Role already prepared for you in the account you've selected.
note: to use this feature correctly, remember to logout from any web console already opened in the browser.
note: the feature currently is available for IAM Role Federated Sessions, Single Sign-On Sessions, and IAM Role Chained Sessions.
"},{"location":"cli/","title":"Index","text":"
Leapp's Command Line Interface.
Warning
Leapp CLI works only if the Desktop App is installed and running. Note that version >= v0.11.0 of the Desktop App is required. Check the installation guide to install the Desktop App.
"},{"location":"cli/scopes/help/#leapp-help-commands","title":"leapp help [COMMANDS]","text":"
Display help for leapp.
USAGE\n $ leapp help [COMMANDS] [-n]\n\nARGUMENTS\n COMMANDS Command to show help for.\n\nFLAGS\n -n, --nested-commands Include all nested commands in the output.\n\nDESCRIPTION\n Display help for leapp.\n
USAGE\n $ leapp idp-url delete [--idpUrlId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --idpUrlId=<value> the idp url id that we want to pass to the function like the delete one\n\nDESCRIPTION\n Delete an identity provider URL\n\nEXAMPLES\n $leapp idp-url delete\n\n $leapp idp-url delete --idpUrlId ID\n\n $leapp idp-url delete --idpUrlId ID [--force, -f]\n
USAGE\n $ leapp idp-url edit [--idpUrlId <value>] [--idpUrl <value>]\n\nFLAGS\n --idpUrl=<value> the idp url address we want to create\n --idpUrlId=<value> the idp url id that we want to pass to the function like the delete one\n\nDESCRIPTION\n Edit an identity provider URL\n\nEXAMPLES\n $leapp idp-url edit\n\n $leapp idp-url edit --idpUrlId ID --idpUrl ADDRESS\n
USAGE\n $ leapp idp-url list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show identity providers list\n\nEXAMPLES\n $leapp idp-url list\n
USAGE\n $ leapp integration create [--integrationAlias <value>] [--integrationPortalUrl <value>] [--integrationRegion <value>]\n [--integrationType AWS-SSO|AZURE] [--integrationTenantId <value>] [--integrationLocation <value>]\n\nFLAGS\n --integrationAlias=<value> alias that identifies an integration\n --integrationLocation=<value> Location of an Azure Integration\n --integrationPortalUrl=<value> url that identifies the integration portal where you authenticate\n --integrationRegion=<value> an AWS valid region code for the integration\n --integrationTenantId=<value> Tenant ID of an Azure Integration\n --integrationType=<option> Identify the type of your integration. Valid types are [AWS-SSO, AZURE]\n <options: AWS-SSO|AZURE>\n\nDESCRIPTION\n Create a new integration\n\nEXAMPLES\n $leapp integration create\n\n $leapp integration create --integrationType AWS-SSO --integrationAlias ALIAS --integrationPortalUrl URL --integrationRegion REGION\n\n $leapp integration create --integrationType AZURE --integrationAlias ALIAS --integrationTenantId TENANT --integrationLocation LOCATION\n
USAGE\n $ leapp integration delete [--integrationId <value>]\n\nFLAGS\n --integrationId=<value> the Integration Id used to identify the integration inside Leapp\n\nDESCRIPTION\n Delete an integration\n\nEXAMPLES\n $leapp integration delete\n\n $leapp integration delete --integrationId ID\n
USAGE\n $ leapp integration list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show integrations list\n\nEXAMPLES\n $leapp integration list\n
USAGE\n $ leapp integration logout [--integrationId <value>]\n\nFLAGS\n --integrationId=<value> the Integration Id used to identify the integration inside Leapp\n\nDESCRIPTION\n Logout from an integration\n\nEXAMPLES\n $leapp integration logout\n\n $leapp integration logout --integrationId ID\n
USAGE\n $ leapp profile create [--profileName <value>]\n\nFLAGS\n --profileName=<value> an AWS named profile Alias used to identify the profile in both config and credential file\n\nDESCRIPTION\n Create a new AWS named profile\n\nEXAMPLES\n $leapp profile create\n\n $leapp profile create --profileName PROFILENAME\n
USAGE\n $ leapp profile delete [--profileId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --profileId=<value> an AWS named profile ID in Leapp\n\nDESCRIPTION\n Delete an AWS named profile\n\nEXAMPLES\n $leapp profile delete\n\n $leapp profile delete --profileId PROFILEID\n\n $leapp profile delete --profileId PROFILEID [--force, -f]\n
USAGE\n $ leapp profile edit [--profileId <value>] [--profileName <value>]\n\nFLAGS\n --profileId=<value> an AWS named profile ID in Leapp\n --profileName=<value> an AWS named profile Alias used to identify the profile in both config and credential file\n\nDESCRIPTION\n Rename an AWS named profile\n\nEXAMPLES\n $leapp profile edit\n\n $leapp profile edit --profileId ID --profileName PROFILENAME\n
USAGE\n $ leapp profile list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show profile list\n\nEXAMPLES\n $leapp profile list\n
"},{"location":"cli/scopes/region/#leapp-region-get-default","title":"leapp region get-default","text":"
Displays the default region
USAGE\n $ leapp region get-default\n\nDESCRIPTION\n Displays the default region\n\nEXAMPLES\n $leapp region get-default\n
"},{"location":"cli/scopes/region/#leapp-region-set-default","title":"leapp region set-default","text":"
Change the default region
USAGE\n $ leapp region set-default [--region <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n\nDESCRIPTION\n Change the default region\n\nEXAMPLES\n $leapp region set-default\n\n $leapp region set-default --region AWSREGION\n
USAGE\n $ leapp session add [--providerType aws] [--accessKey <value>] [--idpArn <value>] [--idpUrl <value>]\n [--mfaDevice <value>] [--sessionName <value>] [--parentSessionId <value>] [--profileId <value>] [--region <value>]\n [--roleArn <value>] [--roleSessionName <value>] [--secretKey <value>] [--sessionType\n awsIamRoleFederated|awsIamUser|awsIamRoleChained]\n\nFLAGS\n --accessKey=<value> AWS Access Key ID of the IAM User\n --idpArn=<value> AWS IAM Federated Role IdP Arn value, obtain it from your AWS Account\n --idpUrl=<value> the idp url address we want to create\n --mfaDevice=<value> MFA Device Arn retrieved from your AWS Account\n --parentSessionId=<value> For AWS IAM Role Chained is the session Id of the session that will assume the chained\n role. Retrieve it using $leapp session list -x\n --profileId=<value> an AWS named profile ID in Leapp\n --providerType=<option> Identify the provider for your sessions. Valid types are [aws]\n <options: aws>\n --region=<value> Session Region for AWS sessions in Leapp\n --roleArn=<value> AWS IAM Federated Role Arn value, obtain it from your AWS Account\n --roleSessionName=<value> Optional Alias for the Assumed Role Session name\n --secretKey=<value> AWS Secret Access Key of the IAM User\n --sessionName=<value> Session Alias to identify the session in Leapp\n --sessionType=<option> Identify the AWS session type. Valid types are [awsIamRoleFederated, awsIamUser,\n awsIamRoleChained]\n <options: awsIamRoleFederated|awsIamUser|awsIamRoleChained>\n\nDESCRIPTION\n Add a new session\n\nEXAMPLES\n $leapp session add\n\n $leapp session add --providerType [aws] --sessionType [awsIamRoleFederated, awsIamRoleChained, awsIamUser] --region [AWSREGION] --sessionName NAME ...[combination of flags relative to the session]\n\n $leapp session add --providerType aws --sessionType awsIamRoleFederated --sessionName NAME --region AWSREGION --idpArn IDPARN --idpUrl IDPURL --profileId PROFILEID --roleArn ROLEARN\n\n $leapp session add --providerType aws --sessionType awsIamRoleChained --sessionName NAME --region AWSREGION --profileId PROFILEID --roleArn ROLEARN --parentSessionId ID (--roleSessionName ROLESESSIONNAME)\n\n $leapp session add --providerType aws --sessionType awsIamUser --sessionName NAME --region AWSREGION --profileId PROFILEID --accessKey ACCESSKEY --secretKey SECRETKEY (--mfaDevice MFADEVICEARN)\n
USAGE\n $ leapp session change-profile [--sessionId <value>] [--profileId <value>]\n\nFLAGS\n --profileId=<value> an AWS named profile ID in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Change a session named-profile\n\nEXAMPLES\n $leapp session change-profile\n\n $leapp session change-profile --profileId PROFILEID --sessionId SESSIONID\n
USAGE\n $ leapp session change-region [--sessionId <value>] [--region <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Change a session region\n\nEXAMPLES\n $leapp session change-region\n\n $leapp session change-region --sessionId SESSIONID --region REGION\n
Provides info about the current active session for a selected profile (if no profile is provided, it uses the profile default)
USAGE\n $ leapp session current [-i] [-p <value>] [-r aws|azure] [-f <value>]\n\nFLAGS\n -f, --format=<value> allows formatting data to show\n - aws -> id alias, accountNumber, roleArn\n - azure -> id tenantId, subscriptionId\n -i, --inline\n -p, --profile=<value> [default: default] aws named profile of which gets info\n -r, --provider=<option> filters sessions by the cloud provider service\n <options: aws|azure>\n\nDESCRIPTION\n Provides info about the current active session for a selected profile (if no profile is provided, it uses the profile\n default)\n\nEXAMPLES\n $leapp session current --format \"alias accountNumber\" --inline --provider aws\n
USAGE\n $ leapp session delete [--sessionId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Delete a session\n\nEXAMPLES\n $leapp session delete\n\n $leapp session delete --sessionId SESSIONID\n\n $leapp session delete --sessionId SESSIONID [--force, -f]\n
Generate STS temporary credentials for the given AWS session id
USAGE\n $ leapp session generate SESSIONID\n\nARGUMENTS\n SESSIONID id of the session\n\nDESCRIPTION\n Generate STS temporary credentials for the given AWS session id\n\nEXAMPLES\n $leapp session generate 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d\n
Show sessions list with all properties; filter query is case sensitive
USAGE\n $ leapp session list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show sessions list with all properties; filter query is case sensitive\n\nEXAMPLES\n $leapp session list\n\n $leapp session list --filter=\"ID=Foo\" -x\n\n $leapp session list --filter=\"Session Name=Foo\"\n\n $leapp session list --filter=\"Type=Foo\"\n\n $leapp session list --filter=\"Named Profile=Foo\"\n\n $leapp session list --filter=\"Region/Location=Foo\"\n\n $leapp session list --filter=\"Status=Foo\"\n
USAGE\n $ leapp session open-web-console [--sessionId <value>] [-p]\n\nFLAGS\n -p, --print Print an AWS Web Console login URL in the terminal instead of opening the web browser\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Open an AWS Web Console\n\nEXAMPLES\n $leapp session open-web-console\n\n $leapp session open-web-console --sessionId SESSIONID [--print, -p]\n
USAGE\n $ leapp session run-aws-credential-plugin [--sessionId <value>] [--pluginName <value>]\n\nFLAGS\n --pluginName=<value> Unique name of a Leapp Plugin\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Run a Leapp Plugin\n\nEXAMPLES\n $leapp session run-plugin\n\n $leapp session run-plugin --sessionName SESSIONAME --pluginName PLUGINNAME\n
USAGE\n $ leapp session start [SESSIONNAME] [--sessionId <value>] [--sessionRole <value>] [--noInteractive]\n\nARGUMENTS\n SESSIONNAME Name of the Leapp session\n\nFLAGS\n --noInteractive If the specified session is not unique or doesn't exist, throw an error without starting the\n interactive session selection mode\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --sessionRole=<value> Session Role of one or more sessions in Leapp\n\nDESCRIPTION\n Start a session\n\nEXAMPLES\n $leapp session start\n\n $leapp session start SESSIONNAME\n\n $leapp session start SESSIONNAME --sessionRole SESSIONROLE\n\n $leapp session start SESSIONNAME --noInteractive\n\n $leapp session start --sessionId SESSIONID\n
USAGE\n $ leapp session start-ssm-session [--sessionId <value>] [--region <value>] [--ssmInstanceId <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --ssmInstanceId=<value> Instance ID for EC2 instance we want to access with SSM\n\nDESCRIPTION\n Start an AWS SSM session\n\nEXAMPLES\n $leapp session start-ssm-session\n\n $leapp session start-ssm-session --sessionId SESSIONID --region AWSREGION --ssmInstanceId EC2INSTANCEID\n
USAGE\n $ leapp session stop [SESSIONNAME] [--sessionId <value>] [--sessionRole <value>] [--noInteractive]\n\nARGUMENTS\n SESSIONNAME Name of the Leapp session\n\nFLAGS\n --noInteractive If the specified session is not unique or doesn't exist, throw an error without starting the\n interactive session selection mode\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --sessionRole=<value> Session Role of one or more sessions in Leapp\n\nDESCRIPTION\n Stop a session\n\nEXAMPLES\n $leapp session stop\n\n $leapp session stop SESSIONNAME\n\n $leapp session stop SESSIONNAME --sessionRole SESSIONROLE\n\n $leapp session stop SESSIONNAME --noInteractive\n\n $leapp session stop --sessionId SESSIONID\n
USAGE\n $ leapp set-workspace [WORKSPACENAME]\n\nARGUMENTS\n WORKSPACENAME name of the Leapp Team remote workspace or local\n\nDESCRIPTION\n Set the current Leapp workspace\n\nEXAMPLES\n $leapp team set-workspace\n\n $leapp team set-workspace local\n\n $leapp team set-workspace WORKSPACE-NAME\n
USAGE\n $ leapp workspace\n\nDESCRIPTION\n Show the current workspace\n\nEXAMPLES\n $leapp workspace\n
See code: dist/commands/workspace.ts
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/","title":"Configure an AWS Identity Center (ex AWS Single Sign-On) integration","text":""},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#what-is-aws-identity-center-ex-aws-single-sign-on","title":"What is AWS Identity Center (ex AWS Single Sign-On)","text":"
AWS Identity Center (ex AWS Single Sign-On) is a cloud service that allows you to grant your users access to AWS resources across multiple AWS accounts.
AWS SSO provides a directory that you can use to create users, organize them in groups, and set permissions across those groups; alternatively, you can obtain them from your Microsoft Active Directory or any standards-based identity provider, such as Okta Universal Directory or Azure AD.
After logging in the first time, Leapp will map all your roles and users into Sessions.
Info
To get started using AWS SSO refer to this guide.
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#how-to-configure-an-aws-identity-center-ex-aws-single-sign-on-integration-in-leapp","title":"How to configure an AWS Identity Center (ex AWS Single Sign-On) integration in Leapp","text":"
Click on the Add Integration button in the sidebar.
Select AWS Single Sign-On as the Integration type.
Provide the required information (described in the next section).
Click on the Add integration button.
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#required-information","title":"Required information","text":"Field Description INTEGRATION TYPE Set as AWS Single Sign-on AWS SSO URL The portal URL to begin the authentication flow. It usually follows this pattern: d-xxxxxxxxxx.awsapps.com/start. REGION The region on which AWS SSO is administered and configured. This is NOT where your generated credentials will be valid; it's only used for the login part."},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-integration/configure-azure-integration/","title":"Configure an Azure integration","text":""},{"location":"configuring-integration/configure-azure-integration/#what-is-an-azure-integration","title":"What is an Azure integration","text":"
Our Leapp integration refers to Azure Tenant which is a dedicated and trusted instance of Azure AD.
The tenant is automatically created when your organization signs up for a Microsoft cloud service subscription.
These subscriptions include Microsoft Azure, Microsoft Intune, or Microsoft 365.
An Azure tenant represents a single organization and can have multiple subscriptions.
Please refer to How to find your Azure Active Directory tenant ID and other Azure AD documentation for more information.
Warning
For azure-cli users with version < 2.30.0: Leapp no longer supports this version of the CLI. Please update to a newer version.
To create a new Azure Integration, go to the left sidebar of Leapp Desktop and click on the icon. A new modal will be presented with the following option to compile. After submitting the new Integration and have logged into your Azure Portal, Subscriptions will be automatically retrieved and mapped into Leapp Azure Sessions.
"},{"location":"configuring-integration/configure-azure-integration/#how-to-configure-an-azure-integration-in-leapp","title":"How to configure an Azure integration in Leapp","text":"
Click on the Add Integration button in the sidebar.
Select Azure as the Integration type.
Provide the required information (described in the next section).
Click on the Add integration button.
"},{"location":"configuring-integration/configure-azure-integration/#required-information","title":"Required information","text":"Field Description INTEGRATION TYPE Set as Azure ALIAS Your friendly integration name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. TENANT ID A tenant ID identifies a tenant. You can have multiple clients on a given tenant database. LOCATION The Azure datacenters are located around the world in strategic places that best meet the customer demands. These areas are known as Azure locations. Specific services requires the user to select a specific location. The value is retrieved from your default location in general options."},{"location":"configuring-integration/configure-azure-integration/#video-tutorial","title":"Video tutorial","text":"
Info
Azure sessions are not available anymore for direct creation. Instead you can create a new Azure Integration.
"},{"location":"configuring-session/configure-aws-iam-role-chained/","title":"Configure AWS IAM Role Chained","text":""},{"location":"configuring-session/configure-aws-iam-role-chained/#what-is-an-aws-iam-role-chained-session","title":"What is an AWS IAM Role Chained session","text":"
An AWS IAM Role Chained session represents an AWS role chaining access. Role chaining is the process of assuming a role starting from another IAM role or user.
An IAM role has some similarities to an IAM user. Roles and users are both AWS identities with permissions policies that determine what the identity can and cannot do in AWS. However, instead of being uniquely associated with one person, a role is intended to be assumable by anyone who needs it.
A role does not have standard long-term credentials such as a password or access keys associated with it. Instead, when you assume a role, it provides you with temporary security credentials for your role session.
Role chaining occurs when you use a role to assume a second role through the AWS CLI or API, even in other accounts.
Info
Refer to this guide to delegate access across AWS accounts using IAM Roles chaining.
"},{"location":"configuring-session/configure-aws-iam-role-chained/#how-to-configure-an-aws-iam-role-chained-in-leapp","title":"How to configure an AWS IAM Role Chained in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM Role Chained as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-role-chained/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. ROLE ARN Your IAM Role unique ID. The active Session will refer to this Role. ROLE SESSION NAME Your session name. You can query and search this on AWS Cloudtrail or any other linked audit service to find out what action were performed by the linked Identity. ASSUMER SESSION Your session from which this Role will be assumed. The assume-role call will be automatically made by Leapp."},{"location":"configuring-session/configure-aws-iam-role-chained/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-aws-iam-role-federated/","title":"Configure AWS IAM Role Federated","text":""},{"location":"configuring-session/configure-aws-iam-role-federated/#what-is-an-aws-iam-role-federated-session","title":"What is an AWS IAM Role Federated session","text":"
An AWS IAM Role Federated session represents an access type that relies on a federation between an AWS account and an external Identity Provider.
AWS Identity and Access Management (IAM) supports identity federation for delegated access to the AWS Management Console or AWS APIs. With identity federation, external identities are granted secure access to resources in your AWS accounts through IAM roles.
These external identities can come from your corporate identity provider (such as Microsoft Active Directory or from the AWS Directory Service) or from a web identity provider (such as Amazon Cognito, Login with Amazon, Facebook, Google, or any OpenID Connect-compatible provider).
We currently only support SAML 2.0 federation.
Info
Refer to this guide to provision your own federated roles.
Refer to this guide to configure and trust your SAML 2.0 Identity Provider.
Is your SAML 2.0 Identity Provider not included in the above list? Please, refer to the FAQ to add a new one.
"},{"location":"configuring-session/configure-aws-iam-role-federated/#how-to-configure-an-aws-iam-role-federated-in-leapp","title":"How to configure an AWS IAM Role Federated in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM Role Federated as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-role-federated/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. SAML 2.0 URL Your SAML URL interface to start the authentication flow and log into your Identity provider. AWS IDENTIY PROVIDER ARN Your Identity Provider ID in AWS. You can find it in IAM section Identity Providers. ROLE ARN Your IAM Role unique ID. The active Session will refer to this Role."},{"location":"configuring-session/configure-aws-iam-role-federated/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-aws-iam-user/","title":"Configure AWS IAM User","text":""},{"location":"configuring-session/configure-aws-iam-user/#what-is-an-aws-iam-user-session","title":"What is an AWS IAM User session","text":"
An AWS Identity and Access Management (IAM) user is an entity that you create in AWS to represent the person or application that uses it to interact with AWS.
An IAM User in AWS consists of a name and a set of long-term credentials. Leapp never sets these values in the configuration files, and automatically generates and refreshes a set of short-term credentials.
Info
If you want to know how Leapp generates and refresh short-term credentials refer to the credentials generation section in the documentation.
"},{"location":"configuring-session/configure-aws-iam-user/#how-to-configure-an-aws-iam-user-in-leapp","title":"How to configure an AWS IAM User in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM User as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-user/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. MFA DEVICE Your MFA device ID to set up multi-factor authentication. ACCESS KEY ID Your long-term Access Key. It will be used to generate a short-term set of credentials. Don't disclose it to anyone. SECRET ACCESS KEY Your long-term Secret Key. It will be used to generate a short-term set of credentials. Don't disclose it to anyone. Add AWS IAM User Screen"},{"location":"configuring-session/configure-aws-iam-user/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-localstack/","title":"Configure LocalStack","text":""},{"location":"configuring-session/configure-localstack/#what-is-a-localstack-session","title":"What is a LocalStack session","text":"
With LocalStack you can emulate AWS cloud services with a fully functional cloud stack on your local machine. Develop and test your cloud applications with the full cloud experience, but without the hassle of the remote cloud.
You can use Leapp to create a LocalStack session that can then be used to set your local credential file and access your LocalStack resources.
Info
You need to install LocalStack in order to use the AWS cloud emulation features
"},{"location":"configuring-session/configure-localstack/#how-to-configure-a-localstack-session-in-leapp","title":"How to configure a LocalStack session in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select LocalStack as the Cloud Provider.
Provide a name for the session.
Click on the Create Session button.
Warning
LocalStack sessions work only with AWS Credential Method configured with the credential-file-method option. The option is available in the Options menu > General > Generics > AWS Credential Method.
Warning
In order to use the credential file to access LocalStack from your AWS CLI, you must update the AWS CLI to the latest version.
Contributions and questions are not just welcome, they\u2019re essential! Please open issues with ideas on how to improve Leapp, including feedback, critiques, and information about how you\u2019re using it. Discussion is at the heart of the project and your thoughts and ideas will help make it better for everyone, thank you.
Read our contribution guide to learn more.
You can chat with us in our community, so join us, or feel free to contact us via the website!
Join our Community
"},{"location":"installation/install-leapp/","title":"Install Leapp","text":""},{"location":"installation/install-leapp/#install-leapp-app","title":"Install Leapp App","text":""},{"location":"installation/install-leapp/#macos-windows-and-linux","title":"MacOS, Windows, and Linux","text":"
You can install Leapp by downloading the pre-built binaries for your OS on the website release page:
Download Leapp \u21e9
Unzip the package and double-click the executable to install.
You can install Leapp CLI through a Homebrew Formula:
brew install Noovolari/brew/leapp-cli\n
In Linux it may happen that the command leapp is not recognized. In that case we suggest to run the following command:
brew link leapp-cli\n
"},{"location":"installation/install-leapp/#install-leapp-cli-on-macos-with-arm64-chip-m1-m2","title":"Install Leapp CLI on macOS with ARM64 chip (M1, M2)","text":"
On macOS with ARM64 chip you can use the Homebrew Formula:
All the available commands are listed in the Leapp CLI section of the documentation.
Warning
Leapp CLI will work only if the Desktop App is installed and running.
"},{"location":"installation/requirements/","title":"Requirements","text":""},{"location":"installation/requirements/#requirements","title":"Requirements","text":""},{"location":"installation/requirements/#macos-and-windows","title":"MacOS and Windows","text":"
There are no requirements for macOS and Windows users.
Leapp uses libsecret and gnome-keyring as dependencies to store all sensitive data into the keyring. Depending on your distribution, you may need to install them using these commands before running Leapp.
"},{"location":"installation/requirements/#logging-into-ec2-instances-via-aws-ssm-with-leapp","title":"Logging into EC2 Instances via AWS SSM with Leapp","text":"
In order to use AWS SSM on your System through Leapp, you must be able to execute this command on your own at least once, when the correct credentials are active.
Leapp checks if a new version is available every 10 minutes (starting from the application launch). If so, a dialog message will pop up and show a version number, the release date and the changelog
In this modal, a user can do the following:
Remind me laterDownload updateClick on X
Leapp will close the modal and notify the user that a new update is available by adding a notification dot to the Dock Bar icon. Users will not be bothered anymore until the next release is available. This option is convenient for users that want to stick to a specific version. Note that you can do this for every version and maintain the one you prefer.
Leapp will open the Release URL in your default browser to let the User manually download the release for their specific OS and install it.
Leapp will close the modal and another one will appear in 10 minutes.
"},{"location":"installation/update-leapp/#macos-homebrew-linux-linuxbrew-and-windows-via-wsl","title":"macOS (Homebrew), Linux (Linuxbrew) and Windows (via WSL)","text":"
Leapp can also be updated via Homebrew Cask with: brew upgrade leapp
Depending on which method you used to install the CLI (npm or Homebrew on macOS), you can update it with the following commands:
npmHomebrew (macOS)
npm update -g @noovolari/leapp-cli\n
brew upgrade Noovolari/brew/leapp-cli\n
"},{"location":"leapp-pro/security-and-password/","title":"Security and password","text":""},{"location":"leapp-pro/security-and-password/#password-issues","title":"Password issues","text":""},{"location":"leapp-pro/security-and-password/#can-i-recover-my-password","title":"Can I recover my password?","text":"
Unfortunately, it is not possible to recover the master password. The master password is very important as it's the key point of our zero-knowledge encryption mechanism. If you forget it, you'll lose access to the previously encrypted Leapp Sessions and Integrations. That's why it is crucial that you keep your password safe; we suggest you to store it in a password manager like 1Password.
"},{"location":"leapp-pro/security-and-password/#how-is-my-data-encrypted","title":"How is my data encrypted?","text":"
All information associated with your stored data is protected with end-to-end encryption. Leapp Sessions and Integrations are encrypted before being forwarded to the backend. Specifically, Leapp Pro uses AES 256-bit encryption as well as PBKDF-SHA512 to secure your data.
AES is a standard in cryptography and is used by the U.S. government and other government agencies around the world for protecting top-secret data. With proper implementation and a strong encryption key (your Master Password), AES is considered unbreakable.
PBKDF-SHA512 is used to derive the encryption key from your master password. Then this key is salted and hashed for authenticating with the Leapp Pro backend. The default iteration count used with PBKDF2 is 500,000 iterations on the client. Each Secret has its own generated symmetric key; this symmetric key is encrypted using the user\u2019s public RSA key (this is also the foundation of the Secret sharing system). This encryption and decryption are done entirely on the Leapp Pro clients because your master password is never stored on or transmitted to Leapp Team backend.
It is important to highlight the fact that the backend does not act as a credentials broker, i.e. it has no visibility on the long-term/short-term credentials used by Leapp Pro Desktop App/CLI to access the cloud providers. In addition, the secrets retrieved from the backend, are an encrypted version of access configurations; access configurations DO NOT include temporary credentials. There is a single edge case: the IAM User. Indeed, the IAM User Session access configuration contains IAM User\u2019s access keys, which are long-term credentials. Still, the Leapp Pro backend has no visibility on these long-term credentials, as they\u2019re encrypted by the client before being forwarded to the Leapp Team backend.
When you unlock Leapp Pro, using a longer and more secure account password is easier than you might otherwise have chosen.
"},{"location":"leapp-pro/security-and-password/#your-fingerprint-is-not-stored-in-leapp","title":"Your fingerprint is not stored in Leapp.","text":"
Leapp never scans or stores your fingerprint. Touch ID is provided by macOS, which only tells Leapp Pro if your fingerprint was recognized or not.
Learn more about Touch ID's advanced security technology.
"},{"location":"leapp-pro/synchronization/","title":"Synchronization","text":""},{"location":"leapp-pro/synchronization/#whats-a-pro-workspace","title":"What's a Pro Workspace","text":"
A Pro Workspace is a new Workspace that is created upon first login with your registered Pro User. This workspace is synchronized with your Cloud account every time you create, edit, or delete an integration or a session; this way it is possible to use Leapp Pro on different devices, maintaining all your saved integrations and sessions.
"},{"location":"leapp-pro/synchronization/#how-the-synchronization-works","title":"How the Synchronization works","text":"
Synchronization works by encrypting all your sessions and integrations with your master password, created during your sign-up process. This way we maintain a 0-knowlegde approach on your data through all the lifecycle of your Pro workspace.
The encrypted data is then saved in the Cloud on your Leapp Pro personal space.
You, as a Leapp Pro user, can always keep an eye on the status of synchronization using the synchronization widget in the bottom-left area of Leapp.
Synchronization widget - synchronization active and done
When all the data is correctly synchronized you'll see the image above.
When Leapp Pro is synchronizing you'll see the icon and text changing to the one in the image below.
Synchronization widget - synchronization in progress
If you eventually lose connection or have a problem in synchronizing your data the widget will turn yellow as shown below.
Synchronization widget - synchronization failed
You have the possibility to manually trigger another synchronization process and see if the problem is resolved.
Info
When Leapp Pro is restarted it will try to synchronize your data in the Cloud if you're logged in, so you can also close Leapp safely even if in synch failed state.
"},{"location":"leapp-pro/synchronization/#do-you-have-any-trouble-with-synchronization","title":"Do you have any trouble with Synchronization","text":"
In case of any troubles locking Leapp Pro workspace please contact us.
Leapp Pro enable Users to protect their Cloud access with Username and password.
With Leapp Pro you can back up and synchronize your Leapp workspace and access to any device you want without losing your access configurations.
"},{"location":"leapp-pro/getting-started/#getting-started-guide","title":"Getting started guide","text":"
Sign up to Leapp Pro
Sign in to Leapp Pro
Lock your Leapp Pro Workspace
"},{"location":"leapp-pro/getting-started/#security-and-syncronization","title":"Security and syncronization","text":"
Once you updgrade your Plan to Leapp Pro, your local Workspace will be moved to the Pro Workspace. All the data inside your workspace are secured with end-to-end encryption through your Master password.
"},{"location":"leapp-pro/getting-started/lock/","title":"Lock your Workspace","text":"
Leapp Pro allows the user to temporary lock the workspace, making it accessible only by typing again your master-password. This feature provides a further security level on top of the standard Leapp Community edition.
"},{"location":"leapp-pro/getting-started/lock/#how-to-lock-the-leapp-pro-workspace","title":"How to lock the Leapp Pro workspace","text":"
To lock your Leapp Pro workspace you should click on the Workspace button located in the top-left area and select the Lock option.
Workspace button Lock option
The Leapp Pro lock screen should appear, prompting for your master-password.
Leapp Pro lock screen"},{"location":"leapp-pro/getting-started/lock/#touch-id","title":"Touch ID","text":"
You can also use your fingerprint to unlock Leapp if your PC is Touch ID compatible. After Logging to your Pro workspace for the first time, Leapp will associate your workspace with your system Touch ID. After that the option will be available and can also be tweaked in the general tab of the option menu.
"},{"location":"leapp-pro/getting-started/lock/#troubles-in-locking-your-workspace","title":"Troubles in locking your Workspace","text":"
In case of any troubles locking Leapp Pro workspace please contact us.
With Leapp Pro you can always sign-in from any location, gaining instant access to your personal workspace.
"},{"location":"leapp-pro/getting-started/sign-in/#sign-in-to-leapp-pro","title":"Sign-in to Leapp Pro","text":"
After upgrading Leapp Community edition, you can sign-in at any time, just clicking on the Workspace button located in the top-left area and selecting the Sign-in Workspace option.
Workspace button Sign-in Workspace option
The Sign-in Workspace dialog will appear. Enter your Email address, master-password and click on the Add Workspace button.
Sign-in dialog
If the information entered is correct, your Leapp Pro workspace will be displayed and you can immediately use it to manage your cloud credentials.
Leapp Pro Workspace
To avoid unwanted access, you can lock your Leapp Pro workspace at any time.
"},{"location":"leapp-pro/getting-started/sign-in/#troubles-in-signing-in-to-leapp-pro","title":"Troubles in signing in to Leapp Pro?","text":"
In case of any troubles signing in to Leapp Pro please contact us.
A Leapp Pro upgrade is required to enable new workspace features like Cloud access from multiple locations and Workspace locking.
"},{"location":"leapp-pro/getting-started/sign-up/#sign-up-to-leapp-pro","title":"Sign-up to Leapp Pro","text":"
To sign up for Leapp Pro you should upgrade your version of Leapp Community edition. Click on the Options button in the top-right area.
Settings button
In the Options dialog, select the Plans tab and click on Upgrade to Pro button.
Plans tab
The upgrade window should appear. Enter your email (it will be the email address associated with your Leapp Pro account) and click on the Upgrade now button.
Upgrade window
At this point a window will appear, so you can specify a payment method to complete the Leapp Pro upgrade. After the payment process you will receive a confirmation email containing the Complete the registration link.
Upgrade email
Clicking the link in the confirmation email will open a web page that will allow you to enter your personal info and the master-password, essential to provide the security requirements of Leapp Pro.
Sign-up page
After entering your personal info and the master-password click the Continue button. You can now finally sign in to Leapp Pro.
"},{"location":"leapp-pro/getting-started/sign-up/#troubles-in-signing-up-to-leapp-pro","title":"Troubles in signing up to Leapp Pro?","text":"
In case of any troubles signing up to Leapp Pro please contact us.
"},{"location":"leapp-pro/getting-started/sign-up/#how-to-sign-in","title":"How to Sign-in","text":"
Take a look to this page to sign-in your Leapp Pro workspace.
argument type description message string the message to show level LogLevel severity of the message display boolean shows the message in a toast in the desktop app when true. Otherwise, log it in the log files"},{"location":"plugins/plugins-development/#fetch","title":"fetch","text":"
fetch(url: string): any
Retrieve the content of a URL. Returns a promise for the URL
argument type description url string a valid HTTP URL to fetch from"},{"location":"plugins/plugins-development/#openexternalurl","title":"openExternalUrl","text":"
openExternalUrl(url: string): void
Open an external URL in the default browser
argument type description url string a valid HTTP URL to open in the default browser"},{"location":"plugins/plugins-development/#createsession","title":"createSession","text":"
Creates a new Leapp Session based on given SessionData
argument type description createSessionData SessionData the metadata used to create the Leapp Session"},{"location":"plugins/plugins-development/#clonesession","title":"cloneSession","text":"
cloneSession(session: Session): Promise<string>
This method allows you to clone the given Leapp Session. This operation is allowed for the following Leapp Session types:
AwsIamUserSession
AwsIamRoleFederatedSession
AwsIamRoleChainedSession
argument type description session Session the Leapp Session that I want to clone"},{"location":"plugins/plugins-development/#updatesession","title":"updateSession","text":"
This method allows you to update the given session with the given updateSessionData. This operation is allowed for the following Leapp Session types:
AwsIamUserSession
AwsIamRoleFederatedSession
AwsIamRoleChainedSession
argument type description updateSessionData SessionData the metadata used to update the given Leapp Session session Session the Leapp Session that I want to update"},{"location":"plugins/plugins-development/#openterminal","title":"openTerminal","text":"
Execute the given command in the platform-specific terminal; optionally, it is possible to set an env key/value object containing the env variables to export in the terminal, before the command execution.
The terminal window base path is set to the home directory.
argument type description command string the command that I want to execute in the platform-specific terminal env any optional key/value env variables object"},{"location":"plugins/plugins-development/#getprofileidbyname","title":"getProfileIdByName","text":"
getProfileIdByName(profileName: string): string
Returns the id of a named profile from its name if it exists, otherwise creates a new profile and returns its id.
Can be used when creating/editing a session since SessionData requires the id of a named profile
argument type description profileName string a valid named profile"},{"location":"plugins/plugins-development/#getidpurlidbyurl","title":"getIdpUrlIdByUrl","text":"
getIdpUrlIdByUrl(url: string): string
Return the ID of the IdpUrl object from the given URL if it exists, otherwise creates a new IdP URL and returns its ID.
Can be used when creating/editing Federated Sessions since SessionData requires the ID of an IdP URL.
argument type description url string the URL associated with the IdpUrl I want to retrieve"},{"location":"plugins/plugins-development/#example-display-a-toast-message-in-leapp","title":"Example: display a toast message in Leapp","text":"
Return a valid FontAwesome 5 code. Override default value in package.json
"},{"location":"plugins/plugins-development/#example-display-a-session-based-message-in-leapp","title":"Example: display a session-based message in Leapp","text":"
async applySessionAction(session: Session, credentials: any): Promise<void> {\nif(session.type === Session.awsIamUser) {\nthis.pluginEnvironment.log(`This is an IAM User session: ${session.sessionName}`, LogLevel.info, true); }\nelse {\nthis.pluginEnvironment.log(`This is NOT an IAM User session: ${session.sessionName}`, LogLevel.info, true);\n}\n}\n
"},{"location":"plugins/plugins-development/#packagejson-metadata","title":"package.json metadata","text":"property values description constraints name a custom string the name of the plugin the same used in the plugin folder author a custom string the name of the author none version a custom string the version of the plugin must be a semver string description a custom string the description of the plugin none keywords a string array the name of the plugin must contain at least \"leapp-plugin\" leappPlugin an object the plugin custom configuration must contain at least \"supportedOS\" and \"supportedSessions\" leappPlugin.supportedOS a string array [\"mac\", \"windows\", \"linux\"] if not specified, all OSs will be considered compatible leappPlugin.supportedSessions a string array [\"anyType, \"aws\", \"azure\", \"awsIamRoleFederated\", \"awsIamRoleChained\", \"awsSsoRole\", \"awsIamUser\"] at least one of these values must be specified leappPlugin.icon a custom string fontAwesome code for an icon (e.g. \"fa fa-globe\") must be a valid FontAwesome 5 code"},{"location":"plugins/plugins-development/#plugin-examples","title":"Plugin Examples","text":""},{"location":"plugins/plugins-development/#open-web-console","title":"Open Web Console","text":"
import { Session } from \"@noovolari/leapp-core/models/session\";\nimport { AwsCredentialsPlugin } from \"@noovolari/leapp-core/plugin-sdk/aws-credentials-plugin\";\nimport { PluginLogLevel } from \"@noovolari/leapp-core/plugin-sdk/plugin-log-level\";\n\nexport class WebConsolePlugin extends AwsCredentialsPlugin {\nget actionName(): string {\nreturn \"Open web console\";\n}\n\nget actionIcon(): string {\nreturn \"fa fa-globe\";\n}\n\nasync applySessionAction(session: Session, credentials: any): Promise<void> {\nthis.pluginEnvironment.log(\"Opening web console for session: \" + session.sessionName, PluginLogLevel.info, true);\n\nconst sessionRegion = session.region;\nconst sessionDuration = 3200;\nconst isUSGovCloud = sessionRegion.startsWith(\"us-gov-\");\nlet federationUrl;\nlet consoleHomeURL;\n\nif (!isUSGovCloud) {\nfederationUrl = \"https://signin.aws.amazon.com/federation\";\nconsoleHomeURL = `https://${sessionRegion}.console.aws.amazon.com/console/home?region=${sessionRegion}`;\n} else {\nfederationUrl = \"https://signin.amazonaws-us-gov.com/federation\";\nconsoleHomeURL = `https://console.amazonaws-us-gov.com/console/home?region=${sessionRegion}`;\n}\n\nif (sessionRegion.startsWith(\"cn-\")) {\nthrow new Error(\"Unsupported Region\");\n}\n\nthis.pluginEnvironment.log(\"Starting opening Web Console\", PluginLogLevel.info, true);\n\nconst sessionStringJSON = {\nsessionId: credentials.sessionToken.aws_access_key_id,\nsessionKey: credentials.sessionToken.aws_secret_access_key,\nsessionToken: credentials.sessionToken.aws_session_token,\n};\n\nconst queryParametersSigninToken = `?Action=getSigninToken&SessionDuration=${sessionDuration}&Session=${encodeURIComponent(\nJSON.stringify(sessionStringJSON)\n)}`;\n\nconst res = await this.pluginEnvironment.fetch(`${federationUrl}${queryParametersSigninToken}`);\nconst response = await res.json();\n\nconst loginURL = `${federationUrl}?Action=login&Issuer=Leapp&Destination=${consoleHomeURL}&SigninToken=${(response as any).SigninToken}`;\nthis.pluginEnvironment.openExternalUrl(loginURL);\n}\n}\n
"},{"location":"plugins/plugins-introduction/","title":"Introduction to Plugins","text":"
This section provides an overview of Leapp\u2019s plugins, which can be used to extend the functionality of Leapp.
Plugins are commonly used when more advanced and custom behavior is needed, for example using Leapp-generated temporary credentials to run custom actions.
You can create your own plugins or import custom ones created by the community. You can also publish your plugins on npm to make them available to everyone easily.
"},{"location":"plugins/plugins-introduction/#add-a-plugin","title":"Add a Plugin","text":"
To add a plugin you can use one of the following methods:
"},{"location":"plugins/plugins-introduction/#add-from-npm","title":"Add from npm","text":"
From the Leapp option menu, go to the Plugins tab. Insert the name of the npm package for the plugin and click on the plus icon to add it to your plugins
Go to Options by clicking the top right gear icon then click the Plugins tab. Click the Folder Icon. This will open the plugin folder inside .Leapp.
Here, manually create a folder with the same name as your plugin package.json name property and move your package.json and bundled plugin.js files inside this folder.
Alternatively, you can simply move your entire plugin folder cloned from the example template.
Lastly, from the Leapp Plugins tab in the Option menu, click on the refresh icon to reload all plugins.
Warning
Adding plugins is at your own risk! We cannot currently guarantee that a plugin is safe, so BE CAREFUL when you install something from an unknown source. A plugin verification system is under development and will be available later this year.
"},{"location":"plugins/plugins-introduction/#disable-a-plugin","title":"Disable a Plugin","text":"
To disable a Leapp plugin, go to Options by clicking the top right gear icon then click the Plugins tab.
Toggle Enabled for the plugin you want to disable.
"},{"location":"plugins/plugins-introduction/#remove-a-plugin","title":"Remove a Plugin","text":"
To remove a Leapp plugin, go to Options by clicking the top right gear icon then click the Plugins tab.
Click the Folder Icon. This will open the plugin folder inside .Leapp. From here, locate the folder containing the plugin you want to remove and simply delete the folder.
"},{"location":"plugins/plugins-introduction/#run-a-plugin","title":"Run a Plugin","text":"
You can run a plugin both from Leapp Desktop App and Leapp CLI.
From Leapp Desktop App, right click on a session to open the contextual menu, click on Plugins, and select the plugin you want to run
Info
This contextual menu option is not available if you have no plugins that you can run on the selected session and/or your operating system.
From Leapp CLI, you can use the command leapp session run-plugin. For more information on how to use this CLI command, see the documentation.
Click on the top right gear icon to go to the Leapp option menu and then select the tab Plugin.
From there, you can see a list of currently installed plugins, check whether a plugin is compatible with your system or not, which session types it supports and disable/enable it if you need.
"},{"location":"plugins/plugins-introduction/#create-your-plugin","title":"Create your Plugin","text":"
You can start creating a plugin from the template.
Leapp plugins are written in TypeScript. They must contain at least a class that extends a base class provided by the Plugin SDK.
There's currently only one of these classes, AwsCredentialsPlugin , that can be used to create a plugin that generates temporary credentials.
Every Leapp plugin must at least have a package.json file and a plugin.js file.
leapp-plugin/ \n \u251c\u2500\u2500 package.json # Plugin metadata\n \u2514\u2500\u2500 plugin.js # A webpack bundle for the main logic\n
Create your Plugin
"},{"location":"security/credential-process/","title":"Credential Process","text":""},{"location":"security/credential-process/#what-is-credential-process","title":"What is Credential Process?","text":"
Credential Process is a configuration option (in the AWS config file) that instruct the AWS CLI and SDKs to use an external command to generate valid credentials in a specific format.
It is a way to generate AWS compatible credentials on the fly, only when requested by tools that respect the AWS credential chain.
Credential Process is perfect if you have a way to generate or look up credentials that isn't directly supported by the AWS CLI or third-party tools; for example, you can configure the AWS CLI to use it by configuring the credential_process setting in the config file.
The difference between Credential Process and Standard Credential file is that credentials in the \"credential file\" are written in plain text and so, they are potentially unsecure, even if temporary. Credential Process instead, generates credentials that are consumed only when they are effectively needed.
No credential is written in any file. They are printed on the stdout and consumed upon request.
"},{"location":"security/credential-process/#how-credential-process-works","title":"How Credential Process works?","text":"
Credential Process asks an external process to generate an AWS compatible temporary credential set in this format:
{\n\"Version\": 1,\n\"AccessKeyId\": \"an AWS access key\",\n\"SecretAccessKey\": \"your AWS secret access key\",\n\"SessionToken\": \"the AWS session token for temporary credentials\", \"Expiration\": \"ISO8601 timestamp when the credentials expire\"\n}
The Expiration field allows the generated credentials to be cached and reused until they are no more valid (by default the value is 3600s=1h).
Ensures that no credential set is written on your machine in neither the ~/.aws/credentials or ~/.aws/config files.
Ensures your long-running tasks always have valid credentials during their lifecycle.
Is compatible with named-profiles.
Is a way to make third-party tool compatible with AWS SSO and SAML Federated IAM Principals even if they don't support them natively.
As stated by this article by Ben Kehoe, Credential Process is a good way to avoid cluttering the credential file with temporary credentials.
Warning
Temporary credentials in the credentials file reduce potential blast radius in case of machine exploit but they require to be refreshed every time they expire.
"},{"location":"security/credential-process/#how-leapp-works-with-credential-process","title":"How Leapp works with Credential Process","text":"
Info
Requirements: this credentials generation method requires that both Leapp desktop app and CLI are installed.
1) Open your Leapp desktop app and go to the settings panel ().
2) In the general section change the AWS Credential Generation from \"credential-file-method\" to \"credential-process-method\".
3) An informative panel will show up telling that you need the CLI installed (see below), click on \"I acknowledge it\"
warning modal
4) Now, everytime you click on start () an entry will be created in the ~/.aws/config file with the following format:
5) You can start more than one session, depending on how many named-profile you've created; for every session started with a unique named-profile, a new entry will be created in the config file.
Info
AWS CLI, SDks, and third-party tools that can read credentials from the config file can reach AWS services with this method.
Leapp is built with a security-first approach. Every piece of information that has to be persisted is encrypted and saved on your workstation.
We devised two main methods to store data, based on its sensitiveness.
Data Persistence and encryption Examples Operational All information used to make Leapp work, not strictly tied to direct access to cloud environments. Stored and encrypted in a configuration file within the user workspace. Named profiles, proxy configurations, etc. Sensitive Information that can be used, or potentially exploited, to gain access to cloud environments. Stored in the System Vault, leveraging its own integrated encryption. Static credentials, access tokens, cached data, etc."},{"location":"security/intro/#end-to-end-encryption","title":"End-to-end Encryption","text":"
We leverage Zero-Knowledge to provide end-to-end encryption on tiers that require to save your data outside of your workstation to deliver specific features.
Zero Knowledge is designed so that no one, except you, can access your secured data.
Warning
We CAN'T access your data under any circumstances, even if you ask us to!
Information that can be used, or potentially exploited, to gain access to cloud environments are stored your workstation's System Vault, leveraging its own integrated encryption. The user can access the secrets stored in the System Vault at any time, using their user password.
Leapp uses Keytar as an interface to the secure vault on macOS, Windows and Linux systems.
Every key is stored in the vault under the name Leapp. In the description, you will find the underlying name used by Leapp to retrieve the secret.
"},{"location":"security/system-vault/#supported-system-vaults","title":"Supported System Vaults","text":"OS System Vault MacOS Keychain Windows Credential Vault Linux API/Libsecret
Info
We're currently supporting only System Vaults installed by default on the OS. We're planning on extending support to other vaults and online password managers (LastPass, BitWarden, 1Password, etc.). If you'd like other services to be supported feel free to open an Issue or make a Pull Request (check our contributing guidelines).
To persist your configuration online, we implemented Zero-Knowledge encryption to prevent access to your information. But how can you trust a company to keep all of your secrets secret? The answer lies in end-to-end encryption, which lays the groundwork for applications with Zero-Knowledge architectures.
Zero-knowledge refers to policies and architecture that eliminate the possibility for secret managers themselves to access your password.
Warning
This is implemented to save your configuration online in the PRO and TEAM versions of Leapp. Don't know yet about the PRO and TEAM versions? Check our roadmap.
Info
This same process is leveraged by Bitwarden to store their password.
"},{"location":"security/zero-knowledge/#users-have-key-control","title":"Users have key control","text":"
When users have complete control of the encryption key, they control access to the data, providing encrypted information to Leapp without Leapp having access to or knowledge of that data.
Info
To know more about this, you can find the whitepaper on which we based our implementation of Zero-Knowledge end-to-end encryption.
During any phase of the registration and login process the client does not provide any password-related info to the server.
The server does not store any information that can be used to guess the password in a convenient way. In other words, the system must not be prone to brute force or dictionary attacks.
Any sensible data is encrypted client-side, the server will work with encrypted blocks only.
All the implementation is released as open-source.
Temporary security credentials created by AssumeRoleWithSAMLResponse last for one hour. However, you can use the optional DurationSeconds parameter to specify the duration of your session.
Your role session lasts for the specified duration, or until the time specified in the SAML authentication response's SessionNotOnOrAfter value, whichever is shorter. You can provide a DurationSeconds value from 900 seconds (15 minutes) up to the maximum session duration setting for the role. This setting can have a value from 1 hour to 12 hours.
Leapp sets the token duration to 1 hour.
Info
\u26a0\ufe0f In this case, generated credentials are not \"cached\" in the keychain.
The GetSessionToken operation must be called by using the long-term AWS security credentials of the AWS IAM user. Credentials that are created by IAM users are valid for the duration that you specify. This duration can range from 900 seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours), with a default of 43,200 seconds (12 hours). Credentials based on account credentials can range from 900 seconds (15 minutes) up to 3,600 seconds (1 hour), with a default of 1 hour.
Leapp sets the token duration to 10 hours.
Info
These are the only temporary credentials that are stored in the System vault and not rotated, unless expired.
The access token is valid for 8 hours as noted in the expiresAt timestamp in the JSON file. Expired tokens must be re-authenticated using the get-role-credentials API call.
Azure generates a set of access and refresh tokens that are put inside the msal_token_cache.json file inside the .azure directory. Following is the procedure used to generate a set of credentials.
Info
In Windows OS the msal_token_cache is persisted on an encrypted file with dpapi API. Starting from release 2.30 of Azure CLI, credentials are no more persisted in the original accessToken.json
Azure Users profile info is saved in the azureProfile.json file inside the .azure directory.
Before accessing Azure sessions, you now have to create an Azure integration. After that, these are the steps required to log in and then retrieve Azure sessions.
msal_token_cache and azureProfile.json files are cleaned for security reasons.
We execute az login --tenantId <TENANTID>. We do this to obtain the updated user profile and the refresh token (associated to this integration).
We extract all the Azure subscriptions associated with the integration and for each one we map a Leapp Azure session.
We extract the refresh token, account, and profile information from msal_token_cache and azureProfile.json and persist them in the System's vault.
We also remove the previous information from the original files, to increase security and avoid external tampering.
In the current version of Leapp we can only start one Azure session at a time.
For each subscription retrieved upon login to a specific integration, we define a new Leapp Azure Session. To start an Azure session we follow these steps.
Recover refresh token, account, and profile information from the Vault and we use them alongside sessionId (Subscription id) in the start operation.
azureProfile.json is only filled with profile information from the current subscription.
We write the account information and the refresh token back in the msal_token_cache
We execute az account get-access-token --subscriptionId <SUBSCRIPTIONID>, to retrieve the access token and the id token of the subscription.
The previous command also writes access and id token back to the msal_token_cache file.
We update the expiration time of the session to the current datetime.
We update the refresh token in the Vault with the new information.
We remove the refresh token from the msal_token_cache.
We finally start the session.
Info
The refresh token is a long term credential that potentially lasts for 90 days. The access token is a short term credential and lasts for 70 minutes. Source
Please always add logs to any issue you want to fill whenever possible, so you can help the team identify the problem quickly
"},{"location":"troubleshooting/faq/","title":"FAQ","text":""},{"location":"troubleshooting/faq/#im-using-the-open-source-app-do-you-store-my-data-online","title":"I'm using the open-source app, do you store my data online?","text":"
NO.
The open-source software doesn't transfer, persist, or share anything with other services. All your data is secured and encrypted on your workstation.
Nobody can access it, not even ourselves.
"},{"location":"troubleshooting/faq/#ive-got-a-paid-tier-how-do-you-manage-my-data-can-you-access-it","title":"I've got a paid tier, how do you manage my data? Can you access it?","text":"
We can't and don't want to see any of your access data.
We need to store your data online to enable some features (syncing, managing other users, etc.) but we implement a Zero-Knowledge encryption system that prevents even ourselves to access your data.
"},{"location":"troubleshooting/faq/#i-dont-feel-secure-using-a-built-in-window-for-authentication-cant-you-use-the-default-browser","title":"I don't feel secure using a built-in window for authentication, can't you use the default browser?","text":"
In the future, Leapp will only use the default browser to authenticate. Right now, this is a compromise to deliver the authentication flow. We already ported the AWS SSO authentication flow on the default browser, and we're working on migrating the other ones as soon as possible.
"},{"location":"troubleshooting/faq/#how-can-i-find-leapp-data-in-the-system-vault","title":"How can I find Leapp data in the System Vault?","text":"
Every key stored by Leapp in the vault is named Leapp. The account name shows the description of the element saved by our software.
"},{"location":"troubleshooting/faq/#where-do-i-find-the-leapp-logs","title":"Where do I find the Leapp logs?","text":"
Head to the Application data section.
"},{"location":"troubleshooting/faq/#ssm-terminal-is-opening-but-no-session-is-starting-what-can-i-do","title":"SSM terminal is opening but no session is starting, what can I do?","text":"
Just close the terminal and relaunch the SSM command.
"},{"location":"troubleshooting/faq/#aws-cli-or-az-cli-is-installed-but-leapp-cant-find-it-what-can-i-do","title":"AWS CLI (or AZ CLI) is installed but Leapp can't find it, what can I do?","text":"
Leapp on macOS works in sandbox mode, so some terminal commands must be symlinked in order to work on some installations. Just make a symlink pointing from /usr/local/bin/aws to the actual aws binary or, for AZ CLI, from /usr/local/bin/az to the actual az binary. To create symlinks on macOS, use this command ln -s /any/file/on/the/disk linked-file. The command is called ln. If used with the option -s it will create a symbolic link in the current directory.
"},{"location":"troubleshooting/faq/#i-use-leapp-session-current-but-want-to-see-the-alias-and-not-the-id","title":"I use leapp session current but want to see the alias and not the id.","text":""},{"location":"troubleshooting/faq/#setting-up-leappalias-command","title":"Setting up leappalias command","text":"
Follow these steps to set up the leappalias command in your Zsh shell:
Create a script file named leappalias.sh using a text editor:
Save the file and make it executable by running the following command in the terminal:
chmod +x leappalias.sh\n
Move the script to a directory in your system's PATH. For example, /usr/local/bin/:
sudo mv leappalias.sh /usr/local/bin/leappalias\n
Open your zshrc file using a text editor:
nano ~/.zshrc\n
Define an alias for executing the script by adding the following line to the zshrc file:
alias leappalias='/usr/local/bin/leappalias'\n
Save the changes and close the zshrc file.
Reload the zshrc file in the terminal using the following command:
source ~/.zshrc\n
Once you have completed these steps, you can use the leappalias command in your terminal to extract and display the alias from the output of leapp session current. Credit goes to bspansinQdo.
"},{"location":"troubleshooting/faq/#how-can-i-add-support-to-a-new-saml-20-identity-provider","title":"How can I add support to a new SAML 2.0 Identity Provider?","text":"
To add support to a new SAML 2.0 Identity Provider, you have to perform the following steps:
create a Fork of the Noovolari/leapp GitHub repository;
create a Pull Request and set up your local environment following Install dependencies and build packages section of the DEVELOPMENT.md;
add the Identity Provider-specific authentication URL RegEx filter to the Leapp Core authenticationUrlRegexes Map;
follow the last part of the Install dependencies and build packages section of the DEVELOPMENT.md to build the solution for both the CLI and the Desktop App;
push your changes to your forked repository and propose to merge them to the main repository.
If you need more details about the implementation, please check the How to add a new SAML IdP preset authentication URL section of the DEVELOPMENT.md.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Overview","text":""},{"location":"#overview","title":"Overview","text":""},{"location":"#welcome-to-leapp","title":"Welcome to Leapp","text":"
Leapp is a tool for developers to manage, secure, and access the cloud.
All data is persisted and encrypted on your workstation. Head to our Security section to know how we guarantee the highest level of security.
Leapp Main Window
The name Leapp is based on the word leap and is pronounced /l:ip/. We chose this name because the project enables you to be one step away from your cloud environments.
"},{"location":"edit-session/","title":"Editing a session","text":"
Leapp allows the user to edit an existing session excluding those generated from an AWS integration.
Info
Integration derived Sessions can\u2019t be changed
To edit an existing session just right-click on a session in the Leapp list (see below), and select \"edit session\". A new modal will appear, allowing the user to choose which parameters to change.
edit session
Below are the configuration options for every type of session:
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Mfa Device (optional): can be left empty or, if you add a valid device name or AWS ARN, it will prompt a modal for MFA code
Access Key ID: Replace your session Access Key ID in the system vault
Secret Access Key: Replace your session Secret Access Key in the system vault
"},{"location":"edit-session/#iam-role-chained","title":"IAM Role Chained","text":"
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Role ARN: The role that you'll assume when chaining from an assumer window
Role Session Name: (optional), it will be used to identify the chained session
Assumer Session: select a session from the list, it will be the Principal assuming the role
Info
You can also generate a new IAM Role Chained session from any other AWS session by right-clicking on a session and chosing \"Create Chained Session\"
"},{"location":"edit-session/#iam-role-federated","title":"IAM Role Federated","text":"
Session Alias: the session name can be changed, as a session is identified by a hidden id
Named Profile: you can change a named profile and the session, if active, will restart itself
AWS Region: you can change the region and the session will restart itself, if active
Role ARN: Role of the Principal in AWS
SAML 2.0 Url: Federated URL needed for authentication to AWS
Identity Provider: the identity provider ARN that you have set up on AWS
After modifying all the parameters, a user can test their validity with test credential generation:
Clicking this button allows Leapp to do a dry run on your parameters, and if valid, a new set of credentials will be generated (but not used) and an informative toast will appear to tell you that they can be used successfully.
"},{"location":"edit-session/#how-we-handle-secrets-when-editing-a-session","title":"How we handle Secrets when Editing a Session","text":"
No secrets will be saved in plain text on your machine. Leapp saves secrets by replacing values in the system keychain, using a combination of an informative name plus the session hidden id.
This way we reduce potential blast radius of an attacker tampering your machine.
When editing a session, Leapp will hide your secrets and you are also unable to copy/paste them from the App.
This section provides an overview of Leapp's integrations, useful to extend the functionality of Leapp to 3rd party services.
Integrations help manage access and identities on your service of choice while using Leapp during your daily activities. They are automatically mapped into Sessions.
Integrations have four main actions available: Create, Delete, Sync, and Logout.
Action Description CREATE Configure a new Integration with the data needed to start the authentication flow. Required to Sync and map the service response into Sessions. DELETE Remove an existing Integration. Removes all the associated Sessions as well and wipes everything related to the Integration from the system (tokens, cache, etc.) SYNC Start the authentication flow to log into the Integration Provider. Leapp will automatically retrieve all the related data and map the response into Sessions. Any change in your service of choice requires a manual Sync to reflect the current status. LOGOUT Disable the Integration. Removes all the Sessions but keeps the Integration data. Running a Sync will restore all the Sessions tied to it."},{"location":"integrations/#supported-services","title":"Supported Services","text":"Service Supported AWS SSO Okta Coming Soon OneLogin Coming Soon AzureAD"},{"location":"sessions/","title":"Sessions","text":""},{"location":"sessions/#sessions","title":"Sessions","text":"
A Session contains all the relevant information to let the dev connect to a cloud provider. Three standard actions should be implemented for each session: start, stop, and rotate.
"},{"location":"sessions/#actions","title":"Actions","text":"Method Description START \u00a0Make the temporary credentials available to the provider chain STOP \u00a0Removes the temporary credentials from the provider chain ROTATE \u00a0Generate new temporary credentials, and substitute the previous ones in the provider chain
The process of setting up Leapp Sessions is managed either manually, for each access method, or through integrations with third-party tools. Leapp stores all the Sessions available to the users locally, inside a configuration file called Workspace.
A Workspace is a global configuration that contains all the relevant information about your Leapp setup (sessions, integrations, app preferences, etc.).
There are two types of workspace: Local and Remote.
A Local workspace is the default workspace that comes with your Leapp installation. It's a private configuration that contains your personal preferences and all sessions and integrations that you created yourself.
A local workspace is associated to a single machine and if you need to migrate your configuration to another one you will have to do it manually.
A Remote workspace is a Leapp Team configuration set created remotely by a Leapp Team manager.
When you sync a remote workspace, you will receive sessions and integrations automatically, without having to configure them yourself.
A remote workspace is persisted online by using Zero-Knowledge encryption.
You will have access to the same configurations instantly on any machine, by logging in to your Leapp Team account after having been invited by your Leapp Team manager.
Info
Both your local and remote workspaces are saved on your machine as encrypted files inside your /.Leapp directory.
The actions below only applies to Remote workspaces.
Action Description Sign-in \u00a0Connect to a Remote workspace. This action will not switch your Local workspace Switch \u00a0Switch to the selected workspace by clicking on its name in the workspace menu Lock \u00a0Switch back to the Local workspace disabling all the Remote ones Sign-out \u00a0Sign-out from a Remote workspace removing all your login details
Info
The Lock action also removes the encrypted files associated to your remote workspaces.
"},{"location":"built-in-features/aws-ec2-connect/","title":"Configure AWS EC2 Connect","text":""},{"location":"built-in-features/aws-ec2-connect/#what-is-aws-ec2-connect","title":"What is AWS EC2 Connect","text":"
Amazon EC2 Instance Connect is a simple and secure way to connect to your instances using Secure Shell (SSH). With EC2 Instance Connect, you can control SSH access to your instances using AWS Identity and Access Management (IAM) policies as well as audit connection requests with AWS CloudTrail events.
"},{"location":"built-in-features/aws-ec2-connect/#how-to-configure-aws-ec2-connect-in-leapp","title":"How To configure AWS EC2 Connect in Leapp","text":"
Warning
If your Leapp Desktop App is warning you that you're missing the AWS Session Manager Plugin, please install it following this official guide.
You can directly connect to an AWS EC2 instance from Leapp through AWS System Manager (AWS SSM).
Info
To setup SSM follow this SSM guide on AWS guide.
example image from AWS
To correctly connect follow these steps:
Right-click on a suitable AWS session to open the contextual menu.
Click on View SSM sessions.
Select the AWS region in which your instance is located.
Wait for Leapp to load your instances.
Select the instance and click connect.
Wait for the terminal to open.
Focus the terminal window and write /bin/bash; press Enter and you'll be inside the terminal of your instance.
If the user is not granted the right permissions, the operation will fail and Leapp will throw an error message.
"},{"location":"built-in-features/aws-named-profiles/","title":"Configure Named Profiles","text":""},{"location":"built-in-features/aws-named-profiles/#what-is-a-named-profile","title":"What is a Named Profile","text":"
Named Profiles are used by AWS to maintain more than one set of active credentials for you to use with AWS-CLI, SDK, or other third-party tools. Named profiles are stored in ~/.aws/credentials file in the ini file format.
Named Profiles have a default profile which is the one you get from aws configure command.
With Leapp you can group and activate more than one credential set at a time through Named Profiles.
"},{"location":"built-in-features/aws-named-profiles/#how-to-configure-a-named-profile-in-leapp","title":"How to configure a Named Profile in Leapp","text":"
Named Profiles can be created in 3 ways:
Option PanelWhen creating a new SessionEdit Profile in Contextual Menu
Click on the gear icon and select the Profiles tab. Insert the name of the new Named Profile in the input form, then click on the plus icon.
When creating a new session, the user will have the option to choose a Named Profile or add a new one.
Right-click on a session and select Change then Named Profile: an option to select or add a new Named Profile will be available.
The new name is directly added to the Named Profile list and can then be used for other sessions too.
Info
AWS SSO sessions will have the Named Profile default when obtained via Login or Sync. To change the Named Profile associated to a session you have to use the \"Change Profile\" option in the session list.
Named profiles can be managed from the Option menu.
In the Option menu, under the Profiles tab, you can add or edit a new Named Profile, and you can also remove unwanted ones. When removing a Named Profile, Leapp will warn you about which sessions are using that profile, and those sessions will be reverted to the default Named Profile.
The input form can be used to add or edit a Named Profile: if it's empty, you can use it to add a new named profile. When selecting the button, you will be able to edit the name of the Named Profile from within the input form.
Warning
Remember that when you change the profile of a session, the session will be immediately put in stop mode. That's because Leapp would have to change the credential file, so you will need to restart the session again.
Once you've opened the Leapp option menu - which can be accessed by clicking the top right gear icon - you can edit the following settings in the General tab
This option allows you to set the default AWS or Azure region/location for every new session.
Each time you create a new session, this will be the default region assigned to it.
You can still change it if you need a different one, by selecting a different region while creating the session or by changing the region once a session is created.
This option is used to select the terminal in which to open an SSM session.
Info
This setting is currently only available on MacOS. If you want to contribute and add a new terminal for a specific OS, please refer to the contributing guide
This option is used to set the default Webconsole session duration in hours.
Info
The minimum session duration is 1 hour, and can be set to a maximum of 12 hours. Set session duration
"},{"location":"built-in-features/multi-console/","title":"Configure Multi Console","text":""},{"location":"built-in-features/multi-console/#what-is-multi-console","title":"What is Multi Console","text":"
The Leapp Multi-Console Browser Extension allows you to open multiple instances of the AWS Web Console in the same browser window and helps you in managing them.
Get it on Firefox \u21e9 Get it on Chrome \u21e9"},{"location":"built-in-features/multi-console/#list-of-supported-browsers","title":"List of Supported Browsers","text":"Browser Supported Firefox Chrome Edge Brave Safari"},{"location":"built-in-features/multi-console/#how-to-configure-multi-console-in-leapp","title":"How to Configure Multi Console in Leapp","text":""},{"location":"built-in-features/multi-console/#install-the-extension","title":"Install the Extension","text":""},{"location":"built-in-features/multi-console/#firefox","title":"Firefox","text":"
You can get the extension on the official Mozilla Addons Store and install it from there:
Visit the page by clicking the button below
Then Click on Add to Firefox
Get it on Firefox \u21e9
"},{"location":"built-in-features/multi-console/#chrome-edge-and-other-chromium-based-browsers","title":"Chrome, Edge and other Chromium based browsers","text":"
Info
Because the extension at the moment relies on Manifest V2, we are unable to upload the extension on the official stores. For more info see Chrome extension documentation
The extension can only be installed manually. To do so, follow these instructions:
Download the zip archive by clicking on the button below
Unzip the file
Open your browser and navigate to about://extensions
Enable Developer mode in the top right corner
Then click on Load unpacked in the top left corner
Finally, Select the folder extracted previously
Get it on Chrome/Others \u21e9
"},{"location":"built-in-features/multi-console/#uninstall-the-extension","title":"Uninstall the Extension","text":""},{"location":"built-in-features/multi-console/#firefox_1","title":"Firefox","text":"
Visit about:addons
Select Leapp Browser Extension and click on the 3 dots
Click on Remove
"},{"location":"built-in-features/multi-console/#chrome-edge-and-other-chromium-based-browsers_1","title":"Chrome, Edge and other Chromium based browsers","text":"
Visit about://extensions
Search for Leapp Browser Extension and click on Remove
See warning section below
Warning
If you are using the Chrome version and you uninstalled or disabled the extension, you have to manually clear cookies for the AWS Console. To do so, when accessing the login page of the AWS Console, on the left of the address bar, click the lock icon and select \"Cookies\". Then, remove all cookies by clicking \"Remove\" until the cookie list is empty and finally click on Done
"},{"location":"built-in-features/multi-console/#how-to-use-it","title":"How to use it","text":"
Once you've installed the extension on your browser, you need to enable the Multi-Console Extension on the Leapp Desktop App in order to use it.
Click on the top-right cog icon to access the settings, click on the Multi-Console tab and then click Enable Multi-Console Extension.
enable option
From the contextual menu of a session (accessed by right-clicking on it), simply select Open Web Console.
Info
If any communication error occurs, your browser is not open or you don't have the extension installed/enabled on it, the web console will be opened in your default browser without using the extension (and will be limited to a single session).
By clicking on the Leapp Multi-Console Extension icon in your browser, a list of all currently active sessions will be shown.
This list contains information obtained from Leapp about the session, including Session Name, Session Role and Session Region.
leapp browser ui
In the extension interface, click on a row to select and focus the tab in which you opened the related AWS Console, so you can easily navigate among many AWS Consoles at the same time.
"},{"location":"built-in-features/opening-web-console/","title":"Configure Open Web Console","text":""},{"location":"built-in-features/opening-web-console/#what-is-open-web-console","title":"What is Open Web Console","text":"
Open Web Console is a Leapp feature that allows you to open the AWS Web Console of a session that you've created in Leapp.
"},{"location":"built-in-features/opening-web-console/#how-to-configure-open-web-console-in-leapp","title":"How to Configure Open Web Console in Leapp","text":"
You can open the AWS Web Console directly from Leapp, without having to log in, input your credentials, or select the role to assume.
To do that just right-click or select the session you want to open in the web console, and click on the icon either in the context-menu or in the bottom-bar below.
Alternatively, you can Command + left-click on a session (or Control + left-click for Windows/Linux ) to open the web console.
Leapp will open your default browser with the Region and the Role already prepared for you in the account you've selected.
note: to use this feature correctly, remember to logout from any web console already opened in the browser.
note: the feature currently is available for IAM Role Federated Sessions, Single Sign-On Sessions, and IAM Role Chained Sessions.
"},{"location":"cli/","title":"Index","text":"
Leapp's Command Line Interface.
Warning
Leapp CLI works only if the Desktop App is installed and running. Note that version >= v0.11.0 of the Desktop App is required. Check the installation guide to install the Desktop App.
"},{"location":"cli/scopes/help/#leapp-help-commands","title":"leapp help [COMMANDS]","text":"
Display help for leapp.
USAGE\n $ leapp help [COMMANDS] [-n]\n\nARGUMENTS\n COMMANDS Command to show help for.\n\nFLAGS\n -n, --nested-commands Include all nested commands in the output.\n\nDESCRIPTION\n Display help for leapp.\n
USAGE\n $ leapp idp-url delete [--idpUrlId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --idpUrlId=<value> the idp url id that we want to pass to the function like the delete one\n\nDESCRIPTION\n Delete an identity provider URL\n\nEXAMPLES\n $leapp idp-url delete\n\n $leapp idp-url delete --idpUrlId ID\n\n $leapp idp-url delete --idpUrlId ID [--force, -f]\n
USAGE\n $ leapp idp-url edit [--idpUrlId <value>] [--idpUrl <value>]\n\nFLAGS\n --idpUrl=<value> the idp url address we want to create\n --idpUrlId=<value> the idp url id that we want to pass to the function like the delete one\n\nDESCRIPTION\n Edit an identity provider URL\n\nEXAMPLES\n $leapp idp-url edit\n\n $leapp idp-url edit --idpUrlId ID --idpUrl ADDRESS\n
USAGE\n $ leapp idp-url list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show identity providers list\n\nEXAMPLES\n $leapp idp-url list\n
USAGE\n $ leapp integration create [--integrationAlias <value>] [--integrationPortalUrl <value>] [--integrationRegion <value>]\n [--integrationType AWS-SSO|AZURE] [--integrationTenantId <value>] [--integrationLocation <value>]\n\nFLAGS\n --integrationAlias=<value> alias that identifies an integration\n --integrationLocation=<value> Location of an Azure Integration\n --integrationPortalUrl=<value> url that identifies the integration portal where you authenticate\n --integrationRegion=<value> an AWS valid region code for the integration\n --integrationTenantId=<value> Tenant ID of an Azure Integration\n --integrationType=<option> Identify the type of your integration. Valid types are [AWS-SSO, AZURE]\n <options: AWS-SSO|AZURE>\n\nDESCRIPTION\n Create a new integration\n\nEXAMPLES\n $leapp integration create\n\n $leapp integration create --integrationType AWS-SSO --integrationAlias ALIAS --integrationPortalUrl URL --integrationRegion REGION\n\n $leapp integration create --integrationType AZURE --integrationAlias ALIAS --integrationTenantId TENANT --integrationLocation LOCATION\n
USAGE\n $ leapp integration delete [--integrationId <value>]\n\nFLAGS\n --integrationId=<value> the Integration Id used to identify the integration inside Leapp\n\nDESCRIPTION\n Delete an integration\n\nEXAMPLES\n $leapp integration delete\n\n $leapp integration delete --integrationId ID\n
USAGE\n $ leapp integration list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show integrations list\n\nEXAMPLES\n $leapp integration list\n
USAGE\n $ leapp integration logout [--integrationId <value>]\n\nFLAGS\n --integrationId=<value> the Integration Id used to identify the integration inside Leapp\n\nDESCRIPTION\n Logout from an integration\n\nEXAMPLES\n $leapp integration logout\n\n $leapp integration logout --integrationId ID\n
USAGE\n $ leapp profile create [--profileName <value>]\n\nFLAGS\n --profileName=<value> an AWS named profile Alias used to identify the profile in both config and credential file\n\nDESCRIPTION\n Create a new AWS named profile\n\nEXAMPLES\n $leapp profile create\n\n $leapp profile create --profileName PROFILENAME\n
USAGE\n $ leapp profile delete [--profileId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --profileId=<value> an AWS named profile ID in Leapp\n\nDESCRIPTION\n Delete an AWS named profile\n\nEXAMPLES\n $leapp profile delete\n\n $leapp profile delete --profileId PROFILEID\n\n $leapp profile delete --profileId PROFILEID [--force, -f]\n
USAGE\n $ leapp profile edit [--profileId <value>] [--profileName <value>]\n\nFLAGS\n --profileId=<value> an AWS named profile ID in Leapp\n --profileName=<value> an AWS named profile Alias used to identify the profile in both config and credential file\n\nDESCRIPTION\n Rename an AWS named profile\n\nEXAMPLES\n $leapp profile edit\n\n $leapp profile edit --profileId ID --profileName PROFILENAME\n
USAGE\n $ leapp profile list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show profile list\n\nEXAMPLES\n $leapp profile list\n
"},{"location":"cli/scopes/region/#leapp-region-get-default","title":"leapp region get-default","text":"
Displays the default region
USAGE\n $ leapp region get-default\n\nDESCRIPTION\n Displays the default region\n\nEXAMPLES\n $leapp region get-default\n
"},{"location":"cli/scopes/region/#leapp-region-set-default","title":"leapp region set-default","text":"
Change the default region
USAGE\n $ leapp region set-default [--region <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n\nDESCRIPTION\n Change the default region\n\nEXAMPLES\n $leapp region set-default\n\n $leapp region set-default --region AWSREGION\n
USAGE\n $ leapp session add [--providerType aws] [--accessKey <value>] [--idpArn <value>] [--idpUrl <value>]\n [--mfaDevice <value>] [--sessionName <value>] [--parentSessionId <value>] [--profileId <value>] [--region <value>]\n [--roleArn <value>] [--roleSessionName <value>] [--secretKey <value>] [--sessionType\n awsIamRoleFederated|awsIamUser|awsIamRoleChained]\n\nFLAGS\n --accessKey=<value> AWS Access Key ID of the IAM User\n --idpArn=<value> AWS IAM Federated Role IdP Arn value, obtain it from your AWS Account\n --idpUrl=<value> the idp url address we want to create\n --mfaDevice=<value> MFA Device Arn retrieved from your AWS Account\n --parentSessionId=<value> For AWS IAM Role Chained is the session Id of the session that will assume the chained\n role. Retrieve it using $leapp session list -x\n --profileId=<value> an AWS named profile ID in Leapp\n --providerType=<option> Identify the provider for your sessions. Valid types are [aws]\n <options: aws>\n --region=<value> Session Region for AWS sessions in Leapp\n --roleArn=<value> AWS IAM Federated Role Arn value, obtain it from your AWS Account\n --roleSessionName=<value> Optional Alias for the Assumed Role Session name\n --secretKey=<value> AWS Secret Access Key of the IAM User\n --sessionName=<value> Session Alias to identify the session in Leapp\n --sessionType=<option> Identify the AWS session type. Valid types are [awsIamRoleFederated, awsIamUser,\n awsIamRoleChained]\n <options: awsIamRoleFederated|awsIamUser|awsIamRoleChained>\n\nDESCRIPTION\n Add a new session\n\nEXAMPLES\n $leapp session add\n\n $leapp session add --providerType [aws] --sessionType [awsIamRoleFederated, awsIamRoleChained, awsIamUser] --region [AWSREGION] --sessionName NAME ...[combination of flags relative to the session]\n\n $leapp session add --providerType aws --sessionType awsIamRoleFederated --sessionName NAME --region AWSREGION --idpArn IDPARN --idpUrl IDPURL --profileId PROFILEID --roleArn ROLEARN\n\n $leapp session add --providerType aws --sessionType awsIamRoleChained --sessionName NAME --region AWSREGION --profileId PROFILEID --roleArn ROLEARN --parentSessionId ID (--roleSessionName ROLESESSIONNAME)\n\n $leapp session add --providerType aws --sessionType awsIamUser --sessionName NAME --region AWSREGION --profileId PROFILEID --accessKey ACCESSKEY --secretKey SECRETKEY (--mfaDevice MFADEVICEARN)\n
USAGE\n $ leapp session change-profile [--sessionId <value>] [--profileId <value>]\n\nFLAGS\n --profileId=<value> an AWS named profile ID in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Change a session named-profile\n\nEXAMPLES\n $leapp session change-profile\n\n $leapp session change-profile --profileId PROFILEID --sessionId SESSIONID\n
USAGE\n $ leapp session change-region [--sessionId <value>] [--region <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Change a session region\n\nEXAMPLES\n $leapp session change-region\n\n $leapp session change-region --sessionId SESSIONID --region REGION\n
Provides info about the current active session for a selected profile (if no profile is provided, it uses the profile default)
USAGE\n $ leapp session current [-i] [-p <value>] [-r aws|azure] [-f <value>]\n\nFLAGS\n -f, --format=<value> allows formatting data to show\n - aws -> id alias, accountNumber, roleArn\n - azure -> id tenantId, subscriptionId\n -i, --inline\n -p, --profile=<value> [default: default] aws named profile of which gets info\n -r, --provider=<option> filters sessions by the cloud provider service\n <options: aws|azure>\n\nDESCRIPTION\n Provides info about the current active session for a selected profile (if no profile is provided, it uses the profile\n default)\n\nEXAMPLES\n $leapp session current --format \"alias accountNumber\" --inline --provider aws\n
USAGE\n $ leapp session delete [--sessionId <value>] [-f]\n\nFLAGS\n -f, --force force a command without asking for confirmation (-f, --force)\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Delete a session\n\nEXAMPLES\n $leapp session delete\n\n $leapp session delete --sessionId SESSIONID\n\n $leapp session delete --sessionId SESSIONID [--force, -f]\n
Generate STS temporary credentials for the given AWS session id
USAGE\n $ leapp session generate SESSIONID\n\nARGUMENTS\n SESSIONID id of the session\n\nDESCRIPTION\n Generate STS temporary credentials for the given AWS session id\n\nEXAMPLES\n $leapp session generate 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d\n
Show sessions list with all properties; filter query is case sensitive
USAGE\n $ leapp session list [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml | |\n [--csv | --no-truncate]] [--no-header | ]\n\nFLAGS\n -x, --extended show extra columns\n --columns=<value> only show provided columns (comma-separated)\n --csv output is csv format [alias: --output=csv]\n --filter=<value> filter property by partial string matching, ex: name=foo\n --no-header hide table header from output\n --no-truncate do not truncate output to fit screen\n --output=<option> output in a more machine friendly format\n <options: csv|json|yaml>\n --sort=<value> property to sort by (prepend '-' for descending)\n\nDESCRIPTION\n Show sessions list with all properties; filter query is case sensitive\n\nEXAMPLES\n $leapp session list\n\n $leapp session list --filter=\"ID=Foo\" -x\n\n $leapp session list --filter=\"Session Name=Foo\"\n\n $leapp session list --filter=\"Type=Foo\"\n\n $leapp session list --filter=\"Named Profile=Foo\"\n\n $leapp session list --filter=\"Region/Location=Foo\"\n\n $leapp session list --filter=\"Status=Foo\"\n
USAGE\n $ leapp session open-web-console [--sessionId <value>] [-p]\n\nFLAGS\n -p, --print Print an AWS Web Console login URL in the terminal instead of opening the web browser\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Open an AWS Web Console\n\nEXAMPLES\n $leapp session open-web-console\n\n $leapp session open-web-console --sessionId SESSIONID [--print, -p]\n
USAGE\n $ leapp session run-aws-credential-plugin [--sessionId <value>] [--pluginName <value>]\n\nFLAGS\n --pluginName=<value> Unique name of a Leapp Plugin\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n\nDESCRIPTION\n Run a Leapp Plugin\n\nEXAMPLES\n $leapp session run-plugin\n\n $leapp session run-plugin --sessionName SESSIONAME --pluginName PLUGINNAME\n
USAGE\n $ leapp session start [SESSIONNAME] [--sessionId <value>] [--sessionRole <value>] [--noInteractive]\n\nARGUMENTS\n SESSIONNAME Name of the Leapp session\n\nFLAGS\n --noInteractive If the specified session is not unique or doesn't exist, throw an error without starting the\n interactive session selection mode\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --sessionRole=<value> Session Role of one or more sessions in Leapp\n\nDESCRIPTION\n Start a session\n\nEXAMPLES\n $leapp session start\n\n $leapp session start SESSIONNAME\n\n $leapp session start SESSIONNAME --sessionRole SESSIONROLE\n\n $leapp session start SESSIONNAME --noInteractive\n\n $leapp session start --sessionId SESSIONID\n
USAGE\n $ leapp session start-ssm-session [--sessionId <value>] [--region <value>] [--ssmInstanceId <value>]\n\nFLAGS\n --region=<value> Session Region for AWS sessions in Leapp\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --ssmInstanceId=<value> Instance ID for EC2 instance we want to access with SSM\n\nDESCRIPTION\n Start an AWS SSM session\n\nEXAMPLES\n $leapp session start-ssm-session\n\n $leapp session start-ssm-session --sessionId SESSIONID --region AWSREGION --ssmInstanceId EC2INSTANCEID\n
USAGE\n $ leapp session stop [SESSIONNAME] [--sessionId <value>] [--sessionRole <value>] [--noInteractive]\n\nARGUMENTS\n SESSIONNAME Name of the Leapp session\n\nFLAGS\n --noInteractive If the specified session is not unique or doesn't exist, throw an error without starting the\n interactive session selection mode\n --sessionId=<value> Session Id to identify the session in Leapp, recover it with $leapp session list -x\n --sessionRole=<value> Session Role of one or more sessions in Leapp\n\nDESCRIPTION\n Stop a session\n\nEXAMPLES\n $leapp session stop\n\n $leapp session stop SESSIONNAME\n\n $leapp session stop SESSIONNAME --sessionRole SESSIONROLE\n\n $leapp session stop SESSIONNAME --noInteractive\n\n $leapp session stop --sessionId SESSIONID\n
USAGE\n $ leapp set-workspace [WORKSPACENAME]\n\nARGUMENTS\n WORKSPACENAME name of the Leapp Team remote workspace or local\n\nDESCRIPTION\n Set the current Leapp workspace\n\nEXAMPLES\n $leapp team set-workspace\n\n $leapp team set-workspace local\n\n $leapp team set-workspace WORKSPACE-NAME\n
USAGE\n $ leapp workspace\n\nDESCRIPTION\n Show the current workspace\n\nEXAMPLES\n $leapp workspace\n
See code: dist/commands/workspace.ts
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/","title":"Configure an AWS Identity Center (ex AWS Single Sign-On) integration","text":""},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#what-is-aws-identity-center-ex-aws-single-sign-on","title":"What is AWS Identity Center (ex AWS Single Sign-On)","text":"
AWS Identity Center (ex AWS Single Sign-On) is a cloud service that allows you to grant your users access to AWS resources across multiple AWS accounts.
AWS SSO provides a directory that you can use to create users, organize them in groups, and set permissions across those groups; alternatively, you can obtain them from your Microsoft Active Directory or any standards-based identity provider, such as Okta Universal Directory or Azure AD.
After logging in the first time, Leapp will map all your roles and users into Sessions.
Info
To get started using AWS SSO refer to this guide.
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#how-to-configure-an-aws-identity-center-ex-aws-single-sign-on-integration-in-leapp","title":"How to configure an AWS Identity Center (ex AWS Single Sign-On) integration in Leapp","text":"
Click on the Add Integration button in the sidebar.
Select AWS Single Sign-On as the Integration type.
Provide the required information (described in the next section).
Click on the Add integration button.
"},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#required-information","title":"Required information","text":"Field Description INTEGRATION TYPE Set as AWS Single Sign-on AWS SSO URL The portal URL to begin the authentication flow. It usually follows this pattern: d-xxxxxxxxxx.awsapps.com/start. REGION The region on which AWS SSO is administered and configured. This is NOT where your generated credentials will be valid; it's only used for the login part."},{"location":"configuring-integration/configure-aws-single-sign-on-integration/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-integration/configure-azure-integration/","title":"Configure an Azure integration","text":""},{"location":"configuring-integration/configure-azure-integration/#what-is-an-azure-integration","title":"What is an Azure integration","text":"
Our Leapp integration refers to Azure Tenant which is a dedicated and trusted instance of Azure AD.
The tenant is automatically created when your organization signs up for a Microsoft cloud service subscription.
These subscriptions include Microsoft Azure, Microsoft Intune, or Microsoft 365.
An Azure tenant represents a single organization and can have multiple subscriptions.
Please refer to How to find your Azure Active Directory tenant ID and other Azure AD documentation for more information.
Warning
For azure-cli users with version < 2.30.0: Leapp no longer supports this version of the CLI. Please update to a newer version.
To create a new Azure Integration, go to the left sidebar of Leapp Desktop and click on the icon. A new modal will be presented with the following option to compile. After submitting the new Integration and have logged into your Azure Portal, Subscriptions will be automatically retrieved and mapped into Leapp Azure Sessions.
"},{"location":"configuring-integration/configure-azure-integration/#how-to-configure-an-azure-integration-in-leapp","title":"How to configure an Azure integration in Leapp","text":"
Click on the Add Integration button in the sidebar.
Select Azure as the Integration type.
Provide the required information (described in the next section).
Click on the Add integration button.
"},{"location":"configuring-integration/configure-azure-integration/#required-information","title":"Required information","text":"Field Description INTEGRATION TYPE Set as Azure ALIAS Your friendly integration name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. TENANT ID A tenant ID identifies a tenant. You can have multiple clients on a given tenant database. LOCATION The Azure datacenters are located around the world in strategic places that best meet the customer demands. These areas are known as Azure locations. Specific services requires the user to select a specific location. The value is retrieved from your default location in general options."},{"location":"configuring-integration/configure-azure-integration/#video-tutorial","title":"Video tutorial","text":"
Info
Azure sessions are not available anymore for direct creation. Instead you can create a new Azure Integration.
"},{"location":"configuring-session/configure-aws-iam-role-chained/","title":"Configure AWS IAM Role Chained","text":""},{"location":"configuring-session/configure-aws-iam-role-chained/#what-is-an-aws-iam-role-chained-session","title":"What is an AWS IAM Role Chained session","text":"
An AWS IAM Role Chained session represents an AWS role chaining access. Role chaining is the process of assuming a role starting from another IAM role or user.
An IAM role has some similarities to an IAM user. Roles and users are both AWS identities with permissions policies that determine what the identity can and cannot do in AWS. However, instead of being uniquely associated with one person, a role is intended to be assumable by anyone who needs it.
A role does not have standard long-term credentials such as a password or access keys associated with it. Instead, when you assume a role, it provides you with temporary security credentials for your role session.
Role chaining occurs when you use a role to assume a second role through the AWS CLI or API, even in other accounts.
Info
Refer to this guide to delegate access across AWS accounts using IAM Roles chaining.
"},{"location":"configuring-session/configure-aws-iam-role-chained/#how-to-configure-an-aws-iam-role-chained-in-leapp","title":"How to configure an AWS IAM Role Chained in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM Role Chained as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-role-chained/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. ROLE ARN Your IAM Role unique ID. The active Session will refer to this Role. ROLE SESSION NAME Your session name. You can query and search this on AWS Cloudtrail or any other linked audit service to find out what action were performed by the linked Identity. ASSUMER SESSION Your session from which this Role will be assumed. The assume-role call will be automatically made by Leapp."},{"location":"configuring-session/configure-aws-iam-role-chained/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-aws-iam-role-federated/","title":"Configure AWS IAM Role Federated","text":""},{"location":"configuring-session/configure-aws-iam-role-federated/#what-is-an-aws-iam-role-federated-session","title":"What is an AWS IAM Role Federated session","text":"
An AWS IAM Role Federated session represents an access type that relies on a federation between an AWS account and an external Identity Provider.
AWS Identity and Access Management (IAM) supports identity federation for delegated access to the AWS Management Console or AWS APIs. With identity federation, external identities are granted secure access to resources in your AWS accounts through IAM roles.
These external identities can come from your corporate identity provider (such as Microsoft Active Directory or from the AWS Directory Service) or from a web identity provider (such as Amazon Cognito, Login with Amazon, Facebook, Google, or any OpenID Connect-compatible provider).
We currently only support SAML 2.0 federation.
Info
Refer to this guide to provision your own federated roles.
Refer to this guide to configure and trust your SAML 2.0 Identity Provider.
Is your SAML 2.0 Identity Provider not included in the above list? Please, refer to the FAQ to add a new one.
"},{"location":"configuring-session/configure-aws-iam-role-federated/#how-to-configure-an-aws-iam-role-federated-in-leapp","title":"How to configure an AWS IAM Role Federated in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM Role Federated as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-role-federated/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. SAML 2.0 URL Your SAML URL interface to start the authentication flow and log into your Identity provider. AWS IDENTIY PROVIDER ARN Your Identity Provider ID in AWS. You can find it in IAM section Identity Providers. ROLE ARN Your IAM Role unique ID. The active Session will refer to this Role."},{"location":"configuring-session/configure-aws-iam-role-federated/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-aws-iam-user/","title":"Configure AWS IAM User","text":""},{"location":"configuring-session/configure-aws-iam-user/#what-is-an-aws-iam-user-session","title":"What is an AWS IAM User session","text":"
An AWS Identity and Access Management (IAM) user is an entity that you create in AWS to represent the person or application that uses it to interact with AWS.
An IAM User in AWS consists of a name and a set of long-term credentials. Leapp never sets these values in the configuration files, and automatically generates and refreshes a set of short-term credentials.
Info
If you want to know how Leapp generates and refresh short-term credentials refer to the credentials generation section in the documentation.
"},{"location":"configuring-session/configure-aws-iam-user/#how-to-configure-an-aws-iam-user-in-leapp","title":"How to configure an AWS IAM User in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select Amazon AWS as the Cloud Provider.
Select AWS IAM User as the access method.
Provide the required information (described in the next section).
Click on the Create Session button.
"},{"location":"configuring-session/configure-aws-iam-user/#required-information","title":"Required information","text":"Field Description SESSION ALIAS Your friendly session name in Leapp. Give it a meaningful name so it will be easier to find inside Leapp. NAMED PROFILE Your friendly session name in the AWS credential file. You will be able to reference it from the AWS CLI with --name. REGION Your default region of choice. Select the one which you use the most for this Session. MFA DEVICE Your MFA device ID to set up multi-factor authentication. ACCESS KEY ID Your long-term Access Key. It will be used to generate a short-term set of credentials. Don't disclose it to anyone. SECRET ACCESS KEY Your long-term Secret Key. It will be used to generate a short-term set of credentials. Don't disclose it to anyone. Add AWS IAM User Screen"},{"location":"configuring-session/configure-aws-iam-user/#video-tutorial","title":"Video tutorial","text":""},{"location":"configuring-session/configure-localstack/","title":"Configure LocalStack","text":""},{"location":"configuring-session/configure-localstack/#what-is-a-localstack-session","title":"What is a LocalStack session","text":"
With LocalStack you can emulate AWS cloud services with a fully functional cloud stack on your local machine. Develop and test your cloud applications with the full cloud experience, but without the hassle of the remote cloud.
You can use Leapp to create a LocalStack session that can then be used to set your local credential file and access your LocalStack resources.
Info
You need to install LocalStack in order to use the AWS cloud emulation features
"},{"location":"configuring-session/configure-localstack/#how-to-configure-a-localstack-session-in-leapp","title":"How to configure a LocalStack session in Leapp","text":"
From the top bar, click on the plus icon to add a new session.
Select LocalStack as the Cloud Provider.
Provide a name for the session.
Click on the Create Session button.
Warning
LocalStack sessions work only with AWS Credential Method configured with the credential-file-method option. The option is available in the Options menu > General > Generics > AWS Credential Method.
Warning
In order to use the credential file to access LocalStack from your AWS CLI, you must update the AWS CLI to the latest version.
Contributions and questions are not just welcome, they\u2019re essential! Please open issues with ideas on how to improve Leapp, including feedback, critiques, and information about how you\u2019re using it. Discussion is at the heart of the project and your thoughts and ideas will help make it better for everyone, thank you.
Read our contribution guide to learn more.
You can chat with us in our community, so join us, or feel free to contact us via the website!
Join our Community
"},{"location":"installation/install-leapp/","title":"Install Leapp","text":""},{"location":"installation/install-leapp/#install-leapp-app","title":"Install Leapp App","text":""},{"location":"installation/install-leapp/#macos-windows-and-linux","title":"MacOS, Windows, and Linux","text":"
You can install Leapp by downloading the pre-built binaries for your OS on the website release page:
Download Leapp \u21e9
Unzip the package and double-click the executable to install.
You can install Leapp CLI through a Homebrew Formula:
brew install Noovolari/brew/leapp-cli\n
In Linux it may happen that the command leapp is not recognized. In that case we suggest to run the following command:
brew link leapp-cli\n
"},{"location":"installation/install-leapp/#install-leapp-cli-on-macos-with-arm64-chip-m1-m2","title":"Install Leapp CLI on macOS with ARM64 chip (M1, M2)","text":"
On macOS with ARM64 chip you can use the Homebrew Formula:
All the available commands are listed in the Leapp CLI section of the documentation.
Warning
Leapp CLI will work only if the Desktop App is installed and running.
"},{"location":"installation/requirements/","title":"Requirements","text":""},{"location":"installation/requirements/#requirements","title":"Requirements","text":""},{"location":"installation/requirements/#macos-and-windows","title":"MacOS and Windows","text":"
There are no requirements for macOS and Windows users.
Leapp uses libsecret and gnome-keyring as dependencies to store all sensitive data into the keyring. Depending on your distribution, you may need to install them using these commands before running Leapp.
"},{"location":"installation/requirements/#logging-into-ec2-instances-via-aws-ssm-with-leapp","title":"Logging into EC2 Instances via AWS SSM with Leapp","text":"
In order to use AWS SSM on your System through Leapp, you must be able to execute this command on your own at least once, when the correct credentials are active.
Leapp checks if a new version is available every 10 minutes (starting from the application launch). If so, a dialog message will pop up and show a version number, the release date and the changelog
In this modal, a user can do the following:
Remind me laterDownload updateClick on X
Leapp will close the modal and notify the user that a new update is available by adding a notification dot to the Dock Bar icon. Users will not be bothered anymore until the next release is available. This option is convenient for users that want to stick to a specific version. Note that you can do this for every version and maintain the one you prefer.
Leapp will open the Release URL in your default browser to let the User manually download the release for their specific OS and install it.
Leapp will close the modal and another one will appear in 10 minutes.
"},{"location":"installation/update-leapp/#macos-homebrew-linux-linuxbrew-and-windows-via-wsl","title":"macOS (Homebrew), Linux (Linuxbrew) and Windows (via WSL)","text":"
Leapp can also be updated via Homebrew Cask with: brew upgrade leapp
Depending on which method you used to install the CLI (npm or Homebrew on macOS), you can update it with the following commands:
npmHomebrew (macOS)
npm update -g @noovolari/leapp-cli\n
brew upgrade Noovolari/brew/leapp-cli\n
"},{"location":"leapp-pro/security-and-password/","title":"Security and password","text":""},{"location":"leapp-pro/security-and-password/#password-issues","title":"Password issues","text":""},{"location":"leapp-pro/security-and-password/#can-i-recover-my-password","title":"Can I recover my password?","text":"
Unfortunately, it is not possible to recover the master password. The master password is very important as it's the key point of our zero-knowledge encryption mechanism. If you forget it, you'll lose access to the previously encrypted Leapp Sessions and Integrations. That's why it is crucial that you keep your password safe; we suggest you to store it in a password manager like 1Password.
"},{"location":"leapp-pro/security-and-password/#how-is-my-data-encrypted","title":"How is my data encrypted?","text":"
All information associated with your stored data is protected with end-to-end encryption. Leapp Sessions and Integrations are encrypted before being forwarded to the backend. Specifically, Leapp Pro uses AES 256-bit encryption as well as PBKDF-SHA512 to secure your data.
AES is a standard in cryptography and is used by the U.S. government and other government agencies around the world for protecting top-secret data. With proper implementation and a strong encryption key (your Master Password), AES is considered unbreakable.
PBKDF-SHA512 is used to derive the encryption key from your master password. Then this key is salted and hashed for authenticating with the Leapp Pro backend. The default iteration count used with PBKDF2 is 500,000 iterations on the client. Each Secret has its own generated symmetric key; this symmetric key is encrypted using the user\u2019s public RSA key (this is also the foundation of the Secret sharing system). This encryption and decryption are done entirely on the Leapp Pro clients because your master password is never stored on or transmitted to Leapp Team backend.
It is important to highlight the fact that the backend does not act as a credentials broker, i.e. it has no visibility on the long-term/short-term credentials used by Leapp Pro Desktop App/CLI to access the cloud providers. In addition, the secrets retrieved from the backend, are an encrypted version of access configurations; access configurations DO NOT include temporary credentials. There is a single edge case: the IAM User. Indeed, the IAM User Session access configuration contains IAM User\u2019s access keys, which are long-term credentials. Still, the Leapp Pro backend has no visibility on these long-term credentials, as they\u2019re encrypted by the client before being forwarded to the Leapp Team backend.
When you unlock Leapp Pro, using a longer and more secure account password is easier than you might otherwise have chosen.
"},{"location":"leapp-pro/security-and-password/#your-fingerprint-is-not-stored-in-leapp","title":"Your fingerprint is not stored in Leapp.","text":"
Leapp never scans or stores your fingerprint. Touch ID is provided by macOS, which only tells Leapp Pro if your fingerprint was recognized or not.
Learn more about Touch ID's advanced security technology.
"},{"location":"leapp-pro/synchronization/","title":"Synchronization","text":""},{"location":"leapp-pro/synchronization/#whats-a-pro-workspace","title":"What's a Pro Workspace","text":"
A Pro Workspace is a new Workspace that is created upon first login with your registered Pro User. This workspace is synchronized with your Cloud account every time you create, edit, or delete an integration or a session; this way it is possible to use Leapp Pro on different devices, maintaining all your saved integrations and sessions.
"},{"location":"leapp-pro/synchronization/#how-the-synchronization-works","title":"How the Synchronization works","text":"
Synchronization works by encrypting all your sessions and integrations with your master password, created during your sign-up process. This way we maintain a 0-knowlegde approach on your data through all the lifecycle of your Pro workspace.
The encrypted data is then saved in the Cloud on your Leapp Pro personal space.
You, as a Leapp Pro user, can always keep an eye on the status of synchronization using the synchronization widget in the bottom-left area of Leapp.
Synchronization widget - synchronization active and done
When all the data is correctly synchronized you'll see the image above.
When Leapp Pro is synchronizing you'll see the icon and text changing to the one in the image below.
Synchronization widget - synchronization in progress
If you eventually lose connection or have a problem in synchronizing your data the widget will turn yellow as shown below.
Synchronization widget - synchronization failed
You have the possibility to manually trigger another synchronization process and see if the problem is resolved.
Info
When Leapp Pro is restarted it will try to synchronize your data in the Cloud if you're logged in, so you can also close Leapp safely even if in synch failed state.
"},{"location":"leapp-pro/synchronization/#do-you-have-any-trouble-with-synchronization","title":"Do you have any trouble with Synchronization","text":"
In case of any troubles locking Leapp Pro workspace please contact us.
Leapp Pro enable Users to protect their Cloud access with Username and password.
With Leapp Pro you can back up and synchronize your Leapp workspace and access to any device you want without losing your access configurations.
"},{"location":"leapp-pro/getting-started/#getting-started-guide","title":"Getting started guide","text":"
Sign up to Leapp Pro
Sign in to Leapp Pro
Lock your Leapp Pro Workspace
"},{"location":"leapp-pro/getting-started/#security-and-syncronization","title":"Security and syncronization","text":"
Once you updgrade your Plan to Leapp Pro, your local Workspace will be moved to the Pro Workspace. All the data inside your workspace are secured with end-to-end encryption through your Master password.
"},{"location":"leapp-pro/getting-started/lock/","title":"Lock your Workspace","text":"
Leapp Pro allows the user to temporary lock the workspace, making it accessible only by typing again your master-password. This feature provides a further security level on top of the standard Leapp Community edition.
"},{"location":"leapp-pro/getting-started/lock/#how-to-lock-the-leapp-pro-workspace","title":"How to lock the Leapp Pro workspace","text":"
To lock your Leapp Pro workspace you should click on the Workspace button located in the top-left area and select the Lock option.
Workspace button Lock option
The Leapp Pro lock screen should appear, prompting for your master-password.
Leapp Pro lock screen"},{"location":"leapp-pro/getting-started/lock/#touch-id","title":"Touch ID","text":"
You can also use your fingerprint to unlock Leapp if your PC is Touch ID compatible. After Logging to your Pro workspace for the first time, Leapp will associate your workspace with your system Touch ID. After that the option will be available and can also be tweaked in the general tab of the option menu.
"},{"location":"leapp-pro/getting-started/lock/#troubles-in-locking-your-workspace","title":"Troubles in locking your Workspace","text":"
In case of any troubles locking Leapp Pro workspace please contact us.
With Leapp Pro you can always sign-in from any location, gaining instant access to your personal workspace.
"},{"location":"leapp-pro/getting-started/sign-in/#sign-in-to-leapp-pro","title":"Sign-in to Leapp Pro","text":"
After upgrading Leapp Community edition, you can sign-in at any time, just clicking on the Workspace button located in the top-left area and selecting the Sign-in Workspace option.
Workspace button Sign-in Workspace option
The Sign-in Workspace dialog will appear. Enter your Email address, master-password and click on the Add Workspace button.
Sign-in dialog
If the information entered is correct, your Leapp Pro workspace will be displayed and you can immediately use it to manage your cloud credentials.
Leapp Pro Workspace
To avoid unwanted access, you can lock your Leapp Pro workspace at any time.
"},{"location":"leapp-pro/getting-started/sign-in/#troubles-in-signing-in-to-leapp-pro","title":"Troubles in signing in to Leapp Pro?","text":"
In case of any troubles signing in to Leapp Pro please contact us.
A Leapp Pro upgrade is required to enable new workspace features like Cloud access from multiple locations and Workspace locking.
"},{"location":"leapp-pro/getting-started/sign-up/#sign-up-to-leapp-pro","title":"Sign-up to Leapp Pro","text":"
To sign up for Leapp Pro you should upgrade your version of Leapp Community edition. Click on the Options button in the top-right area.
Settings button
In the Options dialog, select the Plans tab and click on Upgrade to Pro button.
Plans tab
The upgrade window should appear. Enter your email (it will be the email address associated with your Leapp Pro account) and click on the Upgrade now button.
Upgrade window
At this point a window will appear, so you can specify a payment method to complete the Leapp Pro upgrade. After the payment process you will receive a confirmation email containing the Complete the registration link.
Upgrade email
Clicking the link in the confirmation email will open a web page that will allow you to enter your personal info and the master-password, essential to provide the security requirements of Leapp Pro.
Sign-up page
After entering your personal info and the master-password click the Continue button. You can now finally sign in to Leapp Pro.
"},{"location":"leapp-pro/getting-started/sign-up/#troubles-in-signing-up-to-leapp-pro","title":"Troubles in signing up to Leapp Pro?","text":"
In case of any troubles signing up to Leapp Pro please contact us.
"},{"location":"leapp-pro/getting-started/sign-up/#how-to-sign-in","title":"How to Sign-in","text":"
Take a look to this page to sign-in your Leapp Pro workspace.
argument type description message string the message to show level LogLevel severity of the message display boolean shows the message in a toast in the desktop app when true. Otherwise, log it in the log files"},{"location":"plugins/plugins-development/#fetch","title":"fetch","text":"
fetch(url: string): any
Retrieve the content of a URL. Returns a promise for the URL
argument type description url string a valid HTTP URL to fetch from"},{"location":"plugins/plugins-development/#openexternalurl","title":"openExternalUrl","text":"
openExternalUrl(url: string): void
Open an external URL in the default browser
argument type description url string a valid HTTP URL to open in the default browser"},{"location":"plugins/plugins-development/#createsession","title":"createSession","text":"
Creates a new Leapp Session based on given SessionData
argument type description createSessionData SessionData the metadata used to create the Leapp Session"},{"location":"plugins/plugins-development/#clonesession","title":"cloneSession","text":"
cloneSession(session: Session): Promise<string>
This method allows you to clone the given Leapp Session. This operation is allowed for the following Leapp Session types:
AwsIamUserSession
AwsIamRoleFederatedSession
AwsIamRoleChainedSession
argument type description session Session the Leapp Session that I want to clone"},{"location":"plugins/plugins-development/#updatesession","title":"updateSession","text":"
This method allows you to update the given session with the given updateSessionData. This operation is allowed for the following Leapp Session types:
AwsIamUserSession
AwsIamRoleFederatedSession
AwsIamRoleChainedSession
argument type description updateSessionData SessionData the metadata used to update the given Leapp Session session Session the Leapp Session that I want to update"},{"location":"plugins/plugins-development/#openterminal","title":"openTerminal","text":"
Execute the given command in the platform-specific terminal; optionally, it is possible to set an env key/value object containing the env variables to export in the terminal, before the command execution.
The terminal window base path is set to the home directory.
argument type description command string the command that I want to execute in the platform-specific terminal env any optional key/value env variables object"},{"location":"plugins/plugins-development/#getprofileidbyname","title":"getProfileIdByName","text":"
getProfileIdByName(profileName: string): string
Returns the id of a named profile from its name if it exists, otherwise creates a new profile and returns its id.
Can be used when creating/editing a session since SessionData requires the id of a named profile
argument type description profileName string a valid named profile"},{"location":"plugins/plugins-development/#getidpurlidbyurl","title":"getIdpUrlIdByUrl","text":"
getIdpUrlIdByUrl(url: string): string
Return the ID of the IdpUrl object from the given URL if it exists, otherwise creates a new IdP URL and returns its ID.
Can be used when creating/editing Federated Sessions since SessionData requires the ID of an IdP URL.
argument type description url string the URL associated with the IdpUrl I want to retrieve"},{"location":"plugins/plugins-development/#example-display-a-toast-message-in-leapp","title":"Example: display a toast message in Leapp","text":"
Return a valid FontAwesome 5 code. Override default value in package.json
"},{"location":"plugins/plugins-development/#example-display-a-session-based-message-in-leapp","title":"Example: display a session-based message in Leapp","text":"
async applySessionAction(session: Session, credentials: any): Promise<void> {\nif(session.type === Session.awsIamUser) {\nthis.pluginEnvironment.log(`This is an IAM User session: ${session.sessionName}`, LogLevel.info, true); }\nelse {\nthis.pluginEnvironment.log(`This is NOT an IAM User session: ${session.sessionName}`, LogLevel.info, true);\n}\n}\n
"},{"location":"plugins/plugins-development/#packagejson-metadata","title":"package.json metadata","text":"property values description constraints name a custom string the name of the plugin the same used in the plugin folder author a custom string the name of the author none version a custom string the version of the plugin must be a semver string description a custom string the description of the plugin none keywords a string array the name of the plugin must contain at least \"leapp-plugin\" leappPlugin an object the plugin custom configuration must contain at least \"supportedOS\" and \"supportedSessions\" leappPlugin.supportedOS a string array [\"mac\", \"windows\", \"linux\"] if not specified, all OSs will be considered compatible leappPlugin.supportedSessions a string array [\"anyType, \"aws\", \"azure\", \"awsIamRoleFederated\", \"awsIamRoleChained\", \"awsSsoRole\", \"awsIamUser\"] at least one of these values must be specified leappPlugin.icon a custom string fontAwesome code for an icon (e.g. \"fa fa-globe\") must be a valid FontAwesome 5 code"},{"location":"plugins/plugins-development/#plugin-examples","title":"Plugin Examples","text":""},{"location":"plugins/plugins-development/#open-web-console","title":"Open Web Console","text":"
import { Session } from \"@noovolari/leapp-core/models/session\";\nimport { AwsCredentialsPlugin } from \"@noovolari/leapp-core/plugin-sdk/aws-credentials-plugin\";\nimport { PluginLogLevel } from \"@noovolari/leapp-core/plugin-sdk/plugin-log-level\";\n\nexport class WebConsolePlugin extends AwsCredentialsPlugin {\nget actionName(): string {\nreturn \"Open web console\";\n}\n\nget actionIcon(): string {\nreturn \"fa fa-globe\";\n}\n\nasync applySessionAction(session: Session, credentials: any): Promise<void> {\nthis.pluginEnvironment.log(\"Opening web console for session: \" + session.sessionName, PluginLogLevel.info, true);\n\nconst sessionRegion = session.region;\nconst sessionDuration = 3200;\nconst isUSGovCloud = sessionRegion.startsWith(\"us-gov-\");\nlet federationUrl;\nlet consoleHomeURL;\n\nif (!isUSGovCloud) {\nfederationUrl = \"https://signin.aws.amazon.com/federation\";\nconsoleHomeURL = `https://${sessionRegion}.console.aws.amazon.com/console/home?region=${sessionRegion}`;\n} else {\nfederationUrl = \"https://signin.amazonaws-us-gov.com/federation\";\nconsoleHomeURL = `https://console.amazonaws-us-gov.com/console/home?region=${sessionRegion}`;\n}\n\nif (sessionRegion.startsWith(\"cn-\")) {\nthrow new Error(\"Unsupported Region\");\n}\n\nthis.pluginEnvironment.log(\"Starting opening Web Console\", PluginLogLevel.info, true);\n\nconst sessionStringJSON = {\nsessionId: credentials.sessionToken.aws_access_key_id,\nsessionKey: credentials.sessionToken.aws_secret_access_key,\nsessionToken: credentials.sessionToken.aws_session_token,\n};\n\nconst queryParametersSigninToken = `?Action=getSigninToken&SessionDuration=${sessionDuration}&Session=${encodeURIComponent(\nJSON.stringify(sessionStringJSON)\n)}`;\n\nconst res = await this.pluginEnvironment.fetch(`${federationUrl}${queryParametersSigninToken}`);\nconst response = await res.json();\n\nconst loginURL = `${federationUrl}?Action=login&Issuer=Leapp&Destination=${consoleHomeURL}&SigninToken=${(response as any).SigninToken}`;\nthis.pluginEnvironment.openExternalUrl(loginURL);\n}\n}\n
"},{"location":"plugins/plugins-introduction/","title":"Introduction to Plugins","text":"
This section provides an overview of Leapp\u2019s plugins, which can be used to extend the functionality of Leapp.
Plugins are commonly used when more advanced and custom behavior is needed, for example using Leapp-generated temporary credentials to run custom actions.
You can create your own plugins or import custom ones created by the community. You can also publish your plugins on npm to make them available to everyone easily.
"},{"location":"plugins/plugins-introduction/#add-a-plugin","title":"Add a Plugin","text":"
To add a plugin you can use one of the following methods:
"},{"location":"plugins/plugins-introduction/#add-from-npm","title":"Add from npm","text":"
From the Leapp option menu, go to the Plugins tab. Insert the name of the npm package for the plugin and click on the plus icon to add it to your plugins
Go to Options by clicking the top right gear icon then click the Plugins tab. Click the Folder Icon. This will open the plugin folder inside .Leapp.
Here, manually create a folder with the same name as your plugin package.json name property and move your package.json and bundled plugin.js files inside this folder.
Alternatively, you can simply move your entire plugin folder cloned from the example template.
Lastly, from the Leapp Plugins tab in the Option menu, click on the refresh icon to reload all plugins.
Warning
Adding plugins is at your own risk! We cannot currently guarantee that a plugin is safe, so BE CAREFUL when you install something from an unknown source. A plugin verification system is under development and will be available later this year.
"},{"location":"plugins/plugins-introduction/#disable-a-plugin","title":"Disable a Plugin","text":"
To disable a Leapp plugin, go to Options by clicking the top right gear icon then click the Plugins tab.
Toggle Enabled for the plugin you want to disable.
"},{"location":"plugins/plugins-introduction/#remove-a-plugin","title":"Remove a Plugin","text":"
To remove a Leapp plugin, go to Options by clicking the top right gear icon then click the Plugins tab.
Click the Folder Icon. This will open the plugin folder inside .Leapp. From here, locate the folder containing the plugin you want to remove and simply delete the folder.
"},{"location":"plugins/plugins-introduction/#run-a-plugin","title":"Run a Plugin","text":"
You can run a plugin both from Leapp Desktop App and Leapp CLI.
From Leapp Desktop App, right click on a session to open the contextual menu, click on Plugins, and select the plugin you want to run
Info
This contextual menu option is not available if you have no plugins that you can run on the selected session and/or your operating system.
From Leapp CLI, you can use the command leapp session run-plugin. For more information on how to use this CLI command, see the documentation.
Click on the top right gear icon to go to the Leapp option menu and then select the tab Plugin.
From there, you can see a list of currently installed plugins, check whether a plugin is compatible with your system or not, which session types it supports and disable/enable it if you need.
"},{"location":"plugins/plugins-introduction/#create-your-plugin","title":"Create your Plugin","text":"
You can start creating a plugin from the template.
Leapp plugins are written in TypeScript. They must contain at least a class that extends a base class provided by the Plugin SDK.
There's currently only one of these classes, AwsCredentialsPlugin , that can be used to create a plugin that generates temporary credentials.
Every Leapp plugin must at least have a package.json file and a plugin.js file.
leapp-plugin/ \n \u251c\u2500\u2500 package.json # Plugin metadata\n \u2514\u2500\u2500 plugin.js # A webpack bundle for the main logic\n
Create your Plugin
"},{"location":"security/credential-process/","title":"Credential Process","text":""},{"location":"security/credential-process/#what-is-credential-process","title":"What is Credential Process?","text":"
Credential Process is a configuration option (in the AWS config file) that instruct the AWS CLI and SDKs to use an external command to generate valid credentials in a specific format.
It is a way to generate AWS compatible credentials on the fly, only when requested by tools that respect the AWS credential chain.
Credential Process is perfect if you have a way to generate or look up credentials that isn't directly supported by the AWS CLI or third-party tools; for example, you can configure the AWS CLI to use it by configuring the credential_process setting in the config file.
The difference between Credential Process and Standard Credential file is that credentials in the \"credential file\" are written in plain text and so, they are potentially unsecure, even if temporary. Credential Process instead, generates credentials that are consumed only when they are effectively needed.
No credential is written in any file. They are printed on the stdout and consumed upon request.
"},{"location":"security/credential-process/#how-credential-process-works","title":"How Credential Process works?","text":"
Credential Process asks an external process to generate an AWS compatible temporary credential set in this format:
{\n\"Version\": 1,\n\"AccessKeyId\": \"an AWS access key\",\n\"SecretAccessKey\": \"your AWS secret access key\",\n\"SessionToken\": \"the AWS session token for temporary credentials\", \"Expiration\": \"ISO8601 timestamp when the credentials expire\"\n}
The Expiration field allows the generated credentials to be cached and reused until they are no more valid (by default the value is 3600s=1h).
Ensures that no credential set is written on your machine in neither the ~/.aws/credentials or ~/.aws/config files.
Ensures your long-running tasks always have valid credentials during their lifecycle.
Is compatible with named-profiles.
Is a way to make third-party tool compatible with AWS SSO and SAML Federated IAM Principals even if they don't support them natively.
As stated by this article by Ben Kehoe, Credential Process is a good way to avoid cluttering the credential file with temporary credentials.
Warning
Temporary credentials in the credentials file reduce potential blast radius in case of machine exploit but they require to be refreshed every time they expire.
"},{"location":"security/credential-process/#how-leapp-works-with-credential-process","title":"How Leapp works with Credential Process","text":"
Info
Requirements: this credentials generation method requires that both Leapp desktop app and CLI are installed.
1) Open your Leapp desktop app and go to the settings panel ().
2) In the general section change the AWS Credential Generation from \"credential-file-method\" to \"credential-process-method\".
3) An informative panel will show up telling that you need the CLI installed (see below), click on \"I acknowledge it\"
warning modal
4) Now, everytime you click on start () an entry will be created in the ~/.aws/config file with the following format:
5) You can start more than one session, depending on how many named-profile you've created; for every session started with a unique named-profile, a new entry will be created in the config file.
Info
AWS CLI, SDks, and third-party tools that can read credentials from the config file can reach AWS services with this method.
Leapp is built with a security-first approach. Every piece of information that has to be persisted is encrypted and saved on your workstation.
We devised two main methods to store data, based on its sensitiveness.
Data Persistence and encryption Examples Operational All information used to make Leapp work, not strictly tied to direct access to cloud environments. Stored and encrypted in a configuration file within the user workspace. Named profiles, proxy configurations, etc. Sensitive Information that can be used, or potentially exploited, to gain access to cloud environments. Stored in the System Vault, leveraging its own integrated encryption. Static credentials, access tokens, cached data, etc."},{"location":"security/intro/#end-to-end-encryption","title":"End-to-end Encryption","text":"
We leverage Zero-Knowledge to provide end-to-end encryption on tiers that require to save your data outside of your workstation to deliver specific features.
Zero Knowledge is designed so that no one, except you, can access your secured data.
Warning
We CAN'T access your data under any circumstances, even if you ask us to!
Information that can be used, or potentially exploited, to gain access to cloud environments are stored your workstation's System Vault, leveraging its own integrated encryption. The user can access the secrets stored in the System Vault at any time, using their user password.
Leapp uses Keytar as an interface to the secure vault on macOS, Windows and Linux systems.
Every key is stored in the vault under the name Leapp. In the description, you will find the underlying name used by Leapp to retrieve the secret.
"},{"location":"security/system-vault/#supported-system-vaults","title":"Supported System Vaults","text":"OS System Vault MacOS Keychain Windows Credential Vault Linux API/Libsecret
Info
We're currently supporting only System Vaults installed by default on the OS. We're planning on extending support to other vaults and online password managers (LastPass, BitWarden, 1Password, etc.). If you'd like other services to be supported feel free to open an Issue or make a Pull Request (check our contributing guidelines).
To persist your configuration online, we implemented Zero-Knowledge encryption to prevent access to your information. But how can you trust a company to keep all of your secrets secret? The answer lies in end-to-end encryption, which lays the groundwork for applications with Zero-Knowledge architectures.
Zero-knowledge refers to policies and architecture that eliminate the possibility for secret managers themselves to access your password.
Warning
This is implemented to save your configuration online in the PRO and TEAM versions of Leapp. Don't know yet about the PRO and TEAM versions? Check our roadmap.
Info
This same process is leveraged by Bitwarden to store their password.
"},{"location":"security/zero-knowledge/#users-have-key-control","title":"Users have key control","text":"
When users have complete control of the encryption key, they control access to the data, providing encrypted information to Leapp without Leapp having access to or knowledge of that data.
Info
To know more about this, you can find the whitepaper on which we based our implementation of Zero-Knowledge end-to-end encryption.
During any phase of the registration and login process the client does not provide any password-related info to the server.
The server does not store any information that can be used to guess the password in a convenient way. In other words, the system must not be prone to brute force or dictionary attacks.
Any sensible data is encrypted client-side, the server will work with encrypted blocks only.
All the implementation is released as open-source.
Temporary security credentials created by AssumeRoleWithSAMLResponse last for one hour. However, you can use the optional DurationSeconds parameter to specify the duration of your session.
Your role session lasts for the specified duration, or until the time specified in the SAML authentication response's SessionNotOnOrAfter value, whichever is shorter. You can provide a DurationSeconds value from 900 seconds (15 minutes) up to the maximum session duration setting for the role. This setting can have a value from 1 hour to 12 hours.
Leapp sets the token duration to 1 hour.
Info
\u26a0\ufe0f In this case, generated credentials are not \"cached\" in the keychain.
The GetSessionToken operation must be called by using the long-term AWS security credentials of the AWS IAM user. Credentials that are created by IAM users are valid for the duration that you specify. This duration can range from 900 seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours), with a default of 43,200 seconds (12 hours). Credentials based on account credentials can range from 900 seconds (15 minutes) up to 3,600 seconds (1 hour), with a default of 1 hour.
Leapp sets the token duration to 10 hours.
Info
These are the only temporary credentials that are stored in the System vault and not rotated, unless expired.
The access token is valid for 8 hours as noted in the expiresAt timestamp in the JSON file. Expired tokens must be re-authenticated using the get-role-credentials API call.
Azure generates a set of access and refresh tokens that are put inside the msal_token_cache.json file inside the .azure directory. Following is the procedure used to generate a set of credentials.
Info
In Windows OS the msal_token_cache is persisted on an encrypted file with dpapi API. Starting from release 2.30 of Azure CLI, credentials are no more persisted in the original accessToken.json
Azure Users profile info is saved in the azureProfile.json file inside the .azure directory.
Before accessing Azure sessions, you now have to create an Azure integration. After that, these are the steps required to log in and then retrieve Azure sessions.
msal_token_cache and azureProfile.json files are cleaned for security reasons.
We execute az login --tenantId <TENANTID>. We do this to obtain the updated user profile and the refresh token (associated to this integration).
We extract all the Azure subscriptions associated with the integration and for each one we map a Leapp Azure session.
We extract the refresh token, account, and profile information from msal_token_cache and azureProfile.json and persist them in the System's vault.
We also remove the previous information from the original files, to increase security and avoid external tampering.
In the current version of Leapp we can only start one Azure session at a time.
For each subscription retrieved upon login to a specific integration, we define a new Leapp Azure Session. To start an Azure session we follow these steps.
Recover refresh token, account, and profile information from the Vault and we use them alongside sessionId (Subscription id) in the start operation.
azureProfile.json is only filled with profile information from the current subscription.
We write the account information and the refresh token back in the msal_token_cache
We execute az account get-access-token --subscriptionId <SUBSCRIPTIONID>, to retrieve the access token and the id token of the subscription.
The previous command also writes access and id token back to the msal_token_cache file.
We update the expiration time of the session to the current datetime.
We update the refresh token in the Vault with the new information.
We remove the refresh token from the msal_token_cache.
We finally start the session.
Info
The refresh token is a long term credential that potentially lasts for 90 days. The access token is a short term credential and lasts for 70 minutes. Source
Please always add logs to any issue you want to fill whenever possible, so you can help the team identify the problem quickly
"},{"location":"troubleshooting/faq/","title":"FAQ","text":""},{"location":"troubleshooting/faq/#im-using-the-open-source-app-do-you-store-my-data-online","title":"I'm using the open-source app, do you store my data online?","text":"
NO.
The open-source software doesn't transfer, persist, or share anything with other services. All your data is secured and encrypted on your workstation.
Nobody can access it, not even ourselves.
"},{"location":"troubleshooting/faq/#ive-got-a-paid-tier-how-do-you-manage-my-data-can-you-access-it","title":"I've got a paid tier, how do you manage my data? Can you access it?","text":"
We can't and don't want to see any of your access data.
We need to store your data online to enable some features (syncing, managing other users, etc.) but we implement a Zero-Knowledge encryption system that prevents even ourselves to access your data.
"},{"location":"troubleshooting/faq/#i-dont-feel-secure-using-a-built-in-window-for-authentication-cant-you-use-the-default-browser","title":"I don't feel secure using a built-in window for authentication, can't you use the default browser?","text":"
In the future, Leapp will only use the default browser to authenticate. Right now, this is a compromise to deliver the authentication flow. We already ported the AWS SSO authentication flow on the default browser, and we're working on migrating the other ones as soon as possible.
"},{"location":"troubleshooting/faq/#how-can-i-find-leapp-data-in-the-system-vault","title":"How can I find Leapp data in the System Vault?","text":"
Every key stored by Leapp in the vault is named Leapp. The account name shows the description of the element saved by our software.
"},{"location":"troubleshooting/faq/#where-do-i-find-the-leapp-logs","title":"Where do I find the Leapp logs?","text":"
Head to the Application data section.
"},{"location":"troubleshooting/faq/#ssm-terminal-is-opening-but-no-session-is-starting-what-can-i-do","title":"SSM terminal is opening but no session is starting, what can I do?","text":"
Just close the terminal and relaunch the SSM command.
"},{"location":"troubleshooting/faq/#aws-cli-or-az-cli-is-installed-but-leapp-cant-find-it-what-can-i-do","title":"AWS CLI (or AZ CLI) is installed but Leapp can't find it, what can I do?","text":"
Leapp on macOS works in sandbox mode, so some terminal commands must be symlinked in order to work on some installations. Just make a symlink pointing from /usr/local/bin/aws to the actual aws binary or, for AZ CLI, from /usr/local/bin/az to the actual az binary. To create symlinks on macOS, use this command ln -s /any/file/on/the/disk linked-file. The command is called ln. If used with the option -s it will create a symbolic link in the current directory.
"},{"location":"troubleshooting/faq/#i-use-leapp-session-current-but-want-to-see-the-alias-and-not-the-id","title":"I use leapp session current but want to see the alias and not the id.","text":""},{"location":"troubleshooting/faq/#setting-up-leappalias-command","title":"Setting up leappalias command","text":"
Follow these steps to set up the leappalias command in your Zsh shell:
Create a script file named leappalias.sh using a text editor:
Save the file and make it executable by running the following command in the terminal:
chmod +x leappalias.sh\n
Move the script to a directory in your system's PATH. For example, /usr/local/bin/:
sudo mv leappalias.sh /usr/local/bin/leappalias\n
Open your zshrc file using a text editor:
nano ~/.zshrc\n
Define an alias for executing the script by adding the following line to the zshrc file:
alias leappalias='/usr/local/bin/leappalias'\n
Save the changes and close the zshrc file.
Reload the zshrc file in the terminal using the following command:
source ~/.zshrc\n
Once you have completed these steps, you can use the leappalias command in your terminal to extract and display the alias from the output of leapp session current. Credit goes to bspansinQdo.
"},{"location":"troubleshooting/faq/#how-can-i-add-support-to-a-new-saml-20-identity-provider","title":"How can I add support to a new SAML 2.0 Identity Provider?","text":"
To add support to a new SAML 2.0 Identity Provider, you have to perform the following steps:
create a Fork of the Noovolari/leapp GitHub repository;
create a Pull Request and set up your local environment following Install dependencies and build packages section of the DEVELOPMENT.md;
add the Identity Provider-specific authentication URL RegEx filter to the Leapp Core authenticationUrlRegexes Map;
follow the last part of the Install dependencies and build packages section of the DEVELOPMENT.md to build the solution for both the CLI and the Desktop App;
push your changes to your forked repository and propose to merge them to the main repository.
If you need more details about the implementation, please check the How to add a new SAML IdP preset authentication URL section of the DEVELOPMENT.md.
"},{"location":"usefull-scripts/export-profile/","title":"AWS Profile Selector: Simplifying AWS Profile Selection with the Leapp CLI","text":""},{"location":"usefull-scripts/export-profile/#aws-profile-selector-simplifying-aws-profile-selection-with-the-leapp-cli","title":"AWS Profile Selector: Simplifying AWS Profile Selection with the Leapp CLI","text":"
This script enhances the AWS profile selection process by utilizing the Leapp CLI. It provides a streamlined way to switch between AWS profiles in the command line environment, allowing for easy management of multiple AWS configurations.
To use the script, it's important to note that you need to have Leapp installed and running. Leapp is a command-line tool for managing AWS profiles and sessions. Before executing the script, ensure that Leapp is installed on your system and at least one AWS session is active.
Leapp keeps track of your AWS sessions and allows you to switch between different profiles seamlessly. It's a valuable tool for managing multiple AWS accounts and simplifying your workflow. Once Leapp is installed and running, the script utilizes its functionality to retrieve the list of active sessions and display them for selection.
By integrating 'fzf' with Leapp, the script provides an interactive and convenient way to choose the desired AWS profile. With a few keystrokes, you can quickly switch between AWS profiles without manually setting the environment variables each time.
Remember to save the script in your shell configuration file (.bashrc or .zshrc) and restart your terminal or reload the configuration file for the changes to take effect.
In summary, this script simplifies the process of selecting and exporting an AWS profile, making it easier to switch between different AWS configurations when using the command line.
"}]}
\ No newline at end of file
diff --git a/latest/sitemap.xml.gz b/latest/sitemap.xml.gz
index 2ff339ca2..b604fef9f 100644
Binary files a/latest/sitemap.xml.gz and b/latest/sitemap.xml.gz differ
diff --git a/latest/usefull-scripts/export-profile/index.html b/latest/usefull-scripts/export-profile/index.html
new file mode 100644
index 000000000..b8fd8d51c
--- /dev/null
+++ b/latest/usefull-scripts/export-profile/index.html
@@ -0,0 +1,14 @@
+ AWS Profile Selector: Simplifying AWS Profile Selection with the Leapp CLI - Leapp - Docs
AWS Profile Selector: Simplifying AWS Profile Selection with the Leapp CLI
This script enhances the AWS profile selection process by utilizing the Leapp CLI. It provides a streamlined way to switch between AWS profiles in the command line environment, allowing for easy management of multiple AWS configurations.
To use the script, it's important to note that you need to have Leapp installed and running. Leapp is a command-line tool for managing AWS profiles and sessions. Before executing the script, ensure that Leapp is installed on your system and at least one AWS session is active.
Leapp keeps track of your AWS sessions and allows you to switch between different profiles seamlessly. It's a valuable tool for managing multiple AWS accounts and simplifying your workflow. Once Leapp is installed and running, the script utilizes its functionality to retrieve the list of active sessions and display them for selection.
By integrating 'fzf' with Leapp, the script provides an interactive and convenient way to choose the desired AWS profile. With a few keystrokes, you can quickly switch between AWS profiles without manually setting the environment variables each time.
Remember to save the script in your shell configuration file (.bashrc or .zshrc) and restart your terminal or reload the configuration file for the changes to take effect.
In summary, this script simplifies the process of selecting and exporting an AWS profile, making it easier to switch between different AWS configurations when using the command line.