Integrations security
This section provides additional details about the Posit Connect integrations feature, focusing on the security implications of its design and operation.
Credential exchange
The Connect Server API endpoint that provides credentials to requesting content implements RFC8693. This token exchange service specification lays out strict semantics for interacting with this endpoint and facilitates well-defined interactions that must meet certain security-related criteria to succeed.
Request
Following RFC8693, a valid request to the credential exchange endpoint must include the following parameters:
grant_typemust beurn:ietf:params:oauth:grant-type:token-exchange.- For content credential exchanges,
subject_token_typemust be eitherurn:posit:connect:user-session-tokenurn:posit:connect:content-session-token
subject_tokenmust be a valid instantiation of the submittedsubject_token_type.requested_token_typeis optional but, when set, must be one of the following values:urn:ietf:params:oauth:token-type:access_tokenurn:ietf:params:oauth:token-type:jwturn:ietf:params:oauth:token-type:id_tokenurn:ietf:params:aws:token-type:credentialsurn:posit:connect:api-key- If omitted, Connect initially uses
access_token. Whenaudienceidentifies an integration, Connect replaces that value with the integration’s default.
Workload Identity requests must set requested_token_type to urn:ietf:params:oauth:token-type:id_token. Connect also accepts the legacy urn:ietf:params:oauth:token-type:jwt value for compatibility.
The expected subject_token_type depends on the authentication type of the integration being used.
| Integration Auth Type | Subject Token Type |
|---|---|
| Viewer | urn:posit:connect:user-session-token |
| Service Account | urn:posit:connect:content-session-token |
| Workload Identity | urn:posit:connect:content-session-token |
| Visitor API Key | urn:posit:connect:user-session-token |
The expected requested_token_type depends on the type of the integration being used.
| Integration Type | Requested Token Type |
|---|---|
| Workload Identity | urn:ietf:params:oauth:token-type:id_token |
| AWS Viewer or Service Account | urn:ietf:params:aws:token-type:credentials |
| Connect API | urn:posit:connect:api-key |
| All others | urn:ietf:params:oauth:token-type:access_token |
Subject tokens
Connect signs user session tokens with an ephemeral secret. The executing content process controls this secret’s life cycle. Connect manages a server signing key and uses it to sign content session tokens, including tokens used for Workload Identity. The credential exchange endpoint resolves the public key for the content session token from its kid claim. A client requesting a credential exchange must acquire the subject token from content while the content process is active or recently executed.
Across all subject tokens accepted by the credentials exchange endpoint, the following design properties hold which help to prevent misuse:
The user requesting the token exchange must have owner permissions on the content item.
The
subject_tokenmust have been issued by the server that is receiving the credential request.The
subject_tokenmust have been produced within the past 24 hours.
User session token
A urn:posit:connect:user-session-token is a signed JSON Web Token (JWT) with the following claims:
| Name | Description |
|---|---|
Iss |
Address of the Connect server that issued the subject_token. |
Sub |
GUID identifying the content viewer. |
Job |
Identifies the underlying content process for which the subject token can be used. |
App |
App ID of the accessed content. Connect uses this value to verify that both the authenticated user who is requesting a viewer’s OAuth access token and the content viewer have permission to receive the OAuth access token. |
Iat |
Unix timestamp indicating when the subject_token was issued by the Connect server. |
Exp |
Unix timestamp indicating when the subject_token expires. Connect sets the expiration to be 24 hours from the time the token was issued. |
The design of the urn:posit:connect:user-session-token maintains the following additional properties which help to prevent misuse:
The viewer must have recently interacted with the content which is requesting their OAuth access token.
The viewer must have permission to view the content item.
Content session token
A urn:posit:connect:content-session-token is a signed JSON Web Token (JWT) with the following claims:
| Name | Description |
|---|---|
Iss |
Address of the Connect server that issued the subject_token. |
Sub |
GUID identifying the content item. Must be internally consistent with the App claim. |
Job |
Identifies the underlying content process for which the subject token can be used. |
App |
App ID of the accessed content. Connect uses this value to verify that the authenticated user who is requesting a service account OAuth access token has permission to receive it. |
Iat |
Unix timestamp indicating when the subject_token was issued by the Connect server. |
Exp |
Unix timestamp indicating when the subject_token expires. For the token in the CONNECT_CONTENT_SESSION_TOKEN environment variable, Connect sets the expiration to be 24 hours from the time the token was issued. When Applications.ContentSessionTokenRefreshInterval is set, Connect periodically writes a fresh token to the file at the path in the CONNECT_CONTENT_SESSION_TOKEN_FILE environment variable. Each token in that file expires one refresh interval after it was issued, when Connect writes the next token. |
Response
Following RFC8693, if the credential exchange is successful, the response will include an appropriate access_token value based on the requested_token_type:
urn:ietf:params:oauth:token-type:access_token- Returns an OAuth access token
urn:ietf:params:oauth:token-type:id_tokenor the legacyurn:ietf:params:oauth:token-type:jwt- For a Connect token source, returns a Connect-signed JWT in
access_tokenfor Workload Identity. Theissued_token_typevalue isurn:ietf:params:oauth:token-type:id_token. - For an external token source, returns the provider’s
access_tokenvalue inaccess_token. Theissued_token_typevalue isurn:ietf:params:oauth:token-type:access_token.
- For a Connect token source, returns a Connect-signed JWT in
urn:ietf:params:aws:token-type:credentials- Returns base64-encoded, serialized, AWS credentials (access key ID, secret access key, session token, and expiration)
- This must be decoded and deserialized before use.
urn:posit:connect:api-key- Returns a Connect API key
Other sensitive credentials are never returned in the response.
For what each response type means in practice, including the AWS Security Token Service (STS) mechanisms and the properties of ephemeral Connect API keys, see Credential delivery.
Publisher trust model
When deployed content uses an integration on Connect, it receives a credential that can provide access to private external resources. Viewer integrations grant content the ability to access resources available to viewers. Service Account integrations grant content the ability to access resources available to the Service Account. Workload Identity integrations grant content the ability to access resources available to the configured workload identity.
Once the content receives this credential, Connect cannot control its use. Connect implicitly trusts that publishers’ content will not misuse delegated credentials, either maliciously or unintentionally.
Published content receives credentials that can expire, including OAuth access tokens and workload identity tokens. See Credential delivery for credential lifetimes and refresh behavior.
This trust model, which assumes that publishers will not misuse or abuse system assets, exists elsewhere in Connect. For example, this same implicit trust relationship applies to content that executes using Current User Execution accessing privileged resources. This is not a change in the fundamental trust model between the server and deployed content. Rather, it is an extension of the same underlying trust model with the following additional implications:
Publishers must protect credentials from content logs, caches outside of the content process, and other external observation.
Administrators should regularly audit user roles to ensure that users with the Publisher role are trusted actors on the server.
Sensitive fields
Setting up an integration may require configuring sensitive fields, such as an OAuth client secret for integrations which target confidential OAuth clients. Sensitive fields are encrypted-at-rest in the Connect database and are never returned by the Connect Server API.
Publishers must explicitly opt-in to use a particular integration with their content, either through the Runtime tab in the content settings pane or through the Connect Server API. Content can request credentials only for an integration with which it has been explicitly associated. Content never has access to sensitive information about configured integrations.
Modifying integrations
Connect allows integration edits to support certain essential maintenance and upkeep operations such as secret rotation. Given that there are certain contexts where edits to integrations are necessary, an integration should not be modified to point to an entirely different authentication provider. This ensures that access tokens from active user sessions are not leaked to an unintended authentication provider.
Encryption
Stored credentials
All OAuth credentials stored by Connect are encrypted-at-rest.
Network traffic
When considering the network topology of Connect, and by implication, the relevant network boundaries over which sensitive data might be communicated, it is useful to consider local and off-host execution separately.
To keep the discussion concrete, assume our integration has the Viewer Auth Type, and that our content process needs to acquire a user session token which will be communicated through an HTTP header. The topology differences for Service Account integrations and content session tokens are minimal and will be presented at the end of this section.
The following discussion assumes Connect has been configured to use SSL/TLS. It also assumes the third-party protected resource is configured to use SSL/TLS. Communication with third-party resources is out-of-scope for this document.
Local execution
In the network diagram below, a user initiates communication with Connect which targets some interactive content process, either over HTTPS or websockets using SSL (WSS) (1). Connect then proxies this request to the content (2). Finally, the content initiates a credential exchange request on behalf of the user (3) in order to acquire an OAuth access token which can be used to communicate with some third-party protected resource.
When Connect is running in local execution, all communication which crosses a network boundary (1 and 3) is encrypted by TLS. In particular, note that the credential exchange (3) uses the public Connect Server API to securely communicate the OAuth access token to the requesting content.
Off-host execution
The network topology of the off-host execution model on Connect is very similar to local execution. The initiating communication between a user and Connect remains unchanged (1). The token exchange which serves an OAuth access token to executing content still occurs over the TLS-backed Connect Server API (3). However, communication between the Connect server and the interactive content it manages now crosses an intra-cluster network boundary, because communication must pass between Kubernetes pods (2).
Traffic between the Connect server and executing content in Kubernetes (2) is not encrypted by default.
This network boundary is not encrypted for the following reasons:
Connect assumes that intra-network communication is managed by Kubernetes administrators who have hardened the external boundaries of the cluster against malicious actors.
Best practices dictate that communication within a Kubernetes cluster should be holistically secured by installing a service mesh.
Importantly, OAuth credentials are not communicated directly to executing content across this intra-cluster network boundary. The only relevant data that crosses this network boundary is the signed subject_token, which content can subsequently use to initiate a credential exchange through the TLS-secured Connect Server API to receive a credential.
No sensitive information is communicated in the subject_token. The signing secret used to verify the integrity of the user session token never crosses any network boundaries.
Content session token transmission
Where user session tokens are communicated through an HTTP header to interactive content, represented by step (2) in both the Local and Off-host execution network topology diagrams, content session tokens are transmitted to content through an encrypted environment variable which is made available to the executing content process. This environment variable is always encrypted. When token refresh is configured, Connect also periodically writes a refreshed token to a file in the job directory and publishes the path in the CONNECT_CONTENT_SESSION_TOKEN_FILE environment variable.
The rest of the network topology remains unchanged.
Viewer integrations
Prerequisites
Connect must have received a viewer’s OAuth credentials before the credential exchange occurs. This means that:
- The content being accessed by the viewer must have been explicitly associated with an integration by the content publisher.
- The viewer must have already logged into the OAuth provider and delegated their OAuth credentials to Connect before the credential exchange is initiated.
Restrictions
Viewer integrations are not supported for content which uses the Anyone - no login required access type. This means that every OAuth token maintained by Connect is linked to a named user on the server.
Proof Key for Code Exchange
Viewer integrations in Connect use the PKCE (Proof Key for Code Exchange) extension for the authorization code flow by default. PKCE is required in the upcoming OAuth 2.1 specification, and is recommended in all cases to protect against authorization code injection attacks. If necessary, PKCE can be disabled by creating a Custom integration, but this is not recommended.
Viewer identity delegation
This section describes non-AWS Viewer integrations that return OAuth access tokens to content. AWS Viewer integrations use the viewer’s OIDC ID token inside Connect to assume the IAM role and return temporary AWS credentials instead.
When a viewer is directed to log in to a third-party OAuth application by Connect, the viewer’s identity, represented by an OAuth access token, is stored and maintained on the Connect server. Under specific, well-defined circumstances, executing content is able to request this access token from Connect on behalf of the viewer.
In brief, the restrictions around when and how this credential exchange can occur ensure that both the user requesting the credential exchange and the viewer have the correct permissions, and that the viewer has recently interacted with the content which is requesting their OAuth access token. Additional details about the behavior of this credential exchange operation are provided above.
Once the executing content acquires the viewer’s OAuth access token, it can then make authenticated requests to a third-party protected resource using the viewer’s token. OAuth access tokens are short-lived credentials which expire.
Publishers are trusted to responsibly use OAuth access tokens within their deployed applications.
Process management
While each client session will use a user subject token which is scoped uniquely to the viewer, multiple clients which connect to the same application may reuse the same underlying server-side process. Because of this, published application code must be careful to scope sensitive information to the lifecycle of the client session. For example, applications should not store sensitive information in global variables which persist outside of the client session and are instead tied to the lifecycle of the application process.
The Connect application process management documentation provides additional information about how Connect manages long-running processes to service client connections.
Service account integrations
This section describes non-AWS Service Account integrations that return OAuth access tokens. AWS Service Account integrations use a Connect-issued OIDC content session token to assume the IAM role and return temporary AWS credentials.
OAuth token requests
Non-AWS Service Account integrations request a fresh OAuth access token from the external provider on every credential exchange. There is no OAuth session stored by Connect which caches the access token. No refresh token is received or stored by Connect.
Publisher access
There are two considerations which Connect administrators should be aware of when configuring Service Account integrations.
Viewer integrations require a login flow that explicitly acquires consent from the viewer before granting access to protected resources. Service Account integrations use a non-interactive flow that obtains credentials with the Connect server’s identity without additional opt-in.
By default every publisher has access to every integration configured on the Connect Server.
This means that, by default, the Connect server’s level of access to protected third-party resources is implicitly granted to every publisher on the Connect server through the use of a Service Account integration. Connect Administrators should carefully consider the level of access granted to the Service Account identity before granting access to publishers.
Access control lists
Administrators can configure an access control list (ACL) for an integration to restrict which publishers can associate that integration with their content and which users can use the integration directly. See the Integration Management section of the Connect User Guide for additional information on how to use the Integrations tab on the System page to configure ACLs for integrations.

