From 32cc6ddce8fe599154dd9689e0bdda0b993e644d Mon Sep 17 00:00:00 2001
From: Aaron Turner <synfinatic@gmail.com>
Date: Mon, 22 Nov 2021 18:17:22 -0800
Subject: [PATCH] Add a FAQ
---
Makefile | 6 ++++++
README.md | 1 +
docs/.gitignore | 1 +
docs/FAQ.md | 38 ++++++++++++++++++++++++++++++++++++++
docs/default-region.dot | 33 +++++++++++++++++++++++++++++++++
5 files changed, 79 insertions(+)
create mode 100644 docs/.gitignore
create mode 100644 docs/FAQ.md
create mode 100644 docs/default-region.dot
diff --git a/Makefile b/Makefile
index dd53f87b..aa78c5a4 100644
--- a/Makefile
+++ b/Makefile
@@ -224,3 +224,9 @@ $(DARWINARM64_BIN): $(wildcard */*.go) .prepare
$(OUTPUT_NAME): $(wildcard */*.go) .prepare
go build -ldflags='$(LDFLAGS)' -o $(OUTPUT_NAME) cmd/*.go
+
+docs: docs/default-region.png
+
+docs/default-region.png:
+ dot -o docs/default-region.png -Tpng docs/default-region.dot
+
diff --git a/README.md b/README.md
index d8ae5ad2..f83a47e5 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@
* [Environment Varables](#environment-varables)
* [Release History](#release-history)
* [License](#license)
+ * [Frequently Asked Questions](docs/FAQ.md)
## About
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 00000000..e33609d2
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+*.png
diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 00000000..6771323b
--- /dev/null
+++ b/docs/FAQ.md
@@ -0,0 +1,38 @@
+# Frequently Asked Questions
+
+ * [How do I change the password for the macOS Keychain?](#how-do-i-change-the-password-for-the-macos-keychain)
+ * [How does AWS SSO manage the $AWS\_DEFAULT\_REGION?](#how-does-aws-sso-manage-the-aws_default_region)
+
+### How do I change the password for the macOS Keychain?
+
+You can use `Keychain Access` to do this. From a terminal, type:
+
+`open ~/Library/Keychains/AWSSSOCli.keychain-db`
+
+Then make sure to select the `AWSSSOCli` keychain. Then:
+
+`Edit -> Change password for AWSSSOCli...`
+
+### How does AWS SSO manage the $AWS_DEFAULT_REGION?
+
+AWS SSO will leave the `$AWS_DEFAULT_REGION` environment variable alone
+unless the following are all true:
+
+ * The `$AWS_DEFAULT_REGION` is not already defined in your shell
+ * You have specified the region in the `config.yaml` via `DefaultRegion`
+ * You have not set the `--no-region` flag on the CLI
+ * If `$AWS_SSO_DEFAULT_REGION` is set, does it match `$AWS_DEFAULT_REGION?`
+
+If the above are true, then AWS SSO will define both:
+
+ * `$AWS_DEFAULT_REGION`
+ * `$AWS_SSO_DEFAULT_REGION`
+
+to the default region as defined by `config.yaml`. If the user changes
+roles and the two variables are set to the same region, then AWS SSO will
+update the region. If the user ever overrides the `$AWS_DEFAULT_REGION`
+value or deletes the `$AWS_SSO_DEFAULT_REGION` then AWS SSO will no longer
+manage the variable.
+
+<!-- https://github.com/synfinatic/aws-sso-cli/issues/166 -->
+
diff --git a/docs/default-region.dot b/docs/default-region.dot
new file mode 100644
index 00000000..e062e804
--- /dev/null
+++ b/docs/default-region.dot
@@ -0,0 +1,33 @@
+digraph g {
+ Start -> ADR_SET
+
+ ADR_SET [label="Is $AWS_DEFAULT_REGION defined?"]
+ ADR_SET -> Have_ASDR [label="Yes"]
+ ADR_SET -> Have_DR [label="No"]
+
+ Have_ASDR [label="Is $AWS_SSO_DEFAULT_REGION defined?"]
+ Have_ASDR -> No_Change [label="No"]
+ Have_ASDR -> Var_Match [label="Yes"]
+
+ Var_Match [label="Does $AWS_DEFAULT_REGION match $AWS_SSO_DEFAULT_REGION?"]
+ Var_Match -> Delete_ADSR [label="No"]
+ Var_Match -> Have_DR [label="Yes"]
+
+ Have_DR [label="Is DefaultRegion defined in config.yaml?"]
+ Have_DR -> No_Change [label="No"]
+ Have_DR -> No_Region [label="Yes"]
+
+ No_Change [label="No changes to environment"]
+ No_Change -> End
+
+ No_Region [label="Is --no-region set?"]
+ No_Region -> No_Change [label="Yes"]
+ No_Region -> Set_ADR [label="No"]
+
+ Set_ADR [label="Set $AWS_DEFAULT_REGION"]
+
+ Delete_ADSR [label="Unset $AWS_SSO_DEFAULT_REGION"]
+
+ Delete_ADSR -> End
+ Set_ADR -> End
+}