Add an option to request session tags in the OIDC token

[yob]

Session tags are a more secure way for customers to define which tokens can assume an IAM role. Rather than use the error prone sub claim with colon separators, the trust policy of an IAM Role can target specific claims and the required values (like organization_slug, pipeline_slug, and build_branch.

Unfortunately any OIDC token with session tags needs an additional permission in the trust policy of the role they are assuming (sts:TagSession, see below). Automatically adding session tags would break role assuming for customers with existing roles and trust policies, so for now we default the option to blank and request no session tags.

Maybe in a v2.0.0 release we could invert the behaviour and default to a few commonly used session tags? I'd suggest

• organization_slug
• pipeline_slug
• build_branch

For now, users can opt in to session tags like so, using any valid claim from the Buildkite OIDC docs.

steps:
  - command: aws sts get-caller-identity
    plugins:
      - aws-assume-role-with-web-identity#v1.1.0:
          role-arn: arn:aws:iam::AWS-ACCOUNT-ID:role/SOME-ROLE
          session-tags:
          - organization_slug
          - pipeline_slug
          - build_branch

The resulting token duplicates the requested claims into a nested https://aws.amazon.com/tags claim:

{
  "iss": "https://agent.buildkite.com",
  "sub": "organization:example-org:pipeline:example-pipeline:ref:refs/heads/main:commit:cb9c1decb3b7c3c0fcd8a4368bb6a492e631b571:step:",
  "aud": "https://sts.amazonaws.com",
  "iat": 1739694861,
  "nbf": 1739694861,
  "exp": 1739695161,
  "organization_slug": "example-org",
  "pipeline_slug": "example-pipeline",
  "build_number": 2,
  "build_branch": "main",
  "build_tag": null,
  "build_commit": "cb9c1decb3b7c3c0fcd8a4368bb6a492e631b571",
  "step_key": null,
  "job_id": "01950de4-b414-4ef4-a604-6599c16ec9d9",
  "agent_id": "01950de4-bef7-4802-ad00-b509d14f66ab",
  "build_source": "ui",
  "runner_environment": "buildkite-hosted",
  "https://aws.amazon.com/tags": {
    "principal_tags": {
      "organization_slug": [
        "example-org"
      ],
      "pipeline_slug": [
        "example-pipeline"
      ],
      "build_branch": [
        "main"
      ]
    }
  }
}

Here's an example trust policy for a role that can only be assumed by main branch builds in the https://buildkite.com/example-org/example-pipeline pipeline

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::111111111111:oidc-provider/agent.buildkite.com"
            },
            "Action": [
                "sts:AssumeRoleWithWebIdentity",
                "sts:TagSession"
            ],
            "Condition": {
                "StringEquals": {
                    "agent.buildkite.com:aud": "sts.amazonaws.com"
                },
                "ForAnyValue:StringEquals": {
                    "aws:RequestTag/organization_slug": "example-org",
                    "aws:RequestTag/pipeline_slug": "example-pipeline",
                    "aws:RequestTag/build_branch": "main"
                }
            }
        }
    ]
}

Note the addition of the sts:TagSession action, which we previously haven't documented as required. Without this, any call to AssumeRoleWithWebIdentity with a token that has session tags will fail. These docs were useful in highlighting this requirement.

[yob]

Hmm. It would be good to mention that session tags are captured in cloudtrail logs too. Maybe with an example?

[wolfeidau]

@yob I think it would be good to demo using an org identifier as well, given org slug can be changed.

[yob]

@wolfeidau how's this?

[sj26]

Nice!

Would folks expect to be able to use arrays too? Doesn't have to be a right-now thing.

steps:
  - command: aws sts get-caller-identity
    plugins:
      - aws-assume-role-with-web-identity#v1.1.0:
          role-arn: arn:aws:iam::AWS-ACCOUNT-ID:role/SOME-ROLE
          session-tags:
            - organization_slug
            - pipeline_slug
            - build_branch

[sj26]

I was thinking we could add buildkite-agent oidc request-token ... --no-default-claims option if the claims became too big and heavy. Core JWT attributes would always stay, including sub, to identify where the token came from. But if you only care about a couple of session tags then the rest of our default claims might be noise.

[yob]

I was thinking we could add buildkite-agent oidc request-token ... --no-default-claims option if the claims became too big and heavy

I like it. Since making session tags the default behaviour is a breaking change, and that flag doesn't exist yet: maybe we can mull over ideas for a future v2 release that use session tags by default and has an option to disable the default claims if they're not needed. Or even, turn off the default claims and go all in on session tags 🤔

Would folks expect to be able to use arrays too? Doesn't have to be a right-now thing.

Hmm. The array syntax definitely reads nicer. I'll look into it!

[yob]

I've switched the syntax to accept claims for array instead of CSV string

[pzeballos]

Nice! I think is great that we'll ship this for now and work on a v2 with the breaking changes.