Vault auth with GCE instance (#12)

* remove commented lines
* Add test for docker requirements
* Feature: support Google GCE auth method
* Remove unused variable
* Fix shdoc workflow
* Standardize shdoc argument macro
* shdoc: Automated shell script document updates

Signed-off-by: Brian Menges <@mengesb>

.github/workflows/shell-docs.yml

@@ -40,9 +40,13 @@ jobs:
         if git diff-index --quiet HEAD; then
           echo "No shell documentation changes detected"
         else
-          git ls-files --others --exclude-standard || echo "Nothing to commit"
           git config user.email [email protected]
           git config user.name github-actions
+
+          for F in $(git ls-files --others --exclude-standard); do
+            git add "${F}"
+          done
+
           git commit -am "shdoc: Automated shell script document updates" > /dev/null || echo "Nothing to commit"
           git push --quiet
         fi

aws/aws-credentials.sh

@@ -20,6 +20,8 @@ METADATA="${EC2_METADATA_MOCK:-http://169.254.169.254/2020-10-27/meta-data}"
 # @description
 #   Acquires your instance profile ARN from the metadata API
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws-credentials.sh
 #   $ aws_instance_profile_arn
@@ -35,6 +37,8 @@ function aws_instance_profile_arn() {
 # @description
 #   Acquires your profile name from aws_instance_profile_arn() function
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws-credentials.sh
 #   $ aws_instance_profile_name
@@ -46,6 +50,8 @@ function aws_instance_profile_name() {
 # @description
 #   Acquires your security credentials for your AWS instance profile
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws-credentials.sh
 #   $ aws_credentials
@@ -65,6 +71,8 @@ function aws_credentials() {
 # @description
 #   Acquires your AWS Access Key ID from aws_credentials() function
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws-credentials.sh
 #   $ aws_access_key_id
@@ -80,6 +88,8 @@ function aws_access_key_id() {
 # @description
 #   Acquires your AWS Secret Access Key from aws_credentials() function
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws-credentials.sh
 #   $ aws_secret_access_key
@@ -95,6 +105,8 @@ function aws_secret_access_key() {
 # @description
 #   Acquires your AWS Session Token from aws_credentials() function
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws-credentials.sh
 #   $ aws_session_token
@@ -110,6 +122,8 @@ function aws_session_token() {
 # @description
 #   Outputs environment variable exports for your AWS credentials
 #
+# @noarg
+#
 # @example
 #   $ aws/aws-credentials.sh
 #   export AWS_ACCESS_KEY_ID=12345678901

aws/aws4-sign.sh

@@ -15,6 +15,8 @@ DEBUG="${DEBUG:-false}"
 # @description
 #   Generates a HMAC SHA256 digest with date and AWS_SECRET_ACCESS_KEY
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws4-sign.sh
 #   $ printf '%s' $(TZ=Z date +%Y%m%dT%H%M%SZ) | AWS4_HMAC_SHA256 "key:AWS4v/12345678901" # AWS_SECRET_ACCESS_KEY
@@ -26,25 +28,25 @@ function AWS4_HMAC_SHA256() {
 # @description
 #   Generates a SHA256 digest of the iam_request_body
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws4-sign.sh
 #   $ printf '%s' "Action=GetCallerIdentity&Version=2011-06-15" | AWS4_SHA256
 #   ab821ae955788b0e33ebd34c208442ccfc2d406e2edc5e7a39bd6458fbb4f843
-#
-# @noarg
 function AWS4_SHA256() {
   openssl dgst -sha256 -hex 2>/dev/null | awk '{print $2}'
 }
 
 # @description
 #   Encodes a string to base64
 #
+# @noarg
+#
 # @example
 #   $ source aws/aws4-sign.sh
 #   $ printf '%s' "https://sts.amazon.com/" | AWS4_BASE64
 #   aHR0cHM6Ly9zdHMuYW1hem9uLmNvbS8=
-#
-# @noarg
 function AWS4_BASE64() {
   openssl base64 -A
 }

aws/vault-iam-auth.sh

@@ -6,6 +6,9 @@
 
 # @name vault-iam-auth
 # @brief Generate JSON material to log into a Vault AWS authentication backend using the instances AWS IAM instance profile
+#
+# @noarg
+#
 # @description
 #   <!-- markdownlint-disable-file MD012 -->
 #   This script uses the AWS IAM method for logging into a Vault AWS
@@ -141,6 +144,8 @@ source "${_HERE}/aws4-sign.sh"
 # @description
 #   Generates JSON material for login
 #
+# @noarg
+#
 # @example
 #   $ aws/vault-iam-auth.sh -r my-vault-role
 #   {

docs/gcp-credentials.md

@@ -0,0 +1,84 @@
+# gcp-credentials
+
+Query GCP metadata service for information
+
+## Overview
+
+<!-- markdownlint-disable-file MD012 MD024 -->
+When sourced as a library, this provides functions to get various bits of
+information from the GCP metadata service. When operating as a script, it
+will output common environment variables used for GCP tools
+
+This code handles environments where `jq` may not be available.
+
+## Index
+
+* [headers()](#headers)
+* [url_encode()](#url_encode)
+* [gcp_identity()](#gcp_identity)
+* [gcp_service_accounts()](#gcp_service_accounts)
+
+### headers()
+
+Builds headers for curl requests from HEADERS environment variable
+
+#### Example
+
+```bash
+$ source gcp/gcp-credentials.sh
+$ headers
+-H 'Metadata-Flavor: Google'
+```
+
+### url_encode()
+
+Builds url encoding commands for curl requests
+
+#### Example
+
+```bash
+$ source gcp/gcp-credentials.sh
+$ url_encode
+--data-urlencode 'format=full'
+$ url_encode "audience=https://vault"
+--data-urlencode 'format=full' --data-urlencode 'audience=https://vault'
+```
+
+#### Arguments
+
+* **$1** (string): Data to encode in URL safe format
+
+### gcp_identity()
+
+Returns a GCE instance identity (JWT token) for the audience requested
+
+#### Example
+
+```bash
+$ source gcp/gcp-credentials.sh
+$ gcp_identity "https://vault"
+eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2NzgiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovL3ZhdWx0L215LXJvbGUiLCJhenAiOiJtb2NrQGZvby5pYW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIsImVtYWlsIjoibW9ja0Bmb28uaWFtLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiZXhwIjoxNjE2OTI4NTgwLCJpYXQiOjE2MTY5MjQ5ODAsImlzcyI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbSIsInN1YiI6IjEyMzQ1Njc4OTAxMjM0NTY3ODkwMQI.WQiOiJodHRwczovL3ZhdWx0L215LXJvbGUiLCJhenAiOiJtb2NrQGZvMKPhz_iiY9eWIs_YNn3Ix1Uil4u2_3Ix1Uil4_2OHFjThJeFfGGU8xRz8qw5kCYfd5J7Kuy4Of_mHMekDQcE3qut3fsxzd_o58VuiiY9_WIs1YNn3Ix1Uil4u2OHFjThJeFfGGU8xRz8emCRJzI9Bhqgxrd1A3ZoFRi9_ho6n7raVq-NJW33xZFbmiKpJDX1huD1zrBemCRJzI9Bhqgxrd1A3ZoFRi9pho6n7raVqC-NJW33xZFbmiKpJDX_1huD1zrBcRKwzjfS73gmJc_y5ehiJQHWNthO
+```
+
+#### Arguments
+
+* **$1** (string): Audience to request JWT token for
+
+### gcp_service_accounts()
+
+Returns information about a service accunt, or the default if none passed
+
+#### Example
+
+```bash
+$ source gcp/gcp-credentials.sh
+$ gcp_service_accounts
+{"aliases":"default","email":"[email protected]","scopes":"https://www.googleapis.com/auth/userinfo.email\nhttps://www.googleapis.com/auth/cloud-platform\n"}
+$ gcp_service_accounts "default"
+{"aliases":"default","email":"[email protected]","scopes":"https://www.googleapis.com/auth/userinfo.email\nhttps://www.googleapis.com/auth/cloud-platform\n"}
+```
+
+#### Arguments
+
+* **$1** (string): Google Service Account (Default: default)
+

docs/vault-gce-auth.md

@@ -0,0 +1,104 @@
+# vault-gce-auth
+
+Generate JSON material to log into a Vault Google authentication backend using the instances default identity
+
+## Overview
+
+<!-- markdownlint-disable-file MD012 -->
+This script uses the GCE method for logging into a Vault GCP
+authentication backend.
+
+## Usage
+
+```bash
+$ gcp/vault-gce-auth.sh -h
+usage: gcp/vault-gce-auth.sh [OPTIONS...]
+
+Log into Vault from GCE instance
+
+OPTIONS:
+-m  Vault mount               (Default: gcp)
+-r  Vault role                (REQUIRED)
+-s  Vault address             (Default: http://vault.example.internal:8200)
+
+-h  This help message
+-v  Verbose mode
+```
+
+### Vault role
+
+In google there is no instance profile, therefore the role is a required
+field. You must provide the '-r' option or use the environment variable
+$VAULT_ROLE
+
+```bash
+$ gcp/vault-gce-auth.sh -r my-vault-role
+{
+"role": "my-vault-role",
+"http_request_method": "POST",
+"jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjMiLCJ0eXAiOiJKV1QifQo=.ewogICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCBjaGFyc2V0PXV0Zi04Il0sCiAgIkhvc3QiOiBbInN0cy5hbWF6b25hd3MuY29tIl0sCiAgIlgtQW16LURhdGUiOiBbIjIwMjEwMzA1VDA1MjMxOVoiXSwKICAiWC1BbXotU2VjdXJpdHktVG9rZW4iOiBbIlRFU1Q5MnRlc3Q0OFRFU1QreTZScG9URVNUOTJ0ZXN0NDhURVNULzhvV1ZBaUJxVEVzVDVLeTd0eTJ0RVN0eEMxVD09Il0sCiAgIlgtVmF1bHQtQVdTLUlBTS1TZXJ2ZXItSWQiOiBbIm15LWludGVybmFsLXZhdWx0LmRvbWFpbi50bGQiXSwKICAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPTEyMzQ1Njc4OTAxLzIwMjEwMzA1L3VzLWVhc3QtMS9zdHMvYXdzNF9yZXF1ZXN0LCBTaWduZWRIZWFkZXJzPWNvbnRlbnQtdHlwZTtob3N0O3gtYW16LWRhdGU7eC1hbXotc2VjdXJpdHktdG9rZW47eC12YXVsdC1hd3MtaWFtLXNlcnZlci1pZCwgU2lnbmF0dXJlPWVmYmNlN2M0NGNhNzJhNDRmZWEzMTA5OTZhNWI2MmJjNTE5YTkxMzY5ZjUyNTcwMGRkMDlhZGI1NWNjYjh-U_KpT5JdhRhKQswcsBb59SYV1EM5kMOPxkHcGPzF3lKuxFC8Uqg"
+}
+```
+
+```bash
+$ export VAULT_ROLE=my-vault-role
+$ gcp/vault-gce-auth.sh
+{
+"role": "my-vault-role",
+"http_request_method": "POST",
+"jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjMiLCJ0eXAiOiJKV1QifQo=.ewogICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCBjaGFyc2V0PXV0Zi04Il0sCiAgIkhvc3QiOiBbInN0cy5hbWF6b25hd3MuY29tIl0sCiAgIlgtQW16LURhdGUiOiBbIjIwMjEwMzA1VDA1MjMxOVoiXSwKICAiWC1BbXotU2VjdXJpdHktVG9rZW4iOiBbIlRFU1Q5MnRlc3Q0OFRFU1QreTZScG9URVNUOTJ0ZXN0NDhURVNULzhvV1ZBaUJxVEVzVDVLeTd0eTJ0RVN0eEMxVD09Il0sCiAgIlgtVmF1bHQtQVdTLUlBTS1TZXJ2ZXItSWQiOiBbIm15LWludGVybmFsLXZhdWx0LmRvbWFpbi50bGQiXSwKICAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPTEyMzQ1Njc4OTAxLzIwMjEwMzA1L3VzLWVhc3QtMS9zdHMvYXdzNF9yZXF1ZXN0LCBTaWduZWRIZWFkZXJzPWNvbnRlbnQtdHlwZTtob3N0O3gtYW16LWRhdGU7eC1hbXotc2VjdXJpdHktdG9rZW47eC12YXVsdC1hd3MtaWFtLXNlcnZlci1pZCwgU2lnbmF0dXJlPWVmYmNlN2M0NGNhNzJhNDRmZWEzMTA5OTZhNWI2MmJjNTE5YTkxMzY5ZjUyNTcwMGRkMDlhZGI1NWNjYjh-U_KpT5JdhRhKQswcsBb59SYV1EM5kMOPxkHcGPzF3lKuxFC8Uqg"
+}
+```
+
+### Vault address
+
+This updates the audience field when generating the JWT portion. You may
+use either the option (-s) or the environment variable $VAULT_ADDR to set
+the Vault address
+
+```bash
+$ gcp/vault-gce-auth.sh -r my-vault-role -s https://my-internal-vault.domain.tld
+{
+"role": "my-vault-role",
+"http_request_method": "POST",
+"jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjMiLCJ0eXAiOiJKV1QifQo=.ewogICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCBjaGFyc2V0PXV0Zi04Il0sCiAgIkhvc3QiOiBbInN0cy5hbWF6b25hd3MuY29tIl0sCiAgIlgtQW16LURhdGUiOiBbIjIwMjEwMzA1VDA1MjMxOVoiXSwKICAiWC1BbXotU2VjdXJpdHktVG9rZW4iOiBbIlRFU1Q5MnRlc3Q0OFRFU1QreTZScG9URVNUOTJ0ZXN0NDhURVNULzhvV1ZBaUJxVEVzVDVLeTd0eTJ0RVN0eEMxVD09Il0sCiAgIlgtVmF1bHQtQVdTLUlBTS1TZXJ2ZXItSWQiOiBbIm15LWludGVybmFsLXZhdWx0LmRvbWFpbi50bGQiXSwKICAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPTEyMzQ1Njc4OTAxLzIwMjEwMzA1L3VzLWVhc3QtMS9zdHMvYXdzNF9yZXF1ZXN0LCBTaWduZWRIZWFkZXJzPWNvbnRlbnQtdHlwZTtob3N0O3gtYW16LWRhdGU7eC1hbXotc2VjdXJpdHktdG9rZW47eC12YXVsdC1hd3MtaWFtLXNlcnZlci1pZCwgU2lnbmF0dXJlPWVmYmNlN2M0NGNhNzJhNDRmZWEzMTA5OTZhNWI2MmJjNTE5YTkxMzY5ZjUyNTcwMGRkMDlhZGI1NWNjYjh-U_KpT5JdhRhKQswcsBb59SYV1EM5kMOPxkHcGPzF3lKuxFC8Uqg"
+}
+```
+
+```bash
+$ export VAULT_ADDR=https://my-internal-vault.domain.tld
+$ gcp/vault-gce-auth.sh -r my-vault-role
+{
+"role": "my-vault-role",
+"http_request_method": "POST",
+"jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjMiLCJ0eXAiOiJKV1QifQo=.ewogICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCBjaGFyc2V0PXV0Zi04Il0sCiAgIkhvc3QiOiBbInN0cy5hbWF6b25hd3MuY29tIl0sCiAgIlgtQW16LURhdGUiOiBbIjIwMjEwMzA1VDA1MjMxOVoiXSwKICAiWC1BbXotU2VjdXJpdHktVG9rZW4iOiBbIlRFU1Q5MnRlc3Q0OFRFU1QreTZScG9URVNUOTJ0ZXN0NDhURVNULzhvV1ZBaUJxVEVzVDVLeTd0eTJ0RVN0eEMxVD09Il0sCiAgIlgtVmF1bHQtQVdTLUlBTS1TZXJ2ZXItSWQiOiBbIm15LWludGVybmFsLXZhdWx0LmRvbWFpbi50bGQiXSwKICAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPTEyMzQ1Njc4OTAxLzIwMjEwMzA1L3VzLWVhc3QtMS9zdHMvYXdzNF9yZXF1ZXN0LCBTaWduZWRIZWFkZXJzPWNvbnRlbnQtdHlwZTtob3N0O3gtYW16LWRhdGU7eC1hbXotc2VjdXJpdHktdG9rZW47eC12YXVsdC1hd3MtaWFtLXNlcnZlci1pZCwgU2lnbmF0dXJlPWVmYmNlN2M0NGNhNzJhNDRmZWEzMTA5OTZhNWI2MmJjNTE5YTkxMzY5ZjUyNTcwMGRkMDlhZGI1NWNjYjh-U_KpT5JdhRhKQswcsBb59SYV1EM5kMOPxkHcGPzF3lKuxFC8Uqg"
+}
+```
+
+### Vault mount
+
+This updates the audience field when generating the JWT portion. You may
+use either the option (-m) or the environment variable $VAULT_MOUNT to set
+the Vault mount
+
+```bash
+$ gcp/vault-gce-auth.sh -r my-vault-role -m gcp
+{
+"role": "my-vault-role",
+"http_request_method": "POST",
+"jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjMiLCJ0eXAiOiJKV1QifQo=.ewogICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCBjaGFyc2V0PXV0Zi04Il0sCiAgIkhvc3QiOiBbInN0cy5hbWF6b25hd3MuY29tIl0sCiAgIlgtQW16LURhdGUiOiBbIjIwMjEwMzA1VDA1MjMxOVoiXSwKICAiWC1BbXotU2VjdXJpdHktVG9rZW4iOiBbIlRFU1Q5MnRlc3Q0OFRFU1QreTZScG9URVNUOTJ0ZXN0NDhURVNULzhvV1ZBaUJxVEVzVDVLeTd0eTJ0RVN0eEMxVD09Il0sCiAgIlgtVmF1bHQtQVdTLUlBTS1TZXJ2ZXItSWQiOiBbIm15LWludGVybmFsLXZhdWx0LmRvbWFpbi50bGQiXSwKICAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPTEyMzQ1Njc4OTAxLzIwMjEwMzA1L3VzLWVhc3QtMS9zdHMvYXdzNF9yZXF1ZXN0LCBTaWduZWRIZWFkZXJzPWNvbnRlbnQtdHlwZTtob3N0O3gtYW16LWRhdGU7eC1hbXotc2VjdXJpdHktdG9rZW47eC12YXVsdC1hd3MtaWFtLXNlcnZlci1pZCwgU2lnbmF0dXJlPWVmYmNlN2M0NGNhNzJhNDRmZWEzMTA5OTZhNWI2MmJjNTE5YTkxMzY5ZjUyNTcwMGRkMDlhZGI1NWNjYjh-U_KpT5JdhRhKQswcsBb59SYV1EM5kMOPxkHcGPzF3lKuxFC8Uqg"
+}
+```
+
+```bash
+$ export VAULT_MOUNT=gcp
+$ gcp/vault-gce-auth.sh -r my-vault-role
+{
+"role": "my-vault-role",
+"http_request_method": "POST",
+"jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjMiLCJ0eXAiOiJKV1QifQo=.ewogICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCBjaGFyc2V0PXV0Zi04Il0sCiAgIkhvc3QiOiBbInN0cy5hbWF6b25hd3MuY29tIl0sCiAgIlgtQW16LURhdGUiOiBbIjIwMjEwMzA1VDA1MjMxOVoiXSwKICAiWC1BbXotU2VjdXJpdHktVG9rZW4iOiBbIlRFU1Q5MnRlc3Q0OFRFU1QreTZScG9URVNUOTJ0ZXN0NDhURVNULzhvV1ZBaUJxVEVzVDVLeTd0eTJ0RVN0eEMxVD09Il0sCiAgIlgtVmF1bHQtQVdTLUlBTS1TZXJ2ZXItSWQiOiBbIm15LWludGVybmFsLXZhdWx0LmRvbWFpbi50bGQiXSwKICAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPTEyMzQ1Njc4OTAxLzIwMjEwMzA1L3VzLWVhc3QtMS9zdHMvYXdzNF9yZXF1ZXN0LCBTaWduZWRIZWFkZXJzPWNvbnRlbnQtdHlwZTtob3N0O3gtYW16LWRhdGU7eC1hbXotc2VjdXJpdHktdG9rZW47eC12YXVsdC1hd3MtaWFtLXNlcnZlci1pZCwgU2lnbmF0dXJlPWVmYmNlN2M0NGNhNzJhNDRmZWEzMTA5OTZhNWI2MmJjNTE5YTkxMzY5ZjUyNTcwMGRkMDlhZGI1NWNjYjh-U_KpT5JdhRhKQswcsBb59SYV1EM5kMOPxkHcGPzF3lKuxFC8Uqg"
+}
+```
+
+
+