Dynamic Claims for OIDC ID Token and JWT-SVID Token Credential Providers

Dynamic claims in the OIDC ID Token Credential Provider and JWT-SVID Token Credential Provider allow you to extract and use claims from an OIDC token in the credential data. This feature creates personalized and context-aware credentials that reflect the workload’s identity and attributes from their original OIDC token.

This functionality proves particularly useful in environments where OIDC tokens authenticate and authorize workloads, such as in cloud-native applications, CI/CD pipelines, or microservices architectures.

How dynamic claims work

Dynamic claims operate with two main components:

1. Template Definition - Define dynamic values in Credential Provider configuration using expressions instead of static values
2. Runtime Resolution - Aembit collects the referenced information and replaces template variables with actual values

The process follows these steps:

1. You configure template expressions in your OIDC ID Token or JWT-SVID Token Credential Provider
2. When a workload makes a credential request, Aembit receives the incoming OIDC token
3. Aembit extracts the specified claims from the token using your template expressions
4. Aembit inserts the extracted values into the generated credential

Dynamic claims syntax

Both the OIDC ID Token and JWT-SVID Token Credential Providers support dynamic claims using this syntax: ${expression}

Basic syntax patterns

• OIDC Token Claims: ${oidc.identityToken.decode.payload.claim_name}
• GitLab Token Claims: ${gitlab.identityToken.decode.payload.claim_name}
• GitHub Token Claims: ${github.identityToken.decode.payload.claim_name}
• Environment Variables: ${os.environment.VARIABLE_NAME}
• Combined Values: ${oidc.identityToken.decode.payload.user_login}_suffix

Common expression examples

Expression	Description	Example Result
${oidc.identityToken.decode.payload.user_email}	Extract workload email from OIDC token	workload@company.com
${oidc.identityToken.decode.payload.user_login}	Extract workload login/username	ci-workload
${oidc.identityToken.decode.payload.groups}	Extract workload groups	developers,admins
${gitlab.identityToken.decode.payload.project_path}	Extract GitLab project path	group/project
${gitlab.identityToken.decode.payload.ref}	Extract GitLab branch/tag reference	main
${gitlab.identityToken.decode.payload.job_id}	Extract GitLab CI job ID	123456789
${github.identityToken.decode.payload.actor}	Extract GitHub workflow actor	octocat
${github.identityToken.decode.payload.repository}	Extract GitHub repository	owner/repo
${github.identityToken.decode.payload.workflow}	Extract GitHub workflow name	ci.yml
${os.environment.K8S_POD_NAME}	Environment variable	my-app-pod-12345
${oidc.identityToken.decode.payload.user_login}_dynamic	Combined value	ci-workload_dynamic

Configuration examples

OIDC ID Token Credential Provider

Configure dynamic claims in an OIDC ID Token Credential Provider as follows:

Subject field

${oidc.identityToken.decode.payload.user_login}

Custom claims

• Claim Name: workload_email

• Value: ${oidc.identityToken.decode.payload.user_email}_verified

• Claim Name: dynamic_role

• Value: ${oidc.identityToken.decode.payload.role}

JWT-SVID Token Credential Provider

Configure dynamic claims in a JWT-SVID Token Credential Provider for SPIFFE-compliant tokens:

Subject field (SPIFFE ID)

spiffe://your-domain/ns/${oidc.identityToken.decode.payload.namespace}/sa/${oidc.identityToken.decode.payload.service_account}

Custom claims

• Claim Name: namespace

• Value: ${oidc.identityToken.decode.payload.namespace}

• Claim Name: cluster

• Value: ${os.environment.CLUSTER_NAME}

Step-by-step example

This example demonstrates extracting GitLab workload information from an OIDC token and using it in generated credentials.

1. Create an OIDC ID Token Credential Provider with dynamic claims:

   • Subject: ${oidc.identityToken.decode.payload.user_login}test_dynamic
   • Custom Claim: dynamic_claim1 = ${oidc.identityToken.decode.payload.user_email}_email

2. Create supporting Aembit components:

   • Access Policy linking your workload to the credential provider
   • Client Workload representing your OIDC token source (for example, GitLab CI job)
   • Server Workload representing your target service

3. Make a credential request using your OIDC token

4. Verify the result - the generated credential contains:

   • Subject: ci-workload_test_dynamic (if user_login was ci-workload)
   • dynamic_claim1: ci.workload@company.com_email (if user_email was ci.workload@company.com)

Supported claim sources

The following sections describe the supported claim sources and how to use them in dynamic claims.

OIDC token claims

Extract any claim from the incoming OIDC token’s payload:

${oidc.identityToken.decode.payload.<CLAIM_NAME>}

Common GitLab CI OIDC claims

• user_login - GitLab username
• user_email - Workload’s email address
• project_path - Full project path
• ref - Git branch or tag reference
• job_id - CI job identifier

Common GitHub Actions OIDC claims

• actor - GitHub username who triggered the workflow
• repository - Repository name in format owner/repo
• ref - Git reference (branch/tag)
• workflow - Workflow filename

Common Jenkins OIDC claims

• sub - Subject claim (by default, the URL of the Jenkins job)

• iss - Jenkins instance issuer URL

• aud - Audience claim (configurable)

• `Build number (included by default)

• Custom claims - Jenkins allows administrators to configure additional claims through “Claim templates” using build variables such as:

  • ${JOB_NAME} - Name of the Jenkins job
  • ${BUILD_NUMBER} - Build number for the job run
  • ${NODE_NAME} - Jenkins node where the job ran
  • ${BUILD_USER} - Username that triggered the build (if available)
  • ${BRANCH_NAME} - Git branch name (if applicable)
  • Any other Jenkins environment variables

  Note

  Unlike GitLab and GitHub which have standardized claim names, Jenkins OIDC claims are highly customizable and depend on your configuration.

Environment variables

Access environment variables from the execution context:

${os.environment.VARIABLE_NAME}

Common examples:

• ${os.environment.K8S_POD_NAME} - Kubernetes pod name
• ${os.environment.CLIENT_WORKLOAD_ID} - Aembit client workload identifier

Best practices

The following best practices help you use dynamic claims in both OIDC ID Token and JWT-SVID Token Credential Providers:

Security considerations

• Validate input claims - Ensure the OIDC token contains the expected claims before extraction
• Limit scope - Only extract necessary claims to minimize exposure
• Review generated credentials - Use tools like jwt.io to decode and verify generated tokens
• SPIFFE compliance - For JWT-SVID tokens, ensure dynamic SPIFFE IDs follow the spiffe:// format

Template design

• Use descriptive names - Make custom claim names clear and meaningful
• Combine thoughtfully - When combining values, ensure the result remains valid for your target service
• Test thoroughly - Verify dynamic claims work correctly with your specific OIDC token structure

Troubleshooting

• Missing claims - If a referenced claim doesn’t exist in the source OIDC token, the expression may result in an empty value
• Token format - Ensure your OIDC token follows proper formatting and contains the expected payload structure
• Permissions - Verify your OIDC provider includes the necessary claims in the token

Related docs

• Create an OIDC ID Token Credential Provider
• About the OIDC ID Token Credential Provider
• Create a JWT-SVID Token Credential Provider
• About the JWT-SVID Token Credential Provider
• Vault Dynamic Claims (for Vault-specific dynamic claims)