Skip to main content

Customizing SPIFFE IDs for CI/CD

If your OIDC provider supports custom claims, these can be used to customize the SPIFFE IDs for your CI/CD cluster.

As an example use case for customizing the SPIFFE ID, you may want to pass along build information from GitHub, such as the repository and workflow run ID. SPIRL allows for this information to be used in the SPIFFE ID path template, to produce a SPIFFE ID like the following:

spiffe://spirl.example.com/cicd-cluster/repo/example-org/repo-name/run/30433642

GitHub​

SPIRL's default GitHub profile already recognizes the claims supported by GitHub's OIDC provider. In this example, we will use the Github-provided repo and run_id claims.

To produce the SPIFFE ID mentioned above, pass a custom path template to the --path-template flag. Note that the custom claims must be prefixed with jwt. in the path template.

spirlctl ci-cd cluster add production --trust-domain spirl.example.com \
   --platform k8s --profile github.com \
   --path-template /{{cluster.name}}/repo/{{jwt.repo}}/sha/{{jwt.run_id}}
note

The value passed to the --path-template flag replaces the default path template. If you wish to keep any elements from the default SPIFFE ID path template, these must be included in the new path template passed in via the flag. In the previous example, we include the cluster name via {{cluster.name}}.

Use spirlctl to view the supported claims in the default GitHub profile:

$ spirlctl ci-cd profile info github.com
ID:
Name:                        github.com
Type:                        Github SaaS
Issuer:                      https://token.actions.githubusercontent.com
Claims:                      exp, iat, jti, nbf, sha, repository_id, repository_owner, repository_owner_id, enterprise, enterprise_id, run_id, run_number, run_attempt, actor, actor_id, workflow, workflow_ref, workflow_sha, head_ref, base_ref, event_name, ref_type, ref_protected, environment, environment_node_id, job_workflow_sha, repository_visibility, runner_environment, issuer_scope

Gitlab​

Similarly, SPIRL already supports claims provided by Gitlab's ID tokens. To produce a SPIFFE ID similar to to the one described above, pass the following value to the --path-template flag. Note that the custom claims must be prefixed with jwt. in the path template.

spirlctl ci-cd cluster add production --trust-domain spirl.example.com \
   --platform k8s --profile gitlab.com \
   --path-template /{{cluster.name}}/repo/{{jwt.project_path}}/job/{{jwt.job_id}}

Use spirlctl to view the supported claims in the default Gitlab profile:

$ spirlctl ci-cd profile info gitlab.com
ID:
Name:                        gitlab.com
Type:                        Gitlab SaaS
Issuer:                      https://gitlab.com
Claims:                      exp, nbf, iat, jti, namespace_id, namespace_path, project_id, user_id, user_login, user_email, user_access_level, pipeline_id, pipeline_source, job_id, ref, ref_type, ref_protected, environment, environment_protected, deployment_tier, environment_action, runner_id, runner_environment, sha, ci_config_sha, project_visibility

Jenkins​

When creating a Jenkins CI/CD profile as described in the Jenkins integration quick start, we passed the profile type of jenkins using the --type flag. The built-in Jenkins profile already supports the build_number claim that is added by the Jenkins OpenID Connect Provider plugin.

$ spirlctl ci-cd profile create jenkins --type jenkins --issuer=http://jenkins:8080/oidc
CI/CD Profile 'jenkins' created successfully
ID: cicdp-5wv7fuynbe
$ spirlctl ci-cd profile info jenkins
ID:                          cicdp-5wv7fuynbe
Name:                        jenkins
Type:                        Jenkins
Issuer:                      http://jenkins:8080/oidc
Claims:                      aud, exp, iat, sub, build_number
Created By:                  u-e2e67r71nf

The OIDC plugin supports the configuration of additional claims via a custom claim template. This custom template can include Jenkins environment variables, such as $JOB_NAME or $GIT_COMMIT. We will assume that these have been configured in the Jenkins OIDC plugin as job_name and git_commit.

To support additional claims, we first pass them to a new Jenkins profile using the --claims flag. Multiple claims are separated with a comma.

$ spirlctl ci-cd profile create jenkins_customized --type jenkins \
   --issuer=http://jenkins:8080/oidc \
   --claims job_name,git_commit
CI/CD Profile 'jenkins_customized' created successfully
ID: cicdp-2k5vqp17r8

When we inspect the new profile, we can see that these custom claims are supported:

$ spirlctl ci-cd profile info jenkins_customized
ID:                          cicdp-2k5vqp17r8
Name:                        jenkins_customized
Type:                        Jenkins
Issuer:                      http://jenkins:8080/oidc
Claims:                      aud, exp, iat, sub, build_number, job_name, git_commit
Created By:                  u-e2e67r71nf

At this point, we can use both job_name and git_commit in our custom SPIFFE IDs. But for the sake of our example, we will only use job_name and build_number. Note again that the custom claims must be prefixed with jwt. in the path template.

spirlctl ci-cd cluster add cicd-cluster \
   --trust-domain spirl.example.com --platform k8s --profile jenkins_customized \
   --path-template /{{cluster.name}}/job/{{jwt.job_name}}/build/{{jwt.build_number}}

Again, we'll assume a trust domain of spirl.example.com. Assuming a cluster name of cicd-cluster, job_name of webapp_staging and a build_number of 30433642, this would expand to:

spiffe://spirl.example.com/cicd-cluster/job/webapp_staging/build/30433642