diff --git a/docs/user-guide/base-configuration/overview.md b/docs/user-guide/base-configuration/overview.md index b9a1d4c1e..3cd579d95 100644 --- a/docs/user-guide/base-configuration/overview.md +++ b/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 diff --git a/docs/user-guide/identities/gpg.md b/docs/user-guide/identities/gpg.md new file mode 100644 index 000000000..d6fc75fe7 --- /dev/null +++ b/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) " + 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) " + 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 \ No newline at end of file diff --git a/docs/user-guide/identities/identities.md b/docs/user-guide/identities/identities.md index 9555900a0..4e3dd5448 100644 --- a/docs/user-guide/identities/identities.md +++ b/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 \ No newline at end of file + +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) + diff --git a/mkdocs.yml b/mkdocs.yml index 14f3628d9..1445960fe 100644 --- a/mkdocs.yml +++ b/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"