awsconsurl 24.4.4
Creates and Opens an AWS console login URL in a Browser
Requires Python: >=3.6
Keywords: 'aws'

## AWS Console URL

Generates and launches an AWS console login URL in a new tab for the default browser.

### Installation

```
pip install awsconsurl
```
* This installs boto3 and Python requests. Consider you may prefer either a local installation or a virtual environment.

### Basic Command

In basic usage:
```bash
# consurl
```
This will use your **`default`** AWS profile (from *~/.aws/credentials*) to launch a console window in your default browser.

The **-h** or **--help** prints the command arguments summary and exits. Note that the help message includes the defaults as expressed in the current environment.  Example:
```bash
$ consurl -h
usage: consurl [-h] [-V] [-v] [-p PROFILE] [-o] [-a] [-s SHORT_ROLE_NAME]
               [-r ROLE_ARN] [-n NAME] [-d DURATION]

Open AWS Console in a Browser

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         Print version and exit.
  -v, --verbose         Verbose output [False]
  -p PROFILE, --profile PROFILE
                        Specify AWS profile [default]
  -o, --output          Only Print the URL [False]
  -a, --assume-role     Assume role first [False]
  -s SHORT_ROLE_NAME, --short-role-name SHORT_ROLE_NAME
                        Specify role name to assume [DefaultConsoleRole]
  -r ROLE_ARN, --role-arn ROLE_ARN
                        (optonal) full arn to assume [None]
  -n NAME, --name NAME  Session name for assume role [rkras-rkmbp.sunyocc.edu]
  -d DURATION, --duration DURATION
                        Specify session duration [3600 Sec]

-------------------------
```

The **-V** or **--version** prints the version information and exits.

The **-v** or **--verbose** flag prints debug output to *stderr* as the URL is created. 

The **-o** or **--output** flag outputs the created console login URL to *stdout*, and does not launch the URL in the users browser.

The **-p** or **--profile** arguments specify a configured aws profile to use with the command, [described below.](README.md#Selecting_Credentials)

The Remainder of the command arguments relate to (assuming a role and are described below.](README.md#Assuming_Roles)

### Selecting Credentials

**consurl** uses the AWS ***boto3*** library, and so includes the same basic behavior as ***awscli*** in using the AWS *`credentials`* file.

**consurl** will use the profile named in **AWS_PROFILE** environment varaible, or **AWS_ACCESS_KEY_ID** and **AWS_SECRET_ACCESS_KEY**. If no environment varailbes are set, **consurl** will used configured **default** profile. 

A specific profile can be selected with the **-p** *profilename>* or **--profile** *profilename* command arguments.  This is probably the most important switch for general use.
```bash
# consurl -p sandboxcreds  
```
The credentials profile named ***[sandboxcreds]*** will be used to launch the AWS console.

These credentials will be used to obtain a console login token and a console login URL is created and used to launch the AWS console.

### Assuming Roles

**consurl** is useful to open a console session with an assumed role. This can, with the correct **iam** permissions, launch a console in a different account than the users credentials.

If you would like to assume a role, and use that roles temporary credentials for the console, use the ***-a*** or ***--assume-role*** command switch.

**consurl** will assume the role defined in **AWS_ROLE_ARN** environment variable containing the full **ARN** (Amazon Resource Name) for the role.

To override this use either the **-r** *role-arn* or **--role-arn** *role-arn* switch to specify the role. This is the best methond for assuming cross-account roles:
```bash
# consurl --assume-role --role-arn arn:aws:iam::123456789012:role/MyFavoriteRole
```

Alternatively, you can use the **-s** *short-role-name* or **--short-role-name** *short-role-name*  switch. We define the short role name as the non-ARN name of the role.  The full ARN is generated for the AWS account of the users credentials.
```base
# consurl --assume-role -s MyFavoriteRole
```
For credentials from account 123456789012 will create the role ARN arn:aws:iam::123456789012:role/MyFavoriteRole

If **--assume-role** flag is used, but neither switches nor environment strings define a role ARN, one is created with the name **DefaultConsoleRole** in the account of the users credentials, and **consurl** attempts to assume that role.

If no **--assume-role** flag is used, but either **--role-arn** or **--short-role-name** are specified **consurl** will attempt to assume the role only if it is using **iam** credentials (*i.e.* the session isn't already running an assumed role or temporary credentials.)

For assumed roles ***session name*** is retrieved from the **AWS_ROLE_SESSION_NAME** environment variable, but this can be overriden with the **-n** *session-name>* or **--name** *session-name>* switch. If neither are specified a default is formed as ***[username]-[hostname]***
```bash
# consurl -a -s ITSRole -n "alice@example.org"
```
This results in an *assumed role user* of arn:aws:sts::123456789012:assumed-role/ITSRole/alice@example.org - which can assure a consistent principle to use in IAM policies.

The **-d** *seconds* or **--duration** *seconds* switch provide the duration in Seconds for the assumed role to be valid, with the default of 3600 seconds.  For Assumed roles the maximum is set in the IAM role.