Proposal: Custom Claims Support for ID Tokens (e.g., for AWS STS Session Tags)
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 Stefan Kürzeder