Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add browser template docs #43

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Add browser template docs #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6e10440
make configuration docs more discoverable and add browser template docs
meyerjrr Sep 24, 2024
9904898
Update granted/configuration/autocomplete.mdx
meyerjrr Sep 24, 2024
382d33a
move usage docs all under usage folder + add back configuration page
meyerjrr Sep 25, 2024
1fc317b
Merge branch 'add-browser-template-docs' of github.com:common-fate/do…
meyerjrr Sep 25, 2024
b0bacdc
add cf subfolder
meyerjrr Sep 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 0 additions & 200 deletions granted/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,169 +32,6 @@ To configure any of these options, you can use the following command:
granted settings set
```

## Changing the profile ordering

There are settings options in Granted which allow you to change the way that profiles are listed in use. Default being by Frecency. Alternatively it can be configured to list profiles alphabetically. To set the profile ordering type just run:

```
granted settings profile-order set
```

From here you will be able to select your preferred method of choice

```
? Select filter type [Use arrows to move, type to filter]
> Frecency
Alphabetical
```

### Frecency

Granted uses a [Frecency](https://en.wikipedia.org/wiki/Frecency) algorithm to show the most frequent and recent profiles at the top of the list when running `assume`. The algorithm can be found [here](https://github.com/common-fate/granted/blob/main/pkg/frecency/frecency.go). The algorithm caches frecency data locally in the `aws_profiles_frecency` file in the Granted configuration folder.

## Autocompletion

Granted has support for shell auto complete. We currently support zsh and fish, with plans to support [bash, and powershell](https://github.com/urfave/cli/tree/master/autocomplete) in the future. Please let us know of your interest by [opening an issue on GitHub](https://github.com/common-fate/granted/issues).

### Fish

Fish autocompletions can be created by running the following command, then following the prompts.

Note, This currently only provides command and flag autocompletion, it does not automatically list aws profiles with the assume command.
Let us know if you are using Fish and would like to see this added.

```
granted completion -s fish
```

### ZSH

ZSH autocompletion can be enabled by running the following command.

```
granted completion -s zsh
```

Type `assume` and press **tab** to see a list of your aws profiles.

```
assume
profile-1 profile-2 profile-3
```

Type `assume -` and press **tab** to see flag completions.

```
assume -
--active-role --duration --export --pt --unset --version -h -v
--ar --env --granted-active-aws-role-profile --region --update-checker-api-url -c -r
--auto-configure-shell --ex --help --service --url -d -s
--console --exec --pass-through --un --verbose -e -u
```

Type `assume -s ` and press **tab** to see service names.

```
ct gd s3 sso
appsync cw grafana sagemaker states
athena ddb iam scrh stepfn
c9 dms l scrm tra
ce dx lambda secretsmanager trustedadvisor
cf eb mwaa securityhub vpc
cfn ebs param ses waf
cloudformation ec2 r53 sfn
cloudmap ecr rds sm
cloudwatch ecs redshift sns
config eks route53 ssm
```

Type `assume -r ` and press **tab** to see regions.

```
af-south-1 ap-south-1 eu-north-1 me-south-1 us-west-2
ap-east-1 ap-southeast-1 eu-south-1 sa-east-1
ap-northeast-1 ap-southeast-2 eu-west-1 us-east-1
ap-northeast-2 ca-central-1 eu-west-2 us-east-2
ap-northeast-3 eu-central-1 eu-west-3 us-west-1
```

## Changing the web browser

To see which browser Granted will use to open cloud consoles with, run `granted browser`.

To change the web browser, run the command:

```
granted browser set
```

You will get a response like this:

```
? Select your default browser [Use arrows to move, type to filter]
> Chrome
Brave
Edge
Firefox
Chromium
Safari
Firefox Developer Edition
Arc
```

Select which browser you would like to use and press Enter.

## Using specific browser profiles

Launching a specific browser profile is possible with `--browser-profile` flag for supported browsers such as Chrome, Edge, and Chromium Variants. Example usage: `assume profile-name -c --browser-profile "<your_browser_profile>"`

## Setting color and icon preferences for profiles

If you use Firefox with the [Granted Firefox Addon](https://addons.mozilla.org/en-GB/firefox/addon/granted/), you can set the color and icon preference for each profile. This is useful for distinguishing between profiles at a glance.

To customize the color and icon add `granted_color` and `granted_icon` to the profile in your `~/.aws/config` file.

This configuration:

```
granted_color = green
granted_icon = dollar
```

Will result in this:

<img height="200" src="/images/granted/granted-firefox-custom-color-icon.png" />

Valid colors are: `blue`, `turquoise`, `green`, `yellow`, `orange`, `red`, `pink` and `purple`

Valid icons are: `fingerprint`, `briefcase`, `dollar`, `cart`, `circle`, `gift`, `vacation`, `food`, `fruit`, `pet`, `tree` and `chill`

## Custom browser for running SSO flows

You can specify a custom browser path for your SSO login flows with Granted.

```
granted browser set-sso
```

You will get a response like this:

```
ℹ️ Select your SSO default browser

? Select your default browser Chrome

✅ Granted will default to using /Applications/Google Chrome.app/Contents/MacOS/Google Chrome for SSO flows.
```

## Error reporting and update checking

We currently do not collect error reports in Granted but this is something we are considering in future in order to ensure Granted works reliably on all platforms. Any error reporting telemetry, including instructions on how to opt out, will be communicated through GitHub and this documentation page.

The Granted binary will periodically check to see if new versions are available by calling https://update.api.granted.dev.

To disable update checking you can set the environment variable `GRANTED_DISABLE_UPDATE_CHECK=true`.

## Granted Configuration Editing

Granted gives you tools to be able to interact with the config that is set under the hood.
Expand All @@ -212,43 +49,6 @@ assume -unset
granted uninstall
```

## SSO Configuration

- To list all SSO tokens saved in the Granted keychain use the `sso-tokens` command

```
granted sso-tokens
```

```
granted sso-tokens list
```

- To remove a token from the local store use `sso-tokens clear`

```
granted sso-tokens clear
```

```
granted sso-tokens clear profile_name
```

- To remove all tokens from the store use the `--all` flag

```
granted sso-tokens clear --all
```

## Enable Quiet Mode

To enable quiet mode in Granted, set the `GRANTED_QUIET` environment variable to `true` by running:

```
export GRANTED_QUIET=true
```

This suppresses most of the command output, providing a quieter experience.

## Customize AWS Configuration and Credentials File Locations

Expand Down
4 changes: 2 additions & 2 deletions granted/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ If you'd prefer to watch a video tutorial, Rowan from Common Fate has recorded a
height="400"
src="https://www.youtube.com/embed/pKb9FIl-VGk"
title="YouTube video player"
frameborder="0"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
allowFullScreen
></iframe>

## Set up your AWS profile file
Expand Down
69 changes: 69 additions & 0 deletions granted/usage/autocomplete.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
title: "Autocompletion"
---

## Autocompletion

Granted has support for shell auto complete. We currently support zsh and fish, with plans to support [bash, and powershell](https://github.com/urfave/cli/tree/master/autocomplete) in the future. Please let us know of your interest by [opening an issue on GitHub](https://github.com/common-fate/granted/issues).

### Fish

Fish autocompletions can be created by running the following command, then following the prompts.

Note that this currently only provides command and flag autocompletion; it does not automatically list AWS profiles with the assume command.
Let us know if you are using Fish and would like to see this added.

```
granted completion -s fish
```

### ZSH

ZSH autocompletion can be enabled by running the following command.

```
granted completion -s zsh
```

Type `assume` and press **tab** to see a list of your aws profiles.

```
assume
profile-1 profile-2 profile-3
```

Type `assume -` and press **tab** to see flag completions.

```
assume -
--active-role --duration --export --pt --unset --version -h -v
--ar --env --granted-active-aws-role-profile --region --update-checker-api-url -c -r
--auto-configure-shell --ex --help --service --url -d -s
--console --exec --pass-through --un --verbose -e -u
```

Type `assume -s ` and press **tab** to see service names.

```
ct gd s3 sso
appsync cw grafana sagemaker states
athena ddb iam scrh stepfn
c9 dms l scrm tra
ce dx lambda secretsmanager trustedadvisor
cf eb mwaa securityhub vpc
cfn ebs param ses waf
cloudformation ec2 r53 sfn
cloudmap ecr rds sm
cloudwatch ecs redshift sns
config eks route53 ssm
```

Type `assume -r ` and press **tab** to see regions.

```
af-south-1 ap-south-1 eu-north-1 me-south-1 us-west-2
ap-east-1 ap-southeast-1 eu-south-1 sa-east-1
ap-northeast-1 ap-southeast-2 eu-west-1 us-east-1
ap-northeast-2 ca-central-1 eu-west-2 us-east-2
ap-northeast-3 eu-central-1 eu-west-3 us-west-1
```
0 granted/recipes/automatically_reassume.mdx → granted/usage/automatically_reassume.mdx
View file
Open in desktop
File renamed without changes.
97 changes: 97 additions & 0 deletions granted/usage/browsers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
---
title: "Browsers"
---

## Changing the web browser

To see which browser Granted will use to open cloud consoles with, run `granted browser`.

To change the web browser, run the command:

```
granted browser set
```

You will get a response like this:

```
? Select your default browser [Use arrows to move, type to filter]
> Chrome
Brave
Edge
Firefox
Chromium
Safari
Firefox Developer Edition
Arc
```

Select which browser you would like to use and press Enter.

## Using specific browser profiles

Launching a specific browser profile is possible with `--browser-profile` flag for supported browsers such as Chrome, Edge, and Chromium Variants. Example usage: `assume profile-name -c --browser-profile "<your_browser_profile>"`

## Setting a custom browser template
If you use browsers that we do not provide built-in support for in Granted, or wish to customise the behaviour of browser launching, there are custom templates that can be set for the console browser and for SSO authentication browser. If set these templates will be used as a first priority.

### Custom Template for Console Browser
```
# ~/.granted/config
[AWSConsoleBrowserLaunchTemplate]
Command = "/Applications/Firefox.app/Contents/MacOS/firefox --new-tab {{.URL}} --profile {{.Profile}} --some-flag {{.Args.Foo}}"
UseForkProcess = true
```

### Custom Template for SSO Authentication
Example: Opening chrome into a specified profile
<Info>
To find the name of your chrome profile. First open chrome in your profile of choice and search `chrome://version/` and you should see the profile path:

Profile Path: /Users/your-path/Library/Application Support/Google/Chrome/Profile 2
So "Profile 2" is the profile to set in the below command for --profile-directory
</Info>
```
# ~/.granted/config
[SSOBrowserLaunchTemplate]
Command = "\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\" {{ .URL }} --args \"--profile-directory=Profile 2\""
```

## Setting color and icon preferences for profiles

If you use Firefox with the [Granted Firefox Addon](https://addons.mozilla.org/en-GB/firefox/addon/granted/), you can set the color and icon preference for each profile. This is useful for distinguishing between profiles at a glance.

To customize the color and icon add `granted_color` and `granted_icon` to the profile in your `~/.aws/config` file.

This configuration:

```
granted_color = green
granted_icon = dollar
```

Will result in this:

<img height="200" src="/images/granted/granted-firefox-custom-color-icon.png" />

Valid colors are: `blue`, `turquoise`, `green`, `yellow`, `orange`, `red`, `pink` and `purple`

Valid icons are: `fingerprint`, `briefcase`, `dollar`, `cart`, `circle`, `gift`, `vacation`, `food`, `fruit`, `pet`, `tree` and `chill`

## Custom browser for running SSO flows

You can specify a custom browser path for your SSO login flows with Granted.

```
granted browser set-sso
```

You will get a response like this:

```
ℹ️ Select your SSO default browser

? Select your default browser Chrome

✅ Granted will default to using /Applications/Google Chrome.app/Contents/MacOS/Google Chrome for SSO flows.
```
Loading