1.15.4.7 The IDToken credential manager

Vault

You can use JWTs to authenticate with HashiCorp Vault. This way your pipelines can directly communicate with Vault and use all of it's features, beyond what Concourse's native Vault-integration offers.

First enable the JWT auth method in your Vault Server:

vault auth enable jwt

Now configure the JWT auth method to accept JWTs issued by your Concourse:

vault write auth/jwt/config \
  oidc_discovery_url="https://<external_url_of_your_concourse>" \
  default_role="demo"

Lastly, configure a role for JWT auth. Make sure to use the same value in your pipeline that you used for bound_audiences (the best would be the URL of your Vault). bound_subject must be the sub-claim value of your JWT, if you use the subject_scope setting to change the contents of your sub-claim, adapt this accordingly!

vault write auth/jwt/role/demo \
role_type="jwt"\
user_claim="sub" \
bound_subject="main/your-pipeline" \
bound_audiences="my-vault-server.com" \
policies=webapps \
ttl=1h

This role will allow the holder of a JWT with aud: "my-vault-server.com" and sub: "main/your-pipeline" to get a Vault token with the Vault-policy webapps. If the policy you want to assign has a different name, simply change it in the above example. Make sure to adapt the value for bound_subject according to your team and pipeline name.

Pipelines can now do the following:

var_sources:
- name: vaulttoken
  type: idtoken
  config:
    audience: ["my-vault-server.com"]

jobs:
- name: vault-login
  plan:
  - task: login
    config:
      platform: linux
      image_resource:
        type: registry-image
        source: { repository: hashicorp/vault }
      run:
        path: sh
        args:
        - -e
        - -c
        - |
          export VAULT_ADDR=https://my-vault-server.com
          vault write auth/jwt/login \
            role=demo \
            jwt=((vaulttoken:token)) \
            --format=json > vault-response.json
          echo "Now do something with the token in vault-response.json"

You don't have to create a role and a policy for every single of your pipelines! You can use claims from the JWT with Vault's policy templating feature. This way you can define a policy that allows a pipeline read to all the secrets it would usually have access to using Concourse's native Vault-integration:

path "concourse/metadata/{{ identity.entity.aliases.<JWT_ACCESSOR>.metadata.team }}" {
  capabilities = ["list"]
}

path "concourse/data/{{ identity.entity.aliases.<JWT_ACCESSOR>.metadata.team }}/+" {
  capabilities = ["read"]
}

path "concourse/metadata/{{ identity.entity.aliases.<JWT_ACCESSOR>.metadata.team }}/{{ identity.entity.aliases.<JWT_ACCESSOR>.metadata.pipeline }}" {
  capabilities = ["list"]
}

path "concourse/metadata/{{ identity.entity.aliases.<JWT_ACCESSOR>.metadata.team }}/{{ identity.entity.aliases.<JWT_ACCESSOR>.metadata.pipeline }}/*" {
  capabilities = ["read", "list"]
}

path "concourse/data/{{ identity.entity.aliases.<JWT_ACCESSOR>.metadata.team }}/{{ identity.entity.aliases.<JWT_ACCESSOR>.metadata.pipeline }}/*" {
  capabilities = ["read", "list"]
}

With a policy like this you don't need to configure bound_subject in your JWT auth role. Every single pipeline can simply use the same role and the policy will take care that they can only access secrets meant for them. However you need to explicitly configure claim to metadata mapping:

vault write auth/jwt/role/demo \
  role_type="jwt"\
  user_claim="sub" \
  bound_subject= \
  bound_audiences="my-vault-server.com" \
  policies=pipeline-new \
  claim_mappings='team=team' \
  claim_mappings='pipeline=pipeline' \
  ttl=1h

AWS

AWS supports federation with external identity providers. Using this, you can allow identities managed by an external identity provider to perform actions in your AWS account.

In this scenario the external identity provider is Concourse and the identities are teams/pipelines/jobs. This means you are able to grant a specific pipeline or job permission to perform actions in AWS (like deploying something), all without managing IAM users or dealing with long-lived credentials.

First you need to create an OpenID Connect identity provider in your AWS Account. Set Provider URL to the external URL of your Concourse server. For Audience, you can choose any string you like, but using a value like sts.amazonaws.com is recommended. You have to use the same string later in the configuration of your idtoken var source.

Next you will need to create an IAM-Role that can be assumed using your JWT. Set Identity Provider to the value you previously set Audience to. Add a condition on the sub-claim with type StringEquals and value yourteam/yourpipeline. This will allow ONLY that specific pipeline (and any instanced versions of it) to assume that IAM Role using a JWT. If you use the subject_scope setting to change the contents of your sub-claim, adapt this condition accordingly! In the next step you will be able to choose which AWS permissions your role will get.

Now you can use the AWS AssumeRoleWithWebIdentity API operation to assume your role via a JWT issued by Concourse. The easiest way is to do this is via the assume-role-with-web-identity AWS CLI command:

var_sources:
- name: awstoken
  type: idtoken
  config:
    audience: ["sts.amazonaws.com"]

jobs:
- name: aws-login
  plan:
  - task: print
    config:
      platform: linux
      image_resource:
        type: registry-image
        source: { repository: amazon/aws-cli }
      run:
        path: bash
        args:
        - -e
        - -c
        - |
          aws sts assume-role-with-web-identity \
            --role-session-name Concourse \
            --role-arn arn:aws:iam::<your_account>:role/<your_role> \
            --web-identity-token ((awstoken:token)) > creds.json
          echo "Now do something with the temporary credentials in creds.json"

Azure

Azure also supports a way to grant the holder of a JWT permissions in the Cloud. This is done via a feature called Federated Credentials.

First, create an EntraID App Registration. This app registration will be the service principal used by your pipeline.

Now create a federated credential for the app registration you just created.

For Scenario select "Other". For Issuer set it to the external URL of your Concourse server. For Type select "Explicit subject identifier" and set Value to <teamname>/<pipelinename> of the pipeline that should be able to use the identity. If you use the subject_scope setting to change the contents of your sub-claim, change this setting here accordingly.

You can now assign IAM permissions to the identity of the app registration, which define what the identity is allowed to do in your Azure subscription.

Your pipeline can now use the az cli to login to Azure using a JWT generated by Concourse:

var_sources:
- name: azuretoken
  type: idtoken
  config:
    audience: ["api://AzureADTokenExchange"]

jobs:
- name: azure-deploy
  plan:
  - task: login
    config:
      platform: linux
      image_resource:
        type: registry-image
        source: { repository: mcr.microsoft.com/azure-cli }
      run:
        path: bash
        args:
        - -e
        - -c
        - |
          echo ((azuretoken:token))
          az login --service-principal \
            -u <client_id of your app registration> \
            --tenant <tenant_id of your app registration> \
            --federated-token ((azuretoken:token))
          echo "You are now authenticated with Azure. Do something with it!"