Skip to content

Latest commit

 

History

History
102 lines (75 loc) · 7.99 KB

console.md

File metadata and controls

102 lines (75 loc) · 7.99 KB
Raw

aws-sso-util console

⚠️ This feature is in beta and is subject to change without a compatibility version bump.

aws-sso-util console provides functions for launching the AWS console in a web browser for a given account, role, and optional page within the console.

It contains three commands: launch, the main command, and launch-from-config, which takes a configuration token generated by get-config-token. These latter two commands allow for easier sharing of a given launch configuration.

Identity Center instance

Both aws-sso-util console launch and aws-sso-util console get-config-token require an Identity Center instance to be specified. This consists of a start URL and the region the Identity Center instance is in (which is separate from whatever region you might be accessing).

If you're working with a single Identity Center instance, and you've already got a profile configured for it, it should just work. You should consider setting the environment variables AWS_DEFAULT_SSO_START_URL and AWS_DEFAULT_SSO_REGION in your environment (e.g., your .bashrc or .profile), which will make it explicit.

Here are the details of of how the instance is determined:

  1. The start URL and regions are looked for in the following CLI parameters and environment variables, stopping if either are found:
    1. --sso-start-url and --sso-region
    2. AWS_DEFAULT_SSO_START_URL and AWS_DEFAULT_SSO_REGION
  2. If both the start URL and region are found, and the start URL is a full URL beginning wth http, these values are used.
  3. If not, all the profiles containing Identity Center config are loaded. All Identity Center instances found in the config are then filtered:
    • If a start URL was found in step 1 and it begins with http, it will ignore all other instances.
    • If a start URL was found in step 1 and it does not begin with http, it is treated as a regex pattern that instance start URLs must match.
    • If a region was found in step 1, instances must match this region.
  4. The resulting filtered list of instances must contain exactly one entry.

aws-sso-util console launch

This will open a URL in your browser that will log you into the specified account and role, or you can have it print the URL without opening it. You can optionally specify a console region, a page in the console to open, and a session duration. If you're not already logged in, it will pop up a browser to log you in first.

Usage

aws-sso-util console launch --sso-start-url https://example.awsapps.com/start --sso-region us-east-2 \
    --account-id 123456789012 --role-name Developer --region us-west-2 \
    --destination "/lambda/home#/functions"

By default or if the --open argument is provided, the login URL will be opened in a browser. If --print is provided, the login URL will be printed, and if --open is not explicitly set, it will not be opened in the browser.

Arguments

Required

  • --account-id/-a: The account to log in as.
  • --role-name/-r: The role to log in as.

--sso-start-url and --sso-region may be required if the Identity Center instance cannot be found; see above for details.

Optional

  • --region: The AWS region to use. Note this will use the regional console site as well. This can also be set with the AWS_CONSOLE_DEFAULT_REGION environment variable.
  • --destination: The URL path within the console to land at. This can be a full console URL but the domain may be replaced with a regional console domain. This can also be set with the AWS_CONSOLE_DEFAULT_DESTINATION environment variable.
  • --override-region-in-destination and --keep-region-in-destination: By default, if the destination path has a region specified in it, that will be kept in the destination even if --region is set to something else. Use --override-region-in-destination to replace that with the value of --region.
  • --open and --no-open: Control whether the console login URL is opened in the browser. By default, if --print is not provided, the URL will be opened.
  • --print and --no-print: Control whether the console login URL is printed to the console. If --print is provided and --open is not, the URL will not be opened.
  • --logout-first: Open a page in the browser to logout any current session first, preventing conflicts when the login page is opened. This can also be set with the AWS_CONSOLE_LOGOUT_FIRST environment set to 1 or true.
  • --duration: The session duration in minutes. When this is not set, it defaults to the duration of the credentials retrieved from Identity Center.
  • --force-refresh: Log in to Identity Center again.

Reusable launch configuration

It may be useful to reuse or share the arguments to aws-sso-util console launch. To make this easier, aws-sso-util can package up the arguments as a token, which can then be used in place of the individual arguments. Note that the config token does not contain credentials. It is purely a way to reuse and share the launch configuration; you could do the same by storing and sharing the actual command line arguments as a string, but then you run into pitfalls like quoting the role name if it's got spaces, escaping destination URLs, etc. A config token avoids this by being an opaque URL-safe base64-encoded value.

Usage

aws-sso-util console get-config-token --sso-start-url https://example.awsapps.com/start --sso-region us-east-2 \
    --account-id 123456789012 --role-name Developer \
    --destination "https://console.aws.amazon.com/lambda/home#/functions/my-function?tab=code"
eyJ2ZXJzaW9uIjogIjEiLCAic3NvX3N0YXJ0X3VybCI6ICJodHRwczovL2V4YW1wbGUuYXdzYXBwcy5jb20vc3RhcnQiLCAic3NvX3JlZ2lvbiI6ICJ1cy1lYXN0LTIiLCAiZmVkZXJhdGlvbl9lbmRwb2ludCI6ICJodHRwczovL3NpZ25pbi5hd3MuYW1hem9uLmNvbS9mZWRlcmF0aW9uIiwgImRlc3RpbmF0aW9uIjogImh0dHBzOi8vY29uc29sZS5hd3MuYW1hem9uLmNvbS9sYW1iZGEvaG9tZSMvZnVuY3Rpb25zL215LWZ1bmN0aW9uP3RhYj1jb2RlIiwgImFjY291bnRfaWQiOiAiMTIzNDU2Nzg5MDEyIiwgInJvbGVfbmFtZSI6ICJEZXZlbG9wZXIifQ==

aws-sso-util console launch-from-config --config-token eyJ2ZXJzaW9uIjogIjEiLCAic3NvX3N0YXJ0X3VybCI6ICJodHRwczovL2V4YW1wbGUuYXdzYXBwcy5jb20vc3RhcnQiLCAic3NvX3JlZ2lvbiI6ICJ1cy1lYXN0LTIiLCAiZmVkZXJhdGlvbl9lbmRwb2ludCI6ICJodHRwczovL3NpZ25pbi5hd3MuYW1hem9uLmNvbS9mZWRlcmF0aW9uIiwgImRlc3RpbmF0aW9uIjogImh0dHBzOi8vY29uc29sZS5hd3MuYW1hem9uLmNvbS9sYW1iZGEvaG9tZSMvZnVuY3Rpb25zL215LWZ1bmN0aW9uP3RhYj1jb2RlIiwgImFjY291bnRfaWQiOiAiMTIzNDU2Nzg5MDEyIiwgInJvbGVfbmFtZSI6ICJEZXZlbG9wZXIifQ==
# browser launches

Options

aws-sso-util console get-config-token

The options to aws-sso-util console get-config-token are the same as aws-sso-util console launch, except that --open, --print, and --force-refresh are not available, and the environment variables for region and destination are not used.

Additionally, --account-id and --role-name are not required; omitting either or both will cause the omitted one(s) to be required when the config token is used with aws-sso-util console launch-from-config. This allows for a single config token to be used in situations like the following:

  • Accessing resources with well-known names in different accounts.
  • Multiple people accessing an account, where not all of them can use the same role.

Note that both account and role can be overridden in the launch command even if they are provided when generating the config token.

aws-sso-util console launch-from-config

aws-sso-util console launch-from-config requires the --config-token argument. If either or both of --account-id and --role-name were not provided when generating the config token, they are required at launch (they can also be provided anyway to override what is in the token). The --open, --print, --logout-first (and AWS_CONSOLE_LOGOUT_FIRST), and --force-refresh options work as in aws-sso-util console launch.

Config token details

Config tokens are base64-encoded JSON. When this feature comes out of beta, the format of config tokens will be fixed and documented so they can be constructed without calling aws-sso-util console get-config-token.