> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Identity propagation

By default, an Ocean integration executes integration actions using its own credentials. Every pipeline run or pull request it creates appears in the third-party tool as the integration's service account.

With identity propagation, an integration action runs as the user who triggered the workflow, using that user's own credentials in the third-party tool. The tool's audit logs show the real user, and the action is limited to that user's permissions.

Supported integrations

Identity propagation is supported on self-hosted Ocean integrations for:

  • GitHub - workflow, pull request, and issue actions. External custom property actions always use the GitHub App installation token.
  • GitLab - pipeline and merge request actions.
  • Azure DevOps - pipeline and pull request actions.

See each integration's action page for setup and the full list of actions.

How it works​

  1. Trigger - A user runs a workflow from a self-service trigger. The workflow's integration action node has identity propagation enabled.
  2. Sign - Port attaches a short-lived identity token to the action run, signed by Port. The token identifies the user and the specific run.
  3. Verify - The integration verifies the token against Port's public signing keys, and confirms that it belongs to the run it received.
  4. Look up - The integration looks up the user's access token for the third-party tool in a vault that you own.
  5. Authorize (first run only) - If no token is stored for the user, the run pauses and waits for the user to sign in. The user signs in to the third-party tool through the integration's OAuth broker, the integration stores the new token in the vault, and the run resumes automatically.
  6. Execute - The integration executes the action using the user's token.

Stored tokens are refreshed automatically when they expire. If a token cannot be refreshed, for example because the user revoked access, the run pauses and asks the user to sign in again.

User tokens are stored only in your vault and never pass through Port.

What it looks like in code​

An executor supports identity propagation by asking Ocean for the user's token before calling the third-party API. GitHub, GitLab, and Azure DevOps do this in their abstract executors. The following snippet is adapted from the GitHub abstract executor:

github/actions/abstract_github_executor.py
from port_ocean.identity_propagation.token_exchanger import resolve_user_token


async def _rest_client_for_org(
self, run: IntegrationRun, organization: str
) -> GithubRestClient:
# Returns None when the run does not use identity propagation.
# Verifies the identity token, reads the user's token from the vault, and
# refreshes it if needed. Pauses the run if the user has to sign in.
user_token = await resolve_user_token(run)
if not user_token:
return await create_github_client_for_org(organization)
return GithubRestClient(
github_host=str(ocean.integration_config["github_host"]),
authenticator=PersonalTokenAuthenticator(user_token, organization),
)

Each integration also registers its OAuth provider on startup. The GitHub registry is representative; GitLab and Azure DevOps follow the same pattern with their own authorize URLs and scopes:

github/oauth/registry.py
from port_ocean.identity_propagation.oauth_broker.providers import OAuth2Provider


def register_oauth_provider() -> None:
client_id = ocean.integration_config.get("identity_oauth_client_id")
client_secret = ocean.integration_config.get("identity_oauth_client_secret")
if not client_id or not client_secret:
return

web_host = oauth_web_host(
str(ocean.integration_config.get("github_host") or "https://api.github.com")
)
ocean.register_oauth_provider(
OAuth2Provider(
target=ocean.config.integration.type,
authorize_url=f"{web_host}/login/oauth/authorize",
token_url=f"{web_host}/login/oauth/access_token",
client_id=client_id,
client_secret=client_secret,
scopes="repo",
)
)

Prerequisites​

  • Self-service trigger - Identity propagation requires a user to act as, so it is available only in workflows with a self-service trigger. Port rejects workflows that combine it with event or schedule triggers.
  • Public base URL - The integration's OCEAN__BASE_URL must be reachable from your users' browsers, since the sign-in flow redirects them to it. On startup, the integration registers its OAuth broker with Port at <OCEAN__BASE_URL>/v1/oauth-broker/authorize.
  • OAuth app - An OAuth application registered with the third-party tool, with the redirect URI set to <OCEAN__BASE_URL>/v1/oauth-broker/callback. Provider-specific setup is on the GitHub, GitLab, and Azure DevOps action pages.
  • Vault - An AWS Secrets Manager instance that the integration can access, with the secretsmanager:GetSecretValue, secretsmanager:CreateSecret, and secretsmanager:PutSecretValue permissions.

Enable identity propagation in a workflow​

Set enableIdentityPropagation to true in the configuration of the integration action node, in the workflow's JSON. The example below uses Azure DevOps; the same flag works for GitHub and GitLab action nodes:

{
"identifier": "trigger_pipeline",
"title": "Trigger pipeline",
"config": {
"type": "INTEGRATION_ACTION",
"installationId": "my-azure-devops-integration",
"integrationProvider": "azure-devops",
"integrationInvocationType": "trigger_pipeline",
"enableIdentityPropagation": true,
"integrationActionExecutionProperties": {
"...": "..."
}
}
}

Configuration​

Identity propagation is configured on the integration using the following environment variables (or the equivalent Helm values under identityPropagation).

VariableDescriptionDefault
OCEAN__IDENTITY_PROPAGATION__ENABLEDWhether to enable identity propagation. Also requires OCEAN__ACTIONS_PROCESSOR__ENABLED=true and a public OCEAN__BASE_URL.false
OCEAN__IDENTITY_PROPAGATION__VAULT__TYPEThe vault used to store user tokens.aws_secrets_manager
OCEAN__IDENTITY_PROPAGATION__VAULT__AWS_REGIONThe AWS region of the vault. AWS credentials are read from the standard AWS credential chain.-
OCEAN__IDENTITY_PROPAGATION__VAULT__SECRET_PREFIXThe prefix of the secrets that hold user tokens. Each secret is named <prefix>/<org_id>/<user_id>/<integration_type>.port/tokens
OCEAN__IDENTITY_PROPAGATION__OAUTH__STATE_SIGNING_SECRETThe secret used to sign the sign-in flow's state. When not set, a key is derived from the integration's Port client secret.-
OCEAN__PORT__APP_URLThe URL of Port's app, used to redirect users back to the workflow run after signing in. When not set, it is derived from the Port API URL.-

OAuth app credentials are set on the integration config, not under identityPropagation:

Variable / Helm keyDescription
identityOauthClientId (OCEAN__INTEGRATION__CONFIG__IDENTITY_OAUTH_CLIENT_ID)Client ID of the OAuth application.
identityOauthClientSecret (OCEAN__INTEGRATION__CONFIG__IDENTITY_OAUTH_CLIENT_SECRET)Client secret of the OAuth application.
identityOauthTenantId (OCEAN__INTEGRATION__CONFIG__IDENTITY_OAUTH_TENANT_ID)Entra ID tenant ID. Required for Azure DevOps only.

Authorize and token URLs are derived from each integration's host or tenant settings (githubHost, gitlabHost, or identityOauthTenantId). For Helm examples and provider-specific OAuth app setup, see the GitHub, GitLab, and Azure DevOps action pages.

Actions without identity propagation support

Enabling enableIdentityPropagation on an action that does not support it has no effect, and the action runs with the integration's own credentials.