diff --git a/granted/configuration.mdx b/granted/configuration.mdx index 96dc137..8999c97 100644 --- a/granted/configuration.mdx +++ b/granted/configuration.mdx @@ -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 ""` - -## 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: - - - -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. @@ -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 diff --git a/granted/getting-started.mdx b/granted/getting-started.mdx index 7e3c285..bce5224 100644 --- a/granted/getting-started.mdx +++ b/granted/getting-started.mdx @@ -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 > ## Set up your AWS profile file diff --git a/granted/usage/autocomplete.mdx b/granted/usage/autocomplete.mdx new file mode 100644 index 0000000..2903696 --- /dev/null +++ b/granted/usage/autocomplete.mdx @@ -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 +``` diff --git a/granted/recipes/automatically_reassume.mdx b/granted/usage/automatically_reassume.mdx similarity index 100% rename from granted/recipes/automatically_reassume.mdx rename to granted/usage/automatically_reassume.mdx diff --git a/granted/usage/browsers.mdx b/granted/usage/browsers.mdx new file mode 100644 index 0000000..89d56b4 --- /dev/null +++ b/granted/usage/browsers.mdx @@ -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 ""` + +## 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 + +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 + +``` +# ~/.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: + + + +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. +``` diff --git a/granted/recipes/cache-commands.mdx b/granted/usage/cache-commands.mdx similarity index 64% rename from granted/recipes/cache-commands.mdx rename to granted/usage/cache-commands.mdx index d0bcfc7..e10324f 100644 --- a/granted/recipes/cache-commands.mdx +++ b/granted/usage/cache-commands.mdx @@ -38,3 +38,37 @@ To list currently cached credentials along with their secure storage type, use: ```shell granted cache list ``` + +## 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 +``` + +- To disable cache for a command use the `--no-cache' flag + +``` +assume profile-1 --no-cache +``` diff --git a/granted/recipes/access-requests.mdx b/granted/usage/common-fate/access-requests.mdx similarity index 100% rename from granted/recipes/access-requests.mdx rename to granted/usage/common-fate/access-requests.mdx diff --git a/granted/usage/common-fate/profile-generation.mdx b/granted/usage/common-fate/profile-generation.mdx new file mode 100644 index 0000000..64f22f9 --- /dev/null +++ b/granted/usage/common-fate/profile-generation.mdx @@ -0,0 +1,47 @@ +--- +title: "Profile Generation" +--- + + +To generate profiles that you have access to in Common Fate, Granted can utilize a [HTTP Profile Registry](/usage/profile-registry). Granted's Profile Registry synchronizes these profiles to the default AWS config file located locally at `~/.aws/config`. + +# Adding a HTTP registry + +Granted version v0.26.0+ includes support for specifying a HTTP registry. This can be connected with a [Common Fate deployment](/introduction) + +Granted uses OIDC to authenticate to the HTTP registry. The `~/.cf/config` file is used to configure the OIDC provider. Here's an example configuration, using Cognito as the OIDC provider. + +```toml ~/.cf/config +current_context = "default" + +[context] + [context.default] + oidc_issuer = "https://cognito-idp.ap-southeast-2.amazonaws.com/ap-southeast-2_xzhfVdcnp" + oidc_client_id = "169vrs7th13n3rj1pvqiic3cxA" +``` + +To log in to the OIDC provider, you can run `granted auth login`. + +# Common Fate built-in Profile Registry + +Granted connects with [Common Fate](/introduction) to automatically sync available AWS profiles into your `~/.aws/config` file. + +If you have set up the Common Fate `cf` CLI skip to step 3. + +1. Create your Common Fate configuration by running `granted auth configure `. This will set the necessary config in your [cf config](/user-guide/cli/config) + +```bash +granted auth configure https://commonfate.example.com # replace this with your deployment URL +``` + +2. Next authenticate yourself with the deployment by running `granted auth login`. + +```bash +granted auth login +``` + +3. Add the profile registry: + +```bash +granted registry add --name common-fate --type http --url https://commonfate.example.com # replace this with your deployment URL +``` diff --git a/granted/recipes/credential-process.mdx b/granted/usage/credential-process.mdx similarity index 100% rename from granted/recipes/credential-process.mdx rename to granted/usage/credential-process.mdx diff --git a/granted/recipes/disable-usage-tips.mdx b/granted/usage/disable-usage-tips.mdx similarity index 100% rename from granted/recipes/disable-usage-tips.mdx rename to granted/usage/disable-usage-tips.mdx diff --git a/granted/recipes/eks.mdx b/granted/usage/eks.mdx similarity index 100% rename from granted/recipes/eks.mdx rename to granted/usage/eks.mdx diff --git a/granted/usage/errors.mdx b/granted/usage/errors.mdx new file mode 100644 index 0000000..68833ad --- /dev/null +++ b/granted/usage/errors.mdx @@ -0,0 +1,11 @@ +--- +title: "Error Reporting" +--- + +## 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`. diff --git a/granted/recipes/inline-role-assumption.mdx b/granted/usage/inline-role-assumption.mdx similarity index 100% rename from granted/recipes/inline-role-assumption.mdx rename to granted/usage/inline-role-assumption.mdx diff --git a/granted/recipes/pass.mdx b/granted/usage/pass.mdx similarity index 100% rename from granted/recipes/pass.mdx rename to granted/usage/pass.mdx diff --git a/granted/usage/profile-ordering.mdx b/granted/usage/profile-ordering.mdx new file mode 100644 index 0000000..87bf531 --- /dev/null +++ b/granted/usage/profile-ordering.mdx @@ -0,0 +1,23 @@ +--- +title: "Profile Ordering" +--- + +## 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. diff --git a/granted/usage/quiet-mode.mdx b/granted/usage/quiet-mode.mdx new file mode 100644 index 0000000..252fbe5 --- /dev/null +++ b/granted/usage/quiet-mode.mdx @@ -0,0 +1,13 @@ +--- +title: "Quiet Mode" +--- + +## 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. diff --git a/granted/recipes/ubuntu-keyring.mdx b/granted/usage/ubuntu-keyring.mdx similarity index 100% rename from granted/recipes/ubuntu-keyring.mdx rename to granted/usage/ubuntu-keyring.mdx diff --git a/granted/recipes/wsl-vscode.mdx b/granted/usage/wsl-vscode.mdx similarity index 100% rename from granted/recipes/wsl-vscode.mdx rename to granted/usage/wsl-vscode.mdx diff --git a/mint.json b/mint.json index abb9fbf..01adb14 100644 --- a/mint.json +++ b/mint.json @@ -67,6 +67,13 @@ { "group": "Usage", "pages": [ + { + "group": "Common Fate", + "pages": [ + "granted/usage/common-fate/access-requests", + "granted/usage/common-fate/profile-generation" + ] + }, "granted/usage/assuming-roles", "granted/usage/console", "granted/usage/headless", @@ -74,25 +81,25 @@ "granted/usage/dotenv", "granted/usage/automatic-config-generation", "granted/usage/storing-iam-credentials-securely", - "granted/usage/profile-registry" + "granted/usage/profile-registry", + "granted/usage/browsers", + "granted/usage/autocomplete", + "granted/usage/errors", + "granted/usage/profile-ordering", + "granted/usage/quiet-mode", + "granted/usage/automatically_reassume", + "granted/usage/cache-commands", + "granted/usage/credential-process", + "granted/usage/disable-usage-tips", + "granted/usage/eks", + "granted/usage/inline-role-assumption", + "granted/usage/pass", + "granted/usage/ubuntu-keyring", + "granted/usage/wsl-vscode" ] }, "granted/configuration", - { - "group": "Recipes", - "pages": [ - "granted/recipes/access-requests", - "granted/recipes/automatically_reassume", - "granted/recipes/cache-commands", - "granted/recipes/credential-process", - "granted/recipes/disable-usage-tips", - "granted/recipes/eks", - "granted/recipes/inline-role-assumption", - "granted/recipes/pass", - "granted/recipes/ubuntu-keyring", - "granted/recipes/wsl-vscode" - ] - }, + "granted/faq", "granted/troubleshooting", "granted/security", @@ -195,6 +202,50 @@ { "source": "/setup/authz", "destination": "/authz/introduction" + }, + { + "source": "/recipes/access-requests", + "destination": "/usage/access-requests" + }, + { + "source": "/recipes/automatically_reassume", + "destination": "/usage/automatically_reassume" + }, + { + "source": "/recipes/cache-commands", + "destination": "/usage/cache-commands" + }, + { + "source": "/recipes/credential-process", + "destination": "/usage/credential-process" + }, + { + "source": "/recipes/disable-usage-tips", + "destination": "/usage/disable-usage-tips" + }, + { + "source": "/recipes/eks", + "destination": "/usage/eks" + }, + { + "source": "/recipes/inline-role-assumption", + "destination": "/usage/inline-role-assumption" + }, + { + "source": "/recipes/pass", + "destination": "/usage/pass" + }, + { + "source": "/recipes/ubuntu-keyring", + "destination": "/usage/ubuntu-keyring" + }, + { + "source": "/recipes/wsl-vscode", + "destination": "/usage/wsl-vscode" + }, + { + "source": "granted/usage/access-requests", + "destination": "granted/usage/common-fate/access-requests" } ], "analytics": {