Credential delivery

Enhanced Advanced

Credential delivery is the component part of an integration definition that describes how a credential reaches running content. It is independent of the authentication type, which describes whose identity the credential represents.

A single integration definition in Posit Connect uses exactly one of the five mechanisms below. The template and authentication type of the definition determine which one.

Credential delivery mechanisms.
Mechanism	Content receives	Used by
Token exchange	An OAuth access token	Most Viewer and Service Account integrations
AWS Security Token Service (STS) credentials	Temporary AWS access key, secret, and session token	AWS Viewer and Service Account
Ephemeral Connect API key	A short-lived Connect API key	Connect API
Environment variable	A static secret	Anthropic, OpenAI, Hashicorp Vault
Workload identity token file	A credential file that its software development kit (SDK) reads on its own	AWS, Azure, Databricks, and Google Cloud Workload Identity

The first three deliver credentials on demand through the credential exchange endpoint, which content calls itself. The last two require nothing of the content: Connect prepares the credential before the process starts and refreshes it while the process runs.

Token exchange

Viewer and Service Account integrations, other than AWS and Connect API, use token exchange. Content presents a subject token to the credential exchange endpoint and receives an OAuth access token for the external provider.

Connect never delivers refresh tokens to content. Connect stores the refresh token for Viewer integrations and refreshes the access token on behalf of the content. Service Account integrations request a fresh access token on every exchange and store nothing.

See Integrations security for the request and response shape, and the User Guide for publisher-facing examples.

AWS STS credentials

AWS Viewer and Service Account integrations deliver temporary AWS credentials produced by AWS STS rather than an OAuth access token: an access key ID, a secret access key, a session token, and an expiration. Content requests them through the credential exchange endpoint using the urn:ietf:params:aws:token-type:credentials requested token type. Connect assumes the configured Identity and Access Management (IAM) role and returns the result.

AWS Workload Identity integrations use the workload identity token file mechanism instead. Connect does not assume the role; the AWS SDK does.

Content never receives the OpenID Connect (OIDC) tokens used in the exchange.

Credentials are valid for the session_duration configured on the integration, bounded by the maximum session duration of the IAM role. One hour is the common default. Connect does not cache them: each exchange performs a fresh role assumption, so content can request credentials again as expiry approaches. Content must handle expiration, because Connect does not renew credentials in place.

Important

Service Account integrations require the AWS STS service to reach the /.well-known/openid-configuration and /openid/v1/jwks routes on the Connect server over the public internet. Work with your network administrator to make these two routes reachable. You do not need to expose any other Connect route.

Content session tokens expire 24 hours after issuance. Content that runs longer than that must read the refreshed token from the path in the CONNECT_CONTENT_SESSION_TOKEN_FILE environment variable rather than caching the value of that variable. The Applications.ContentSessionTokenRefreshInterval setting controls the refresh interval.

See the AWS integration page for the IAM configuration each authentication type requires.

Ephemeral Connect API key

Some integrations deliver a short-lived API key for the Connect Server API rather than a third-party credential. An ephemeral key differs from a user-created API key in three ways:

Bound to a job: the key belongs to the content process it was created for.
Reaped with the process: when the content process exits, Connect deletes every ephemeral key for that job.
Scoped to a user: the key carries the user ID and role of a real Connect user, so it grants exactly that user’s access and no more.

The API key management endpoints never return ephemeral keys, and the keys never appear in the API key list in the dashboard.

The Connect API integration uses this mechanism to give content a key that acts as the viewer. The role of the key is the lower of the role of the viewer and the max_role configured on the integration. Set max_role as restrictively as the content allows: it caps every key the integration issues, even when an administrator is the one using the content. See Connect API.

Because the key belongs to the content job, it stops working when the content process restarts. Publishers must refresh the client from the current user session token rather than caching the key. See Obtaining a visitor API key.

Environment variables

The simplest mechanism sets one or more environment variables when content starts. The Anthropic and OpenAI integrations use it for a stored secret: Connect keeps the API key encrypted in the integration configuration and sets ANTHROPIC_API_KEY or OPENAI_API_KEY, which the official SDKs read automatically. Content receives the real secret.

For a stored secret, this mechanism offers none of the guarantees of an OAuth flow: the credential is long-lived and it is the same for every viewer. What it does offer is central management. An administrator can rotate the credential in one place without redeploying any content. Access control lists govern which publishers can attach it, and Connect records which content uses it.

The Hashicorp Vault integration also delivers through an environment variable, but the value is not a stored secret. Connect authenticates to Vault on the content’s behalf and sets VAULT_TOKEN to the resulting short-lived Vault client token, so content can use any Vault client library without integration-specific code. See Hashicorp Vault.

Workload identity token file

The Workload Identity integrations for AWS, Azure, Databricks, and Google Cloud deliver their credential as a file rather than through the credential exchange endpoint. Connect obtains a short-lived identity token for the content, writes it where the provider SDK expects to find it, points the SDK at that location with environment variables, and refreshes the file for the life of the content process. The SDK exchanges the token for a provider credential on its own.

What Connect writes for each Workload Identity integration.
Integration	Connect writes	SDK reads
AWS	An identity token file	`AWS_WEB_IDENTITY_TOKEN_FILE`, `AWS_ROLE_ARN`, `AWS_DEFAULT_REGION`
Azure	A federated token file	`AZURE_FEDERATED_TOKEN_FILE`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`
Databricks	An identity token file	`DATABRICKS_OIDC_TOKEN_FILEPATH`, `DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`
Google Cloud	A credential configuration file and a token file	`GOOGLE_APPLICATION_CREDENTIALS`

Content calls nothing and stores nothing. Because Connect refreshes the token file in place, long-running content keeps working without handling expiration itself. Connect also sets a CONNECT_*_INTEGRATION_GUID variable for each of these integrations; those are read by Connect’s own session supervisor, not by your content.

The remaining Workload Identity integrations do not use a token file. For Hashicorp Vault and Posit Package Manager, Connect completes the exchange itself: Vault delivers the result as VAULT_TOKEN, and Package Manager writes a .netrc entry for the Package Manager host. A Custom integration using Workload Identity leaves the exchange to the content, which requests an identity token from the credential exchange endpoint and presents it to the provider itself.