Document usage of CI_JOB_JWT

with an example

doc/ci/examples/README.md

@@ -20,24 +20,25 @@ Examples are available in several forms. As a collection of:
 
 The following table lists examples with step-by-step tutorials that are contained in this section.
 
-| Use case                    | Resource                                                                                                                   |
-|:----------------------------|:---------------------------------------------------------------------------------------------------------------------------|
-| Browser performance testing | [Browser Performance Testing with the Sitespeed.io container](../../user/project/merge_requests/browser_performance_testing.md). |
-| Clojure                     | [Test a Clojure application with GitLab CI/CD](test-clojure-application.md).                                               |
-| Deployment with Dpl         | [Using `dpl` as deployment tool](deployment/README.md).                                                                    |
-| Elixir                      | [Testing a Phoenix application with GitLab CI/CD](test_phoenix_app_with_gitlab_ci_cd/index.md).                            |
-| End-to-end testing          | [End-to-end testing with GitLab CI/CD and WebdriverIO](end_to_end_testing_webdriverio/index.md).                           |
-| Game development            | [DevOps and Game Dev with GitLab CI/CD](devops_and_game_dev_with_gitlab_ci_cd/index.md).                                   |
-| GitLab Pages                | See the [GitLab Pages](../../user/project/pages/index.md) documentation for a complete example of deploying a static site. |
-| Java with Spring Boot       | [Deploy a Spring Boot application to Cloud Foundry with GitLab CI/CD](deploy_spring_boot_to_cloud_foundry/index.md).       |
-| Java with Maven             | [How to deploy Maven projects to Artifactory with GitLab CI/CD](artifactory_and_gitlab/index.md).                          |
-| PHP with PHPunit, atoum     | [Testing PHP projects](php.md).                                                                                            |
-| PHP with NPM, SCP           | [Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md).             |
-| PHP with Laravel, Envoy     | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md).                |
-| Python on Heroku            | [Test and deploy a Python application with GitLab CI/CD](test-and-deploy-python-application-to-heroku.md).                 |
-| Ruby on Heroku              | [Test and deploy a Ruby application with GitLab CI/CD](test-and-deploy-ruby-application-to-heroku.md).                     |
-| Scala on Heroku             | [Test and deploy a Scala application to Heroku](test-scala-application.md).                                                |
-| Parallel testing Ruby & JS  | [GitLab CI/CD parallel jobs testing for Ruby & JavaScript projects](https://docs.knapsackpro.com/2019/how-to-run-parallel-jobs-for-rspec-tests-on-gitlab-ci-pipeline-and-speed-up-ruby-javascript-testing). |
+| Use case                      | Resource                                                                                                                   |
+|:------------------------------|:---------------------------------------------------------------------------------------------------------------------------|
+| Browser performance testing   | [Browser Performance Testing with the Sitespeed.io container](../../user/project/merge_requests/browser_performance_testing.md). |
+| Clojure                       | [Test a Clojure application with GitLab CI/CD](test-clojure-application.md).                                               |
+| Deployment with Dpl           | [Using `dpl` as deployment tool](deployment/README.md).                                                                    |
+| Elixir                        | [Testing a Phoenix application with GitLab CI/CD](test_phoenix_app_with_gitlab_ci_cd/index.md).                            |
+| End-to-end testing            | [End-to-end testing with GitLab CI/CD and WebdriverIO](end_to_end_testing_webdriverio/index.md).                           |
+| Game development              | [DevOps and Game Dev with GitLab CI/CD](devops_and_game_dev_with_gitlab_ci_cd/index.md).                                   |
+| GitLab Pages                  | See the [GitLab Pages](../../user/project/pages/index.md) documentation for a complete example of deploying a static site. |
+| Java with Spring Boot         | [Deploy a Spring Boot application to Cloud Foundry with GitLab CI/CD](deploy_spring_boot_to_cloud_foundry/index.md).       |
+| Java with Maven               | [How to deploy Maven projects to Artifactory with GitLab CI/CD](artifactory_and_gitlab/index.md).                          |
+| PHP with PHPunit, atoum       | [Testing PHP projects](php.md).                                                                                            |
+| PHP with NPM, SCP             | [Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md).             |
+| PHP with Laravel, Envoy       | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md).                |
+| Python on Heroku              | [Test and deploy a Python application with GitLab CI/CD](test-and-deploy-python-application-to-heroku.md).                 |
+| Ruby on Heroku                | [Test and deploy a Ruby application with GitLab CI/CD](test-and-deploy-ruby-application-to-heroku.md).                     |
+| Scala on Heroku               | [Test and deploy a Scala application to Heroku](test-scala-application.md).                                                |
+| Parallel testing Ruby & JS    | [GitLab CI/CD parallel jobs testing for Ruby & JavaScript projects](https://docs.knapsackpro.com/2019/how-to-run-parallel-jobs-for-rspec-tests-on-gitlab-ci-pipeline-and-speed-up-ruby-javascript-testing). |
+| Secrets management with Vault | [Authenticating and Reading Secrets With Hashicorp Vault](authenticating-with-hashicorp-vault/index.md).                    |
 
 ### Contributing examples
 

doc/ci/examples/authenticating-with-hashicorp-vault/index.md

+---
+type: tutorial
+---
+
+# Authenticating and Reading Secrets With Hashicorp Vault
+
+This tutorial demonstrates how to authenticate, configure, and read secrets with HashiCorp's Vault from GitLab CI/CD.
+
+## Requirements
+
+This tutorial assumes you are familiar with GitLab CI/CD and Vault.
+
+To follow along, you will need:
+
+- An account on GitLab.
+- A running Vault server and the access required to configure authentication and create roles and policies.
+
+NOTE: **Note:**
+You will need to replace the `vault.example.com` URL below with the URL of your Vault server and `gitlab.example.com` with the URL of your GitLab instance.
+
+## How it works
+
+Each job has JSON Web Token (JWT) provided as environment variable named `CI_JOB_JWT`. This JWT can be used to authenticate with Vault using the [JWT Auth](https://www.vaultproject.io/docs/auth/jwt/#jwt-authentication) method.
+
+The JWT's payload looks like this:
+
+```json
+{
+  "jti": "c82eeb0c-5c6f-4a33-abf5-4c474b92b558", # Unique identifier for this token
+  "iss": "gitlab.example.com",                   # Issuer, the domain of your GitLab instance
+  "iat": 1585710286,                             # Issued at
+  "nbf": 1585798372,                             # Not valid before
+  "exp": 1585713886,                             # Expire at
+  "sub": "22",                                   # Subject (project id)
+  "namespace_id": "1",
+  "namespace_path": "mygroup",
+  "project_id": "22",
+  "project_path": "mygroup/myproject",
+  "user_id": "42",
+  "user_login": "myuser",
+  "user_email": "myuser@example.com"
+  "pipeline_id": "1212",
+  "job_id": "1212",
+  "ref": "auto-deploy-2020-04-01",               # Git ref for this job
+  "ref_type": "branch",                          # Git ref type, branch or tag
+  "ref_protected": "true"                        # true if this git ref is protected, false otherwise
+}
+```
+
+The JWT is encoded by using RS256 and signed with your GitLab instance's OpenID Connect private key. You can use this JWT and the existing JWKS endpoint (for example, `https://gitlab.example.com/oauth/discovery/keys`) to authenticate with a Vault server that is configured to allow the JWT Authentication method for authentication.
+
+When configuring roles in Vault, you can use [bound_claims](https://www.vaultproject.io/docs/auth/jwt/#bound-claims) to match against the JWT's claims and restrict which secrets each CI job has access to.
+
+To communicate with Vault, you can use either its CLI client or perform API requests (using `curl` or another client).
+
+## Example
+
+CAUTION: **Caution**:
+JWTs are credentials, which can grant access to resources. Be careful where you paste them!
+
+Let's say you have the passwords for your staging and production databases stored in a Vault server that is running on `http://vault.example.com:8200`. Your staging password is `pa$$w0rd` and your production password is `real-pa$$w0rd`.
+
+```shell
+$ vault kv get -field=password secret/myproject/staging/db
+pa$$w0rd
+
+$ vault kv get -field=password secret/myproject/production/db
+real-pa$$w0rd
+```
+
+To configure your Vault server, start by enabling the [JWT Auth](https://www.vaultproject.io/docs/auth/jwt/) method:
+
+```shell
+$ vault auth enable jwt
+Success! Enabled jwt auth method at: jwt/
+```
+
+Then create policies that allow you to read these secrets (one for each secret):
+
+```shell
+$ vault policy write myproject-staging - <<EOF
+# Policy name: myproject-staging
+#
+# Read-only permission on 'secret/data/myproject/staging/*' path
+path "secret/data/myproject/staging/*" {
+  capabilities = [ "read" ]
+}
+EOF
+Success! Uploaded policy: myproject-staging
+
+$ vault policy write myproject-production - <<EOF
+# Policy name: myproject-production
+#
+# Read-only permission on 'secret/data/myproject/production/*' path
+path "secret/data/myproject/production/*" {
+  capabilities = [ "read" ]
+}
+EOF
+Success! Uploaded policy: myproject-production
+```
+
+You'll also need roles that will link the JWT with these policies.
+
+One for staging named `myproject-staging`:
+
+```shell
+$ vault write auth/jwt/role/myproject-staging - <<EOF
+{
+  "role_type": "jwt",
+  "policies": ["myproject-staging"],
+  "token_explicit_max_ttl": 60,
+  "bound_subject": "22",
+  "user_claim": "user_email",
+  "bound_claims": {
+    "ref": "master",
+    "ref_type": "branch"
+  }
+}
+EOF
+```
+
+And one for production named `myproject-production`:
+
+```shell
+$ vault write auth/jwt/role/myproject-production - <<EOF
+{
+  "role_type": "jwt",
+  "policies": ["myproject-production"],
+  "token_explicit_max_ttl": 60,
+  "bound_subject": "22",
+  "user_claim": "user_email",
+  "bound_claims_type": "glob",
+  "bound_claims": {
+    "ref_protected": "true",
+    "ref_type": "branch",
+    "ref": "auto-deploy-*"
+  }
+}
+EOF
+```
+
+This example uses [bound_subject](https://www.vaultproject.io/api/auth/jwt#bound_subject) and [bound_claims](https://www.vaultproject.io/api/auth/jwt#bound_claims) to specify that only a JWT with matching values for these claims will be allowed to authenticate.
+
+Combined with GitLab's [protected branches](../../../user/project/protected_branches.md), you can restrict who is able to authenticate and read the secrets.
+
+[token_explicit_max_ttl](https://www.vaultproject.io/api/auth/jwt#token_explicit_max_ttl) specifies that the token issued by Vault, upon successful authentication, has a hard lifetime limit of 60 seconds.
+
+[user_claim](https://www.vaultproject.io/api/auth/jwt#user_claim) specifies the name for the Identity alias created by Vault upon a successful login.
+
+[bound_claims_type](https://www.vaultproject.io/api-docs/auth/jwt#bound_claims_type) configures the interpretation of the `bound_claims` values. If set to `glob`, the values will be interpreted as globs, with `*` matching any number of characters.
+
+For the full list of options, see Vault's [Create Role documentation](https://www.vaultproject.io/api/auth/jwt#create-role).
+
+Now, configure the JWT Authentication method:
+
+```shell
+$ vault write auth/jwt/config \
+    jwks_url="https://gitlab.example.com/oauth/discovery/keys" \
+    bound_issuer="gitlab.example.com"
+```
+
+[bound_issuer](https://www.vaultproject.io/api/auth/jwt#inlinecode-bound_issuer) specifies that only a JWT with the issuer (that is, the `iss` claim) set to `gitlab.example.com` can use this method to authenticate, and that the JWKS endpoint (`https://gitlab.example.com/oauth/discovery/keys`) should be used to validate the token.
+
+For the full list of available configuration options, see Vault's [API documentation](https://www.vaultproject.io/api/auth/jwt#configure).
+
+The following job, when run for the `master` branch, will be able to read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`:
+
+```yaml
+read_secrets:
+  script:
+    # Check job's ref name
+    - echo $CI_COMMIT_REF_NAME
+    # and is this ref protected
+    - echo $CI_COMMIT_REF_PROTECTED
+    # Vault's address can be provided here or as CI variable
+    - export VAULT_ADDR=http://vault.example.com:8200
+    # Authenticate and get token. Token expiry time and other properties can be configured
+    # when configuring JWT Auth - https://www.vaultproject.io/api/auth/jwt#parameters-1
+    - export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-staging jwt=$CI_JOB_JWT)"
+    # Now use the VAULT_TOKEN to read the secret and store it in an environment variable
+    - export PASSWORD="$(vault kv get -field=password secret/myproject/staging/db)"
+    # Use the secret
+    - echo $PASSWORD
+    # This will fail because the role myproject-staging can not read secrets from secret/myproject/production/*
+    - export PASSWORD="$(vault kv get -field=password secret/myproject/production/db)"
+```
+
+![read_secrets staging](img/vault-read-secrets-staging.png)
+
+The following job will be able to authenticate using the `myproject-production` role and read secrets under `/secret/myproject/production/`:
+
+```yaml
+read_secrets:
+  script:
+    # Check job's ref name
+    - echo $CI_COMMIT_REF_NAME
+    # and is this ref protected
+    - echo $CI_COMMIT_REF_PROTECTED
+    # Vault's address can be provided here or as CI variable
+    - export VAULT_ADDR=http://vault.example.com:8200
+    # Authenticate and get token. Token expiry time and other properties can be configured
+    # when configuring JWT Auth - https://www.vaultproject.io/api/auth/jwt#parameters-1
+    - export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-production jwt=$CI_JOB_JWT)"
+    # Now use the VAULT_TOKEN to read the secret and store it in environment variable
+    - export PASSWORD="$(vault kv get -field=password secret/myproject/production/db)"
+    # Use the secret
+    - echo $PASSWORD
+```
+
+![read_secrets production](img/vault-read-secrets-production.png)

doc/ci/variables/predefined_variables.md

@@ -62,6 +62,7 @@ future GitLab releases.**
 | `CI_JOB_NAME`                                 | 9.0    | 0.5    | The name of the job as defined in `.gitlab-ci.yml`                                                                                                                                                                                                                                                                                                         |
 | `CI_JOB_STAGE`                                | 9.0    | 0.5    | The name of the stage as defined in `.gitlab-ci.yml`                                                                                                                                                                                                                                                                                                       |
 | `CI_JOB_TOKEN`                                | 9.0    | 1.2    | Token used for authenticating with the [GitLab Container Registry](../../user/packages/container_registry/index.md) and downloading [dependent repositories](../../user/project/new_ci_build_permissions_model.md#dependent-repositories)                                                                                                                                                                                                              |
+| `CI_JOB_JWT`                                  | 12.10  | all    | RS256 JSON web token that can be used for authenticating with third party systems that support JWT authentication, for example [HashiCorp's Vault](../examples/authenticating-with-hashicorp-vault). |
 | `CI_JOB_URL`                                  | 11.1   | 0.5    | Job details URL                                                                                                                                                                                                                                                                                                                                            |
 | `CI_MERGE_REQUEST_ASSIGNEES`                  | 11.9   | all    | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                              |
 | `CI_MERGE_REQUEST_CHANGED_PAGE_PATHS`         | 12.9   | all    | Comma-separated list of paths of changed pages in a deployed [Review App](../review_apps/index.md) for a [Merge Request](../merge_request_pipelines/index.md). A [Route Map](../review_apps/index.md#route-maps) must be configured.                                                                                 |