Authenticating TeamCity Builds to External Services With OIDC

Static credentials in CI/CD environments are a significant source of security risks and operational overhead. They can be accidentally leaked through logs and build artifacts. And you can never be sure who’s copying, saving, or sharing them with others during the CI/CD setup process. In addition, they require regular rotation to meet security requirements.

That’s why many services, including major cloud providers, now support authentication with short-lived OIDC identity tokens, allowing CI/CD pipelines to authenticate without storing static credentials.

In this article, we will explain how OIDC authentication works and show how the new TeamCity OIDC JWT plugin enables your build configurations to authenticate securely to AWS, Google Cloud, and other services that support OIDC.

What is OIDC?

OpenID Connect (OIDC) is an authentication standard originally designed to verify user identities. However, many popular cloud providers and services, such as AWS and Google Cloud, use parts of the OIDC specification to authenticate workloads. This article focuses only on those parts.

The authentication flow starts when an identity provider (IdP) issues a cryptographically signed JSON Web Token (JWT) containing information about a workload. Each piece of information in the token is called a claim. Each token contains a validity period, an intended audience (the service or services the token was issued for), and an issuer URL. The issued token can then be presented to a third-party service (such as a cloud provider), which we will refer to as a token consumer.

When a token consumer receives a token, it uses the issuer URL to retrieve the metadata document ({issuer_url}/.well-known/openid-configuration). Among other information, this document includes a link to the issuer’s JSON Web Key Set (JWKS), which contains public keys used to verify token signatures. OIDC issuer URLs must use the https scheme, so the metadata document can only be served over HTTPS. Some consumers also support validation against a preconfigured set of keys instead, in which case the issuer does not need to serve the metadata document over the internet.

After retrieving the public keys, the consumer verifies the token signature against them. If the signature is valid, the consumer checks whether the token was issued for an expected audience and is currently valid (not expired). The validated token’s claims are then used by the consumer to authenticate the workload.

Some consumers accept IdP tokens directly. Others perform a token exchange and return service-specific temporary credentials for workloads to use.

To enable this authentication method for TeamCity builds, the server needs to act as an identity provider and issue tokens for them.

Introducing the TeamCity OIDC JWT Plugin

The new OIDC JWT plugin adds IdP capabilities required to issue tokens for third-party services that support OIDC, such as AWS and Google Cloud.

The tokens are signed using algorithms based on RSA or ECDSA. Signing keys can be rotated either from the web UI or with an authorized request to an HTTP endpoint. By default, key rotation does not affect running builds or invalidate previously issued tokens.

For publicly accessible TeamCity instances, the plugin provides the .well-known/openid-configuration document and a JWKS with the issuer’s public keys. It also features a configurable issuer URL for instances that are not accessible from the internet, allowing you to host these documents on a public HTTPS host without exposing the TeamCity instance itself.

Finally, the plugin provides an API that allows other plugins to add new ways to sign tokens. By implementing a simple interface, plugin authors can add support for external hardware security modules (HSMs) or other key management services, such as Google Cloud KMS.

Getting started

To use the plugin, install it from JetBrains Marketplace. The plugin requires Java 17 and supports TeamCity 2025.11 and later versions.

The installed and enabled plugin can be configured via Admin | Integrations | OIDC Tokens. You can set the issuer URL (for instances inaccessible from the internet), configure signing settings, and manage signing keys.

Configuration changes may disrupt existing integrations. We recommend configuring the plugin before you set up OIDC for your builds. Once the plugin is configured, you can add build features that provide OIDC tokens.

The OIDC Token (in build parameters) build feature is the easiest way to issue a token. It generates a token at the start of the build and stores it in the specified build parameter. The lifetime of the token is configurable. By default, it equals the build timeout or 10 minutes if no timeout is specified.

The feature allows you to issue a token for one or more audiences. When different services require separate single-audience tokens, add a separate build feature for each token.

With long-running builds, tokens issued at the start of a build may remain valid for longer than necessary. For such builds, there is the OIDC Token (on demand via HTTP request) build feature. It allows build scripts to obtain short-lived tokens during the build with an HTTP request. The lifetime of issued tokens is always 5 minutes and cannot be changed.

The build can then present the issued token directly to the target service or use it as part of that service’s authentication flow.

The correct audience and token lifetime depend on the service you are integrating with. Consult the service’s official documentation for instructions on setting up OIDC authentication. You can also follow the setup guides we have for AWS and Google Cloud.

Learn more

Visit the plugin’s JetBrains Marketplace page for more information:

👉Check out the plugin👈

You can also explore the plugin’s GitHub repository, which contains the source code, an example JWT payload, and detailed usage documentation.