Jenkins

Jenkins can publish without a stored secret. The OpenID Connect Provider plugin gives each job an identity token. Telesphorepo trades it for a publish session.

Set up

1. Install the OpenID Connect Provider plugin in Jenkins.
2. In Jenkins, add a credential of the kind “OpenID Connect id token”. Set its audience to the URL of your Telesphorepo server, for example https://repo.acme.com. Give it the ID telesphorepo-oidc.
3. An admin opens the Trust policies page and picks the Jenkins preset. The issuer is the Jenkins URL followed by /oidc, for example https://jenkins.acme.com/oidc.
4. Add at least one claim that limits which jobs may publish. List the repositories that the policy may publish to.
5. Leave the audience empty, or set it to the same text as in the Jenkins credential. Empty means the base_url of the server.

See Trust policies for all fields.

Publish with curl

Jenkinsfile

withCredentials([string(credentialsId: 'telesphorepo-oidc', variable: 'OIDC')]) {
  sh '''
    SESSION=$(curl -sSf https://repo.acme.com/api/publish/sessions/oidc \
      -H 'Content-Type: application/json' \
      -d "{\\"token\\":\\"$OIDC\\",\\"repo\\":\\"releases\\"}")
    TOKEN=$(echo "$SESSION" | jq -r .token)
    curl -sSf -u "ci:$TOKEN" -T app-1.0.jar \
      https://repo.acme.com/maven/releases/com/acme/app/1.0/app-1.0.jar
    curl -sSf -X DELETE -u "ci:$TOKEN" \
      "https://repo.acme.com/api/publish/sessions/$(echo "$SESSION" | jq -r .id)"
  '''
}

The agent needs curl and jq.

Publish with the plugin or extension

Both clients read the token from an environment variable.

1. In the Gradle settings, set oidcTokenEnv. See Gradle plugin.

   telesphorepo {
       url = "https://repo.acme.com"
       oidcTokenEnv = "OIDC"
   }

   For Maven, pass -Dtelesphorepo.oidcTokenEnv=OIDC. See Maven extension.

2. Run the build inside withCredentials, so that the variable is set:

   Jenkinsfile

   withCredentials([string(credentialsId: 'telesphorepo-oidc', variable: 'OIDC')]) {
     sh './gradlew publish'
   }

When the server cannot reach Jenkins

The server finds the signing keys of the issuer through discovery. If Jenkins is on a private network, the server cannot do this. Paste the keys into the trust policy instead.

1. Download the JWKS of Jenkins from the jwks_uri in <jenkins url>/oidc/.well-known/openid-configuration.
2. Paste the JSON into the JWKS field of the trust policy.
3. Save. The server checks the pasted keys when you save and uses them instead of discovery.

Update the pasted JWKS when Jenkins rotates its keys.

Gotchas

• The iss claim of the token must equal the issuer of the policy exactly. A different host name or a missing /oidc fails the match.
• The aud claim must equal the audience of the policy. A mismatch fails the exchange.
• The server accepts each token once and only if it is at most 10 minutes old. Use a fresh token for each exchange.
• The server accepts RS, ES and PS signatures (256, 384, 512 bits) and EdDSA.
• If you edit or disable a policy, the server ends its open sessions.