Improve the doc + AWS MFA doc

LozanoMatheus · Sep 11, 2022 · 856212b · 856212b
1 parent 269be1e
commit 856212b
Showing 1 changed file with 138 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@ _Hoping these will become a native features_
 * [AWS CLI](https://aws.amazon.com/cli/)
 * [realpath](https://github.com/coreutils/coreutils)
 
-## AWS Access Keys auto-rotation
+## AWS Access Keys autorotation
 
 The AWSecure CLI can autorotate the AWS Access Keys based on the profile that the user is currently using or via cronjob.
 
@@ -41,11 +41,12 @@ For example, if you configured to only use in the user request and there are mul
 
 The AWS Access Keys auto-rotation works transparently for the users, when the user executes an AWS command (e.g. `aws lambda list-functions`), it will check if needs to rotate the AWS Access Keys for the current AWS Profile. Once the AWS Access Keys auto-rotation steps are done, it will run the command requested by the user (e.g. `aws lambda list-functions`).
 
-### How it works - cronjob
-
 This allows users to add the AWS Access Keys auto-rotation as a cronjob (e.g. on crontab), so they can disable it when running any AWS command. It's also possible to add multiple entries, one per AWS profile.
 
+This is helpful in case you have a profile that you barely use or you want to eliminate the extra ~3 seconds on each command or ~25 seconds when the keys needs to be rotated.
+
 For example:
+
 Configure the `~/.awsecure-cli` to never run the AWS Access Keys auto-rotation.
 
 ```bash
@@ -69,6 +70,12 @@ PATH=/usr/local/bin:...
 
 > Make sure you have the environment variable PATH configure and pointing to AWSecure CLI.
 
+## AWSecure CLI and AWS MFA
+
+The AWSecure CLI makes easier to use AWS MFA in the terminal, specially when you have multiple profiles and/or using other tools such as kubectl.
+
+The AWSecure CLI can automatically gets the first MFA device configured in your user, request the MFA code and then temporarily stores the session token for the time you define in the `AWSECURE_CLI_MFA_TOKEN_DURATION`. Once the MFA token duration is reached, it will automatically ask you again for the MFA code and renew the session token.
+
 ## Instalation
 
 There are two ways you can install the wrapper. You can create a symbolic link to `/usr/local/bin` (or another place of your choice) or by setting the `awsecure-cli/bin/<INTERPRETER>`.
@@ -91,7 +98,9 @@ echo 'PATH=/usr/local/bin:${PATH}' >> ~/.zshrc
 
 ## Configuring
 
-These are the configurations that you can define in your `~/.awsecure-cli`.
+These are the configurations that you can define in your `~/.awsecure-cli` or via environment variables.
+
+> The exported environment variable has high priority over the file `~/.awsecure-cli`.
 
 |                PARAMETER                |   DEFAULT   |      ACCEPTED<br> VALUES     |                                                                                                                               COMMENT                                                                                                                               |
 |:---------------------------------------:|:-----------:|:----------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
@@ -100,44 +109,98 @@ These are the configurations that you can define in your `~/.awsecure-cli`.
 | AWSECURE_CLI_LOG_TO_FILE                | false       | true<br>false                | This will send the logs to a file `/tmp/awsecure-cli.log.<Ymd>` (e.g. `/tmp/awsecure-cli.log.20220215`) |
 | AWSECURE_CLI_AUTOROTATE_AWS_ACCESS_KEYS | true        | true<br>false                | Enable the AWS Access Keys autorotation |
 | AWSECURE_CLI_AUTOROTATE_PERIOD          | 168         | 1 to ...                     | This value is based on hours and once your AWS Access Keys are older than this, it will autorotate (168 hours == 7 days) |
-| AWSECURE_CLI_AUTOROTATE_CHECK           | daily       | daily<br>on-reboot<br>always | This is when the autorotate will be executed.<br>If you're using in the user request, this will only be triggered if you run the AWS CLI |
+| AWSECURE_CLI_AUTOROTATE_CHECK           | daily       | daily<br>on-reboot<br>always | This is when the autorotate will be executed.<br>If you're using in the user request, this will only be triggered if you run the AWS CLI. This check is based on your AWSecure CLI utilization. If you don't set it on cronjob or use it, then it will never autorotate your AWS access keys. |
 | AWSECURE_CLI_AUTOROTATE_ONLY            | not defined | true<br>false                | This trigger only the AWS Access Keys auto-rotation, any AWS command (e.g. `aws lambda list-functions`) will be ignored |
 | AWSECURE_CLI_MFA_ON                     | false       | true<br>false                | This will add the AWS_SESSION_TOKEN on (almost) all AWS CLI request. You need to set AWSECURE_CLI_MFA_AUTO_GET_DEVICE or AWSECURE_CLI_MFA_AWS_ARN |
 | AWSECURE_CLI_MFA_AUTO_GET_DEVICE        | true        | true<br>false                | This will automatically get the first AWS MFA device configured in your user and set the AWSECURE_CLI_MFA_AWS_ARN |
 | AWSECURE_CLI_MFA_AWS_ARN                | false       | string                       | This is the AWS ARN for the MFA device configured in your user. The ARN starts with `arn:aws:iam::<AWS_Account_ID>:sms-mfa/` or `arn:aws:iam::<AWS_Account_ID>:mfa`. Please, check the "[Checking MFA status](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_checking-status.html) official documentation." |
-| AWSECURE_CLI_MFA_TOKEN_DURATION_SECOND  | 900         | int                          | This is how long the token will be valid. The token will be temporarly stored locally and renewed once is reaches the time informed. Valid range: Minimum value of 900. Maximum value of 129600 - Please, check the [AWS official documentation - AWS STS API Reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html#API_GetSessionToken_RequestParameters) |
+| AWSECURE_CLI_MFA_TOKEN_DURATION  | 900         | int                          | This is how long the token will be valid. The token will be temporarly stored locally and renewed once is reaches the time informed. Valid range: Minimum value of 900 (15 minutes). Maximum value of 129600 (36 hours) - Please, check the [AWS official documentation - AWS STS API Reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html#API_GetSessionToken_RequestParameters) |
 
 > \* mandatory parameter
 
-### Example
+## Configuration examples
+
+These are some of the configuration examples you can have in your AWSecure CLI.
+
+### Minimal (inc. Access keys autorotation)
+
+The `AWSECURE_CLI_AWS_BIN_FILEPATH` is the only thing you have to define. All the other configurations already have a pre-defined value or it's not mandatory.
 
-You can configure via `~/.awsecure-cli`.
+This will autorotate your AWS Access keys every 168 hours (7 days) and checking if it's needed to rotate every day.
+
+Defining it via `~/.awsecure-cli`.
 
 ```bash
 AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
-AWSECURE_CLI_MUTED="false"
-AWSECURE_CLI_AUTOROTATE_AWS_ACCESS_KEYS="true"
-AWSECURE_CLI_AUTOROTATE_PERIOD="24"
-AWSECURE_CLI_AUTOROTATE_CHECK="always"
-AWSECURE_CLI_AUTOROTATE_ONLY="true"
-AWSECURE_CLI_LOG_TO_FILE="true"
 ```
 
-Or export the environment variables, like:
+Or via environment variables:
 
 ```bash
 export AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
-export AWSECURE_CLI_MUTED="false"
-export AWSECURE_CLI_AUTOROTATE_AWS_ACCESS_KEYS="true"
-export AWSECURE_CLI_AUTOROTATE_PERIOD="24"
-export AWSECURE_CLI_AUTOROTATE_CHECK="always"
-export AWSECURE_CLI_AUTOROTATE_ONLY="true"
-export AWSECURE_CLI_LOG_TO_FILE="true"
 ```
 
-> The exported environment variable has high priority over the file `~/.awsecure-cli`.
+### Custom AWS Access keys autorotation
+
+AWS access keys autorotation every 336 hours (14 days).
+
+Defining it via `~/.awsecure-cli`.
+
+```bash
+AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
+AWSECURE_CLI_AUTOROTATE_PERIOD="336"
+```
+
+Or via environment variables:
+
+```bash
+export AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
+export AWSECURE_CLI_AUTOROTATE_PERIOD="336"
+```
+
+### MFA + Access keys autorotation
+
+Enable MFA and setting its session token duration time for 14400 (4 hours). Also, autorotating your AWS access keys every 168 hours (7 days).
+
+Defining it via `~/.awsecure-cli`.
+
+```bash
+export AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
+export AWSECURE_CLI_AUTOROTATE_PERIOD="168"
+export AWSECURE_CLI_MFA_ON="on"
+export AWSECURE_CLI_MFA_TOKEN_DURATION="14400"
+```
+
+Or via environment variables:
+
+```bash
+AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
+AWSECURE_CLI_AUTOROTATE_PERIOD="168"
+AWSECURE_CLI_MFA_ON="on"
+AWSECURE_CLI_MFA_TOKEN_DURATION="14400"
+```
+
+### Minimal for kubectl without kubeconfig
+
+AWSecure CLI can also be integrated with kubectl. The AWSCLI is used to get the session-token and autheticate to your EKS cluster.
+
+The only mandatory for this, is the `AWSECURE_CLI_MUTED="false"`. This is because kubectl only accepts a specific JSON return, anything more than that will cause an error and prevent you from using the kubectl.
+
+Defining it via `~/.awsecure-cli`.
+
+```bash
+AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
+AWSECURE_CLI_MUTED="true"
+```
+
+Or via environment variables:
+
+```bash
+export AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
+export AWSECURE_CLI_MUTED="true"
+```
 
-## Integrating with kubectl
+### Integrating with kubectl with kubeconfig
 
 The integration with `kubectl` will be done thanks to the integration between AWS STS and Kubernetes.
 
@@ -149,6 +212,8 @@ aws eks update-kubeconfig --name <EKS_CLUSTER_NAME> --role-arn <ROLE_ARN> --alia
 
 Make sure you have, at least, the `AWS_PROFILE` and `AWSECURE_CLI_MUTED` defined in your `~/.kube/config`.
 
+> In case you define the `AWSECURE_CLI_AUTOROTATE_PERIOD` via `~/.kube/config`, make sure it's the same as the one defined via `~/.awsecure-cli` and/or environment variables.
+
 ```yaml
 - name: arn:aws:eks:<REGION>:<ACCOUNT_ID>:cluster/<CLUSTER_NAME>
   user:
@@ -177,3 +242,53 @@ For more information, please check the AWS official documentation.
 
 * [Create a kubeconfig for Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html)
 * [AWS CLI - aws eks update-kubeconfig](https://docs.aws.amazon.com/cli/latest/reference/eks/update-kubeconfig.html)
+
+### Kubectl + MFA
+
+This will use the MFA for every kubectl request you make and it will automatically gets your first MFA device.
+
+To use the MFA is relative simply, but since kubectl will isn't interactive, you can't pass the MFA code. So, in order to fix it, you have to first run an AWSCLI command (e.g. `aws s3 ls`) to create the session token and then you can use the kubectl. You can also disable the MFA only for kubectl.
+
+Defining it via `~/.awsecure-cli`.
+
+```bash
+AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
+AWSECURE_CLI_MFA_ON="on"
+AWSECURE_CLI_MFA_TOKEN_DURATION="14400"
+```
+
+Or via environment variables:
+
+```bash
+export AWSECURE_CLI_AWS_BIN_FILEPATH=~/.asdf/shims/aws
+export AWSECURE_CLI_MFA_ON="on"
+export AWSECURE_CLI_MFA_TOKEN_DURATION="14400"
+```
+
+Or via `~/.kube/config`:
+
+> In case you define the `AWSECURE_CLI_MFA_TOKEN_DURATION` via `~/.kube/config`, make sure it's the same as the one defined via `~/.awsecure-cli` and/or environment variables.
+
+```yaml
+- name: arn:aws:eks:<REGION>:<ACCOUNT_ID>:cluster/<CLUSTER_NAME>
+  user:
+    exec:
+      apiVersion: <API_VERSION>
+      args:
+      - --region
+      - <REGION>
+      - eks
+      - get-token
+      - --cluster-name
+      - <CLUSTER_NAME>
+      - --role
+      - arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>
+      command: aws
+      env:
+      - name: AWS_PROFILE
+        value: <AWS_PROFILE>
+      - name: AWSECURE_CLI_MFA_ON
+        value: "true" ## or false, in case you want to disable it only for kubectl
+      - name: AWSECURE_CLI_MUTED
+        value: "true"
+```