From 6e104404ed6dce5e0d4d4b8aa3ce28b1b194019a Mon Sep 17 00:00:00 2001 From: meyerjrr Date: Tue, 24 Sep 2024 14:14:41 +1000 Subject: [PATCH 1/4] make configuration docs more discoverable and add browser template docs --- granted/configuration.mdx | 255 --------------------- granted/configuration/autocomplete.mdx | 69 ++++++ granted/configuration/browsers.mdx | 97 ++++++++ granted/configuration/cache.mdx | 37 +++ granted/configuration/errors.mdx | 11 + granted/configuration/misc.mdx | 25 ++ granted/configuration/profile-ordering.mdx | 23 ++ granted/configuration/quiet-mode.mdx | 13 ++ granted/configuration/settings.mdx | 33 +++ granted/getting-started.mdx | 4 +- mint.json | 14 +- 11 files changed, 323 insertions(+), 258 deletions(-) delete mode 100644 granted/configuration.mdx create mode 100644 granted/configuration/autocomplete.mdx create mode 100644 granted/configuration/browsers.mdx create mode 100644 granted/configuration/cache.mdx create mode 100644 granted/configuration/errors.mdx create mode 100644 granted/configuration/misc.mdx create mode 100644 granted/configuration/profile-ordering.mdx create mode 100644 granted/configuration/quiet-mode.mdx create mode 100644 granted/configuration/settings.mdx diff --git a/granted/configuration.mdx b/granted/configuration.mdx deleted file mode 100644 index 96dc137..0000000 --- a/granted/configuration.mdx +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: "Configuration" ---- - -## Granted Configuration Folder - -The configuration settings for Granted are stored within the `$HOME/.granted` folder on Unix systems, and `%USERPROFILE%/.granted` on Windows. This designated folder serves as a repository for configuration data, encompassing: - -- **Default Browser Configuration**: The `DefaultBrowser` option allows you to [establish the default browser](#changing-the-web-browser). - -- **Custom Browser Paths**: The `CustomBrowserPath` option lets you override default installation paths for browsers with custom locations. - -- **Custom Single Sign-On (SSO) Browser Paths**: The `CustomSSOBrowserPath` option provides the ability to [set custom browser](#custom-browser-for-running-sso-flows) for running Single Sign-On (SSO) flows. - -- **Profile Ordering**: The `Ordering` option allows you to change the [order of profiles](#changing-the-profile-ordering) when they are displayed. - -- **Export Credential Suffix**: The `ExportCredentialSuffix` option enables appending a suffix when exporting credentials. - -- **Access Request URL**: The `AccessRequestURL` option lets you set a Glide URL that can be used to request access. - -- **CommonFate SSO Default Start URL and Region**: The `CommonFateDefaultSSOStartURL` and `CommonFateDefaultSSORegion` options respectively set the default start URL and region for CommonFate Single Sign-On. - -- **Usage Tips and Credential Caching**: The `DisableUsageTips` option, when set to true, suppresses usage tips. The `DisableCredentialProcessCache` option, when set to true, prevents credential caching via credential processes. - -- **Export All Environment Variables**: The `DefaultExportAllEnvVar=true` configuration exports all environment variables by default when the `credential_process` is used. - -- **Export Credentials To AWS**: The `ExportCredsToAWS=true` configuration will enable credentials to be exported to `~/.aws/credentials` by default. - -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. - -- Use the `-unset` flag to remove any exported environment variables that Granted has provisioned - eg. - -``` -assume -unset -``` - -- Use the `uninstall` command to reset the granted configuration to a factory default - -``` -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 - -Specify the location of your AWS configuration file and credentials file through environment variables. Set the `$AWS_CONFIG_FILE` and `$AWS_SHARED_CREDENTIALS_FILE` environment variables to configure these file locations according to your preferences. diff --git a/granted/configuration/autocomplete.mdx b/granted/configuration/autocomplete.mdx new file mode 100644 index 0000000..28869d7 --- /dev/null +++ b/granted/configuration/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, 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/configuration/browsers.mdx b/granted/configuration/browsers.mdx new file mode 100644 index 0000000..89d56b4 --- /dev/null +++ b/granted/configuration/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/configuration/cache.mdx b/granted/configuration/cache.mdx new file mode 100644 index 0000000..b12f7df --- /dev/null +++ b/granted/configuration/cache.mdx @@ -0,0 +1,37 @@ +--- +title: "Cache" +--- + +## 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/configuration/errors.mdx b/granted/configuration/errors.mdx new file mode 100644 index 0000000..68833ad --- /dev/null +++ b/granted/configuration/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/configuration/misc.mdx b/granted/configuration/misc.mdx new file mode 100644 index 0000000..45f5daf --- /dev/null +++ b/granted/configuration/misc.mdx @@ -0,0 +1,25 @@ +--- +title: "Miscellaneous" +--- + +## Granted Configuration Editing + +Granted gives you tools to be able to interact with the config that is set under the hood. + +- Use the `-unset` flag to remove any exported environment variables that Granted has provisioned + eg. + +``` +assume -unset +``` + +- Use the `uninstall` command to reset the granted configuration to a factory default + +``` +granted uninstall +``` + + +## Customize AWS Configuration and Credentials File Locations + +Specify the location of your AWS configuration file and credentials file through environment variables. Set the `$AWS_CONFIG_FILE` and `$AWS_SHARED_CREDENTIALS_FILE` environment variables to configure these file locations according to your preferences. diff --git a/granted/configuration/profile-ordering.mdx b/granted/configuration/profile-ordering.mdx new file mode 100644 index 0000000..87bf531 --- /dev/null +++ b/granted/configuration/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/configuration/quiet-mode.mdx b/granted/configuration/quiet-mode.mdx new file mode 100644 index 0000000..252fbe5 --- /dev/null +++ b/granted/configuration/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/configuration/settings.mdx b/granted/configuration/settings.mdx new file mode 100644 index 0000000..a4db63d --- /dev/null +++ b/granted/configuration/settings.mdx @@ -0,0 +1,33 @@ +--- +title: "Configuration Settings" +--- + +## Granted Configuration Folder + +The configuration settings for Granted are stored within the `$HOME/.granted` folder on Unix systems, and `%USERPROFILE%/.granted` on Windows. This designated folder serves as a repository for configuration data, encompassing: + +- **Default Browser Configuration**: The `DefaultBrowser` option allows you to [establish the default browser](#changing-the-web-browser). + +- **Custom Browser Paths**: The `CustomBrowserPath` option lets you override default installation paths for browsers with custom locations. + +- **Custom Single Sign-On (SSO) Browser Paths**: The `CustomSSOBrowserPath` option provides the ability to [set custom browser](#custom-browser-for-running-sso-flows) for running Single Sign-On (SSO) flows. + +- **Profile Ordering**: The `Ordering` option allows you to change the [order of profiles](#changing-the-profile-ordering) when they are displayed. + +- **Export Credential Suffix**: The `ExportCredentialSuffix` option enables appending a suffix when exporting credentials. + +- **Access Request URL**: The `AccessRequestURL` option lets you set a Glide URL that can be used to request access. + +- **CommonFate SSO Default Start URL and Region**: The `CommonFateDefaultSSOStartURL` and `CommonFateDefaultSSORegion` options respectively set the default start URL and region for CommonFate Single Sign-On. + +- **Usage Tips and Credential Caching**: The `DisableUsageTips` option, when set to true, suppresses usage tips. The `DisableCredentialProcessCache` option, when set to true, prevents credential caching via credential processes. + +- **Export All Environment Variables**: The `DefaultExportAllEnvVar=true` configuration exports all environment variables by default when the `credential_process` is used. + +- **Export Credentials To AWS**: The `ExportCredsToAWS=true` configuration will enable credentials to be exported to `~/.aws/credentials` by default. + +To configure any of these options, you can use the following command: + +``` +granted settings set +``` 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/mint.json b/mint.json index abb9fbf..5460771 100644 --- a/mint.json +++ b/mint.json @@ -77,7 +77,19 @@ "granted/usage/profile-registry" ] }, - "granted/configuration", + { + "group": "Configuration", + "pages": [ + "granted/configuration/settings", + "granted/configuration/browsers", + "granted/configuration/cache", + "granted/configuration/autocomplete", + "granted/configuration/errors", + "granted/configuration/profile-ordering", + "granted/configuration/quiet-mode", + "granted/configuration/misc" + ] + }, { "group": "Recipes", "pages": [ From 9904898f84ce22a280dfb9b0935f03c4fef7f536 Mon Sep 17 00:00:00 2001 From: meyerjrr <33018450+meyerjrr@users.noreply.github.com> Date: Tue, 24 Sep 2024 15:55:01 +1000 Subject: [PATCH 2/4] Update granted/configuration/autocomplete.mdx Co-authored-by: Calvin <70191007+ckluy31@users.noreply.github.com> --- granted/configuration/autocomplete.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/granted/configuration/autocomplete.mdx b/granted/configuration/autocomplete.mdx index 28869d7..2903696 100644 --- a/granted/configuration/autocomplete.mdx +++ b/granted/configuration/autocomplete.mdx @@ -10,7 +10,7 @@ Granted has support for shell auto complete. We currently support zsh and 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. +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. ``` From 382d33af8cc6805780326f0b145f4ff65132d060 Mon Sep 17 00:00:00 2001 From: meyerjrr Date: Wed, 25 Sep 2024 17:07:30 +1000 Subject: [PATCH 3/4] move usage docs all under usage folder + add back configuration page --- .../settings.mdx => configuration.mdx} | 24 ++++- granted/configuration/cache.mdx | 37 -------- granted/configuration/misc.mdx | 25 ------ .../{recipes => usage}/access-requests.mdx | 0 .../{configuration => usage}/autocomplete.mdx | 0 .../automatically_reassume.mdx | 0 granted/{configuration => usage}/browsers.mdx | 0 granted/{recipes => usage}/cache-commands.mdx | 34 ++++++++ .../{recipes => usage}/credential-process.mdx | 0 .../{recipes => usage}/disable-usage-tips.mdx | 0 granted/{recipes => usage}/eks.mdx | 0 granted/{configuration => usage}/errors.mdx | 0 .../inline-role-assumption.mdx | 0 granted/{recipes => usage}/pass.mdx | 0 .../profile-ordering.mdx | 0 .../{configuration => usage}/quiet-mode.mdx | 0 granted/{recipes => usage}/ubuntu-keyring.mdx | 0 granted/{recipes => usage}/wsl-vscode.mdx | 0 mint.json | 87 ++++++++++++------- 19 files changed, 115 insertions(+), 92 deletions(-) rename granted/{configuration/settings.mdx => configuration.mdx} (73%) delete mode 100644 granted/configuration/cache.mdx delete mode 100644 granted/configuration/misc.mdx rename granted/{recipes => usage}/access-requests.mdx (100%) rename granted/{configuration => usage}/autocomplete.mdx (100%) rename granted/{recipes => usage}/automatically_reassume.mdx (100%) rename granted/{configuration => usage}/browsers.mdx (100%) rename granted/{recipes => usage}/cache-commands.mdx (64%) rename granted/{recipes => usage}/credential-process.mdx (100%) rename granted/{recipes => usage}/disable-usage-tips.mdx (100%) rename granted/{recipes => usage}/eks.mdx (100%) rename granted/{configuration => usage}/errors.mdx (100%) rename granted/{recipes => usage}/inline-role-assumption.mdx (100%) rename granted/{recipes => usage}/pass.mdx (100%) rename granted/{configuration => usage}/profile-ordering.mdx (100%) rename granted/{configuration => usage}/quiet-mode.mdx (100%) rename granted/{recipes => usage}/ubuntu-keyring.mdx (100%) rename granted/{recipes => usage}/wsl-vscode.mdx (100%) diff --git a/granted/configuration/settings.mdx b/granted/configuration.mdx similarity index 73% rename from granted/configuration/settings.mdx rename to granted/configuration.mdx index a4db63d..8999c97 100644 --- a/granted/configuration/settings.mdx +++ b/granted/configuration.mdx @@ -1,5 +1,5 @@ --- -title: "Configuration Settings" +title: "Configuration" --- ## Granted Configuration Folder @@ -31,3 +31,25 @@ To configure any of these options, you can use the following command: ``` granted settings set ``` + +## Granted Configuration Editing + +Granted gives you tools to be able to interact with the config that is set under the hood. + +- Use the `-unset` flag to remove any exported environment variables that Granted has provisioned + eg. + +``` +assume -unset +``` + +- Use the `uninstall` command to reset the granted configuration to a factory default + +``` +granted uninstall +``` + + +## Customize AWS Configuration and Credentials File Locations + +Specify the location of your AWS configuration file and credentials file through environment variables. Set the `$AWS_CONFIG_FILE` and `$AWS_SHARED_CREDENTIALS_FILE` environment variables to configure these file locations according to your preferences. diff --git a/granted/configuration/cache.mdx b/granted/configuration/cache.mdx deleted file mode 100644 index b12f7df..0000000 --- a/granted/configuration/cache.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "Cache" ---- - -## 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/configuration/misc.mdx b/granted/configuration/misc.mdx deleted file mode 100644 index 45f5daf..0000000 --- a/granted/configuration/misc.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Miscellaneous" ---- - -## Granted Configuration Editing - -Granted gives you tools to be able to interact with the config that is set under the hood. - -- Use the `-unset` flag to remove any exported environment variables that Granted has provisioned - eg. - -``` -assume -unset -``` - -- Use the `uninstall` command to reset the granted configuration to a factory default - -``` -granted uninstall -``` - - -## Customize AWS Configuration and Credentials File Locations - -Specify the location of your AWS configuration file and credentials file through environment variables. Set the `$AWS_CONFIG_FILE` and `$AWS_SHARED_CREDENTIALS_FILE` environment variables to configure these file locations according to your preferences. diff --git a/granted/recipes/access-requests.mdx b/granted/usage/access-requests.mdx similarity index 100% rename from granted/recipes/access-requests.mdx rename to granted/usage/access-requests.mdx diff --git a/granted/configuration/autocomplete.mdx b/granted/usage/autocomplete.mdx similarity index 100% rename from granted/configuration/autocomplete.mdx rename to granted/usage/autocomplete.mdx 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/configuration/browsers.mdx b/granted/usage/browsers.mdx similarity index 100% rename from granted/configuration/browsers.mdx rename to granted/usage/browsers.mdx 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/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/configuration/errors.mdx b/granted/usage/errors.mdx similarity index 100% rename from granted/configuration/errors.mdx rename to granted/usage/errors.mdx 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/configuration/profile-ordering.mdx b/granted/usage/profile-ordering.mdx similarity index 100% rename from granted/configuration/profile-ordering.mdx rename to granted/usage/profile-ordering.mdx diff --git a/granted/configuration/quiet-mode.mdx b/granted/usage/quiet-mode.mdx similarity index 100% rename from granted/configuration/quiet-mode.mdx rename to granted/usage/quiet-mode.mdx 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 5460771..c86f7e9 100644 --- a/mint.json +++ b/mint.json @@ -74,37 +74,26 @@ "granted/usage/dotenv", "granted/usage/automatic-config-generation", "granted/usage/storing-iam-credentials-securely", - "granted/usage/profile-registry" - ] - }, - { - "group": "Configuration", - "pages": [ - "granted/configuration/settings", - "granted/configuration/browsers", - "granted/configuration/cache", - "granted/configuration/autocomplete", - "granted/configuration/errors", - "granted/configuration/profile-ordering", - "granted/configuration/quiet-mode", - "granted/configuration/misc" - ] - }, - { - "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/usage/profile-registry", + "granted/usage/browsers", + "granted/usage/autocomplete", + "granted/usage/errors", + "granted/usage/profile-ordering", + "granted/usage/quiet-mode", + "granted/usage/access-requests", + "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", + "granted/faq", "granted/troubleshooting", "granted/security", @@ -207,6 +196,46 @@ { "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" } ], "analytics": { From b0bacdca5c7d3ed5f596cfbca1df57bc99078f88 Mon Sep 17 00:00:00 2001 From: meyerjrr Date: Wed, 25 Sep 2024 17:36:03 +1000 Subject: [PATCH 4/4] add cf subfolder --- .../{ => common-fate}/access-requests.mdx | 0 .../usage/common-fate/profile-generation.mdx | 47 +++++++++++++++++++ mint.json | 12 ++++- 3 files changed, 58 insertions(+), 1 deletion(-) rename granted/usage/{ => common-fate}/access-requests.mdx (100%) create mode 100644 granted/usage/common-fate/profile-generation.mdx diff --git a/granted/usage/access-requests.mdx b/granted/usage/common-fate/access-requests.mdx similarity index 100% rename from granted/usage/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/mint.json b/mint.json index c86f7e9..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", @@ -80,7 +87,6 @@ "granted/usage/errors", "granted/usage/profile-ordering", "granted/usage/quiet-mode", - "granted/usage/access-requests", "granted/usage/automatically_reassume", "granted/usage/cache-commands", "granted/usage/credential-process", @@ -236,6 +242,10 @@ { "source": "/recipes/wsl-vscode", "destination": "/usage/wsl-vscode" + }, + { + "source": "granted/usage/access-requests", + "destination": "granted/usage/common-fate/access-requests" } ], "analytics": {