Proposal: Custom Claims Support for ID Tokens (e.g., for AWS STS Session Tags)

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Proposal

Introduce a feature enabling users to define custom claims for ID tokens generated by GitLab. Users can specify these claims using YAML format, facilitating the inclusion of additional metadata or context-specific information in the ID tokens. For example, users can define custom claims such as AWS STS session tags, incorporating details like project, environment, and pipeline ID.

Example .gitlab-ci.yml:

id_tokens:
  GITLAB_OIDC_TOKEN:
    aud: https://gitlab.com
    "https://aws.amazon.com/tags":
      principal_tags:
        "Project": ["$CI_PROJECT_PATH"]
        "Environment": ["$AWS_ENVIRONMENT_NAME"]
        "PipelineIID": ["$CI_PIPELINE_IID"]
      transitive_tag_keys: [
        "Project", 
        "Environment",
        "PipelineIID"
      ]

Example resulting (decoded) id token:

{
  "namespace_id": "72",
  "namespace_path": "my-group",
  "project_id": "20",
  "project_path": "my-group/my-project",
  "user_id": "1",
  "user_login": "sample-user",
  "user_email": "sample-user@example.com",
  "user_identities": [
      {"provider": "github", "extern_uid": "2435223452345"},
      {"provider": "bitbucket", "extern_uid": "john.smith"},
  ],
  "pipeline_id": "574",
  "pipeline_source": "push",
  "job_id": "302",
  "ref": "feature-branch-1",
  "ref_type": "branch",
  "ref_path": "refs/heads/feature-branch-1",
  "ref_protected": "false",
  "groups_direct": ["mygroup/mysubgroup", "myothergroup/myothersubgroup"],
  "environment": "test-environment2",
  "environment_protected": "false",
  "deployment_tier": "testing",
  "environment_action": "start",
  "runner_id": 1,
  "runner_environment": "self-hosted",
  "sha": "714a629c0b401fdce83e847fc9589983fc6f46bc",
  "project_visibility": "public",
  "ci_config_ref_uri": "gitlab.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main",
  "ci_config_sha": "714a629c0b401fdce83e847fc9589983fc6f46bc",
  "jti": "235b3a54-b797-45c7-ae9a-f72d7bc6ef5b",
  "iss": "https://gitlab.com",
  "iat": 1681395193,
  "nbf": 1681395188,
  "exp": 1681398793,
  "sub": "project_path:my-group/my-project:ref_type:branch:ref:feature-branch-1",
  "aud": "https://gitlab.com",
  "https://aws.amazon.com/tags": {
    "principal_tags": {
      "Project": ["my-group/my-project"],
      "Environment": ["staging"],
      "PipelineIID": ["574"]
    },
    "transitive_tag_keys": ["Project", "Environment", "PipelineIID"]
  }
}

This enhancement offers users greater flexibility in customizing ID tokens to suit their specific requirements, thereby enhancing interoperability with external services like AWS STS. (Reference: AWS STS Session Tags - Assume Role with web identity)

Edited by 🤖 GitLab Bot 🤖