oidc

The oidc provider mints a short-lived OpenID Connect (OIDC) token for an audience you choose. You can exchange the token with any service that federates OIDC identities, such as Anthropic, Cloudsmith, JFrog Artifactory, or Aembit. For the steps to configure a service to trust these tokens, see Configure a relying party for custom-audience OIDC tokens.

The vendor login providers, such as aws-login, exchange their token for you and return that vendor’s credentials. fn::open::oidc returns the signed token itself, so your own code or tool does the exchange.

Examples

Mint a token

Set audience to the value the relying party expects in the token’s aud claim. Set identityToken.version to v2:

values:
  registry:
    login:
      fn::open::oidc:
        audience: https://registry.example.com
        identityToken:
          version: v2

The provider returns the token as a secret string, so you reference it as ${registry.login}.

Set a shorter lifetime

Tokens live for one hour by default. Use duration to ask for a shorter lifetime, from 1m to 1h:

values:
  registry:
    login:
      fn::open::oidc:
        audience: https://registry.example.com
        duration: 15m
        identityToken:
          version: v2

The relying party applies its own clock-skew allowance, so it may accept a token for a few minutes after exp. The relying party, not duration, sets the lifetime of the credential you exchange the token for.

Pass the token to a command

Export the token as an environment variable, then run your tool with pulumi env run:

values:
  registry:
    login:
      fn::open::oidc:
        audience: https://registry.example.com
        identityToken:
          version: v2
  environmentVariables:
    REGISTRY_OIDC_TOKEN: ${registry.login}

Write $REGISTRY_OIDC_TOKEN, not ${REGISTRY_OIDC_TOKEN}, inside a command you pass to pulumi env run. The CLI expands ${NAME} itself before the command runs, so the shell gets an empty value.

If a tool reads the token from a file, use the files reserved property instead. pulumi env run writes the token to a temporary file and sets the named variable to that file’s path:

values:
  registry:
    login:
      fn::open::oidc:
        audience: https://registry.example.com
        identityToken:
          version: v2
  files:
    REGISTRY_OIDC_TOKEN_FILE: ${registry.login}

Define the token once and import it

The token’s subject (sub) names the environment that declares the fn::open::oidc block, not the environment you open. Define the block in one environment and import it where you need the token. Every importing environment then gets a token with the same subject, and the relying party trusts one subject.

# myorg/registry/login
values:
  registry:
    login:
      fn::open::oidc:
        audience: https://registry.example.com
        identityToken:
          version: v2

# myorg/myapp/dev
imports:
  - registry/login

values:
  environmentVariables:
    REGISTRY_OIDC_TOKEN: ${registry.login}

Token contents

fn::open::oidc signs its tokens with a separate issuer, https://api.pulumi.com/oidc/v2. The subject has the form pulumi:org:<org-id>:env:<environment-id> and uses the IDs of the organization and the declaring environment. For the full claim list and the steps to trust the token, see Configure a relying party for custom-audience OIDC tokens.

To see the claims before you mint a token, use debug-oidc-claims with the same inputs.

Each token that fn::open::oidc mints adds an entry to your organization’s audit log. The entry records the subject, audience, environment, and lifetime of the token. Its event name is environment-oidc-token-issued.

Schema reference

Inputs

identityToken.version has no default so that a later token format can ship without changing the tokens an existing environment mints or the trust policies that pin them.

The provider refuses any other input, including subjectAttributes. The subject of a fn::open::oidc token is always built from the organization ID and the ID of the environment that declares it.

Outputs

The provider returns one value: the signed token, as a secret string. It has no properties, so reference the block itself, for example ${registry.login}.

Configuring OIDC

To configure a service to trust these tokens, see Configure a relying party for custom-audience OIDC tokens.

Troubleshooting

Pulumi checks the inputs against the schema when you save the environment, and runs the provider’s own checks when you open it. Some errors below appear at save, in the console editor or from esc env edit, and others only at open.

Environment not saved

Symptom: opening fails with fn::open::oidc cannot run in an unsaved environment document; save the environment and import it.

Cause: the token’s subject uses the environment’s ID, and an unsaved environment document has no ID yet.

Fix: save the environment that declares the block, then open it, or open another environment that imports it.

Input refused

Symptom: saving fails with missing required properties: audience, expected a string of at most length 255, or expected "v2". Opening fails with fn::open::oidc does not accept subjectAttributes: a v2 token's subject is always the environment's ID, fn::open::oidc does not accept an input named "<name>", or audience must not be blank.

Cause: fn::open::oidc accepts only audience, identityToken.version, and duration, and the audience must be 1 to 255 bytes and not blank. The vendor login providers accept subjectAttributes, but this provider does not.

Fix: add the missing input, or remove the refused one. To restrict which environments the relying party trusts, match the exact sub claim instead.

Duration out of range

Symptom: saving fails with string must match the pattern "^([0-9]+h)?([0-9]+m)?([0-9]+s)?$", or opening fails with duration must be between 1m0s and 1h0m0s.

Fix: write duration as hours, minutes, and seconds, such as 15m or 1h, from 1m to 1h, or remove it to use the one-hour default.

Relying party rejects the token

Symptom: the service you exchange the token with rejects it.

Cause: usually the service trusts the vendor login issuer, https://api.pulumi.com/oidc, or expects a different aud or sub.

Fix: preview the claims with debug-oidc-claims and compare iss, aud, and sub with the service’s configuration. The issuer must be https://api.pulumi.com/oidc/v2.