Merge pull request #40 from binbashar/BBL-19-ref-arch-doc-content-upd…

…ates

BBL-19 | user-guide/identities completed

docs/user-guide/base-configuration/overview.md

@@ -7,6 +7,7 @@
     * [x] **Docker engine** `>= 19.03.12`(check via `docker --version`) 
     * [x] **Python** `>= 3.8` (check via `python3 --version` || `python3.8 --version`) 
     * [x] **jq** `>= jq-1.5-1-a5b5cbe` (check via `jq --version`)
+    * [x] **aws-cli** `>= 1.16.265` (check via `aws --version`)
 
 ## Configurations
 Specific configuration per component could be found in the immediately following entries

docs/user-guide/identities/gpg.md

@@ -0,0 +1,64 @@
+# PGP keys helper
+
+## Why to use PGP?
+
+By default our [Leverage Reference Architectre base-identities layer](https://github.com/binbashar/le-tf-infra-aws/blob/master/security/base-identities/users.tf) 
+approach is to use [IAM module]([https://github.com/binbashar/terraform-aws-iam/tree/master/modules/iam-user]) 
+to manage AWS IAM Users credentials with **encryption to grant strong security**. 
+
+This **module** outputs commands and PGP messages which can be decrypted either using command line to get AWS Web Connsole
+user's password and user's secret key.   
+
+!!! warning "Notes for keybase users"
+    If possible, always use PGP encryption to prevent Terraform from keeping unencrypted password and access secret key 
+    in state file.
+
+!!! check "Keybase pre-requisites"
+    When `pgp_key` is specified as `keybase:username`, make sure that the user public key has already been uploaded to 
+    the [Reference Architecture base-identities layer `keys` folder](https://github.com/binbashar/le-tf-infra-aws/tree/master/security/base-identities/keys) 
+
+## How to manage your GPG keys?
+
+!!! info "Create a key pair"
+    - NOTE: the user for whom this account is being created needs to do this
+    - Install `gpg`
+    - Run `gpg --version` to confirm
+    - Run `gpg --gen-key` and provide "Your Name" and "Your Email" as instructed -- you must also provide a passphrase
+    - Run `gpg --list-keys` to check that your key was generated
+
+!!! info "Delete a key pair"
+    - Run `gpg --list-keys` to check your key id
+    - Run `gpg --delete-secret-keys "Your Name"` to delete your private gpg key
+    - Run `gpg --delete-key "Your Name"` to delete your public gpg key
+
+!!! info "Export your public key"
+    - NOTE: the user must have created a key pair before doing this
+    - Run `gpg --export "Your Name" | base64`
+    - Now the user can share her/his public key for creating her/his account
+
+!!! info "Decrypt your encrypted password"
+    1. The user should copy the encrypted password from whatever media it was provided to her/him
+    2. Run `echo "YOUR ENCRYPTED STRING PASSWORD HERE" | base64 --decode > a_file_with_your_pass`
+    ```bash
+    $ echo "wcBMA/ujy1wF7UPcAQgASLL/x8zz7OHIP+EHU7IAZfa1A9qD9ScP5orK1M473WlXVgPrded0iHpyZRwsJRS8Xe38AHZ65O6CnywdR522MbD\
+    RD6Yz+Bfc9NwO316bfSoTpyROXvMi+cfMEcihInHaCIP9YWBaI3eJ6VFdn90g9of00HYehBux7E2VitMuWo+v46W1p8/pw0b0H5qcppnUYYOjjSbjzzAuMF\
+    yNB5M1K8av61bPQPQTxBH3SFaM0B4RNmUl1bHKDIcdESYyIP/PRLQ45Rs5MzGgALIxBy24qdPNjHJQR48/5QV4nzB9qeEe4eWDB4ynSEfLsXggiz8fsbajV\
+    gSLNsdpqP9lYaueFdLgAeR6a+EjvqZfq0hZAgoiymsb4Qtn4A7gmeGmNeDE4td1mVfgzuTZ9zhnSbAYlXNIiM4b0MeX4HrjFkT/Aq+A/rvgBeKhszWD4Ibh\
+    A4PgC+QPiJRb5kQ/mX8DheQfAHJ24iUZk1jh6AsA" | base64 --decode > encrypted_pass
+    ```
+    3. Run `gpg --decrypt a_file_with_your_pass` (in the path you've executed 2.) to effectively decrypt your pass using
+     your gpg key and its passphrase
+    ```bash
+    $ gpg --decrypt encrypted_pass
+
+    You need a passphrase to unlock the secret key for
+    user: "Demo User (AWS org project-user acct gpg key w/ passphrase) <[email protected]>"
+    2048-bit RSA key, ID 05ED43DC, created 2019-03-15 (main key ID D64DD59F)
+
+    gpg: encrypted with 2048-bit RSA key, ID 05ED43DC, created 2019-03-15
+          "Demo User (AWS org project-user acct gpg key w/ passphrase) <[email protected]>"
+    Vi0JA|c%fP*FhL}CE-D7ssp_TVGlf#%
+    ```
+    :warning: Depending on your shell version an extra `%` character could appear as shown below, you must disregard this
+    character since it's not part of the Initial (one time) AWS Web Console password. 
+    4. If all went well, the decrypted password should be there

docs/user-guide/identities/identities.md

@@ -1,7 +1,145 @@
 # Identity and Access Management (IAM) Layer
 
-## How it works
-TODO
-
+!!! help "How it works"
+    :books: [**documentation:** identities](../../how-it-works/identities/identities.md)
+    
 ## User guide
-TODO
+
+Please follow the steps below to orchestrate your `base-identities` layer 1st in your
+[`project-root`](https://github.com/binbashar/le-tf-infra-aws/tree/master/root/base-identities) AWS account and
+afterwards in your [`project-security`](https://github.com/binbashar/le-tf-infra-aws/tree/master/security/base-identities) account.
+
+!!! example "IAM user standard creation workflow"
+    1. Pre-requisite add Public PGP Key following the [documentation](./gpg.md) 
+    2. For steps 3. and 4. consider following 
+    [Terraform `make` workflow](https://leverage.binbash.com.ar/user-guide/base-workflow/repo-le-tf-infra-aws/)
+    3. Update (add | remove) your IAM Users associated code and deploy 
+    [security/base-identities/users.tf](https://github.com/binbashibilitySRL/devops-tf-infra/blob/master/security/base-identities/users.tf)
+    4. Update (add | remove | edit) your IAM Groups associated code and deploy 
+    [security/base-identities/groups.tf](https://github.com/binbashibilitySRL/devops-tf-infra/blob/master/security/base-identities/groups.tf)
+    5. Get and share the IAM Users AWS Console user id and its OTP associated password from the 
+    [`make apply` outputs](https://github.com/binbashar/le-tf-infra-aws/blob/master/security/base-identities/outputs.tf)
+        * :warning: temporally set `sensitive   = false` to get the encrypted outputs in your prompt output.
+    6. Each user will need to decrypt its AWS Console Password, you could share the [associated documentation](./gpg.md) with them.
+    7. Users must login to the AWS Web Console (https://project-security.signin.aws.amazon.com/console) with their
+     decrypted password and create new pass 
+    8. Activate MFA for Web Console (Optional but strongly recommended)
+    9. User should 
+    [create his AWS ACCESS KEYS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) 
+    if needed 
+    10. User could optionally set up `~/.aws/project/credentials` + `~/.aws/project/config` following the immediately
+     below **AWS Credentials Setup** sub-section
+
+
+### AWS Credentials Setup
+
+* :warning: **TODO:** This task will be automated via 
+    * [x] [Makefile](https://github.com/binbashar/le-tf-infra-aws/blob/master/Makefile)
+    * [x] [Script](https://github.com/binbashar/le-tf-infra-aws/tree/master/%40bin/scripts)
+
+#### Example for: `~/.aws/leverage/credentials`
+
+```
+#================================================================#
+# LEVERAGE credentials                                           #
+#================================================================#
+#------------------------------------#
+# AWS OrganizationAccountAccessRole  #
+#------------------------------------#
+[binbash-root]
+aws_access_key_id = AKIXXXXXXXXXXXXXXXXXXXXX
+aws_secret_access_key = cKJ2XXXXXXXXXXXXXXXXXXXXXXXXXXX
+region = us-east-1
+
+#------------------------------------#
+# AWS DevOps Role                    #
+#------------------------------------#
+[binbash-security]
+aws_access_key_id = AKXXXXXXXXXXXXXXXXXXXXXXX
+aws_secret_access_key = cKJ29HXXXXXXXXXXXXXXXXXXXXXXXXX
+region = us-east-1 
+```
+
+#### Example for: `~/.aws/leverage/cofigs`
+
+```
+[default]
+output = json
+region = us-east-1
+
+#================================================================#
+# LEVERAGE config                                                #
+#================================================================#
+#------------------------------------#
+# AWS OrganizationAccountAccessRole  #
+#------------------------------------#
+[profile binbash-security-oaar]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::111111111111:role/OrganizationAccountAccessRole
+source_profile = binbash-root
+
+[profile binbash-shared-oaar]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::222222222222:role/OrganizationAccountAccessRole
+source_profile = binbash-root
+
+[profile binbash-apps-devstg-oaar]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::333333333333:role/OrganizationAccountAccessRole
+source_profile = binbash-root
+
+[profile binbash-apps-prd-oaar-replication]
+output = json
+region = us-east-2
+role_arn = arn:aws:iam::444444444444:role/OrganizationAccountAccessRole
+source_profile = binbash-root
+
+[profile binbash-legacy-oaar]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::555555555555:role/OrganizationAccountAccessRole
+source_profile = binbash-root
+
+#------------------------------------#
+# AWS DevOps Role                    #
+#------------------------------------#
+[profile binbash-security-devops]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::111111111111:role/DevOps
+source_profile = binbash-security
+
+[profile binbash-shared-devops]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::222222222222:role/DevOps
+source_profile = binbash-security
+
+[profile binbash-apps-devstg-devops]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::333333333333:role/DevOps
+source_profile = binbash-security
+
+[profile binbash-apps-prd-devops]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::444444444444:role/DevOps
+source_profile = binbash-security
+
+[profile binbash-legacy-devops]
+output = json
+region = us-east-1
+role_arn = arn:aws:iam::555555555555:role/DevOps
+source_profile = binbash-security 
+```
+
+## Read More
+
+!!! info "AWS reference links"
+    Consider the following AWS official links as reference:        
+    - :orange_book: [Best practices for managing AWS access keys](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html)
+

mkdocs.yml

@@ -33,17 +33,20 @@ theme:
 
 extra:
   social:
+    - icon: material/home
+      link: 'https://www.binbash.com.ar'
     - icon: material/github
       link: 'https://github.com/binbashar'
     - icon: material/linkedin
       link: 'https://www.linkedin.com/company/binbash'
+    - icon: material/slack
+      link: 'https://join.slack.com/t/binbashar/shared_invite/zt-fw1692b6-9k4ADsWJ47lKacszphXM1w'
+    - icon: fontawesome/brands/medium
+      link: 'https://medium.com/binbash-inc'
     - icon: material/twitter
       link: 'https://twitter.com/binbash_devops'
     - icon: material/docker
       link: 'https://hub.docker.com/orgs/binbash'
-    - icon: material/home
-      link: 'https://www.binbash.com.ar'
-
 
 #===================================================================================#
 # Mkdocs Markdown Extentions, Plugins & extras
@@ -157,7 +160,9 @@ nav:
         - Helm Infra: "user-guide/base-workflow/repo-le-helm-infra.md"
     - AWS Organization:
       - Organization: "user-guide/organization/organization.md"
-    - Identities: "user-guide/identities/identities.md"
+    - Identities:
+      - gpg: "user-guide/identities/gpg.md"
+      - identities: "user-guide/identities/identities.md"
     - Security:
       - VPN: "user-guide/security/vpn.md"
       - Services: "user-guide/security/services.md"