Overview
Native Users define how a Connector authenticates to an upstream Resource. Formal identities never need to know or send these upstream credentials.This guide documents Native Users supported by Connector 2.17.0 and later.
If your Resource still uses legacy Native Users, see the
migration guide.
How Native Users work
Each Native User has three important properties:- A label identifies the Native User within its Resource.
- A credential type defines how the Connector authenticates upstream.
- A credential source supplies static values or runs a hook at connection time.
@<label> to their Formal
username. The requested Native User takes precedence over the default selection.
Supported credential types
The Control Plane shows only the credential types supported by the Resource:- Web
- Terraform
Create a Native User
- Go to Resources and open your Resource.

- Select Authentication.
- Click Add User.

- Select a credential type.

- Enter a unique Label.
- Choose Static or Hook as the credential source.
- Configure the credential fields and termination protection.
- Click Create.
ANALYTICS_READONLY_PASSWORD. Do not use the legacy ENV: prefix.Verify: Confirm that the Native User appears under Native Users with
the expected label, credential type, and authentication source.Resolve credentials with a hook
Choose Hook when credentials must be generated or fetched at connection time. The hook runs on the Connector after policy allows the connection.Select the credential type before writing the hook. The hook must return that type’s exact credential shape.Allowlist every environment variable the hook reads. Access each value through the hook’senv argument.Add a named entry under Secrets for each
secret manager reference the hook needs. The
Connector fetches them before the hook runs and passes them as the fourth
argument, so the hook reads secrets["NAME"]. Names use letters, digits, and
underscores, and cannot start with a digit. The hook does not run if a secret
cannot be fetched.The input argument contains the Resource and selected Native User:Hook examples
The editor providesHookNativeUserInput, HookNativeUserEnvironment, and
HookNativeUserOutput types for your selected credential type.Read a database password from the Connector
Read a database password from the Connector
Select Password and allowlist
DATABASE_PASSWORD.Fetch database credentials from Vault
Fetch database credentials from Vault
Select Password. Allowlist the
vault.example.com network host and
the VAULT_TOKEN environment variable.Mint an HTTP bearer token
Mint an HTTP bearer token
Select HTTP Bearer. Allowlist the
auth.example.com network host.
Allowlist the OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET environment
variables.Rotate or edit credentials
Select a Native User to open its details. You can rename its label or change termination protection.Use Update Credentials to rotate static credentials. You cannot change a Native User’s credential type or switch between static and hook sources. Create another Native User for those changes.
Select a default Native User
Default Native User maps a Formal identity to a Native User. Reference a Native User by its label withnative_users["<label>"].Selecting by label requires Connector version 2.25.3 or later.

user object supports these fields:native_users maps each of the Resource’s Native User labels to its ID.Each result branch must be a native_users lookup with a literal label of
one of the Resource’s Native Users, or a literal Native User ID. Computed
lookups such as native_users[user.username] are rejected.Click Save after the editor shows Valid CEL.Verify: Connect without an @<label> suffix and confirm the expected
upstream credential identity appears in the session log.Require an explicit selection
Leave Default Native User unset to require clients to request a label. HTTP Resources instead proceed without injected credentials, except those with linked accounts, which refuse the request.A CEL branch can return an empty string to reject matching identities:Secret manager references
A secret manager reference points at a secret the Connector fetches at connection time. The Connector authenticates with its own cloud identity, so grant that identity read access to each secret. Formal stores only the reference, never the secret value.
AWS Secrets Manager: Use the full secret ARN, including the six-character
suffix AWS appends to the secret name. The account ID must be 12 digits. To
select a JSON key or a version, use the extended form ECS task definitions use,
<arn>:<json-key>:<version-stage>:<version-id>, leaving unused fields empty.
Set a version stage or a version ID, not both. Without either, the Connector
reads AWSCURRENT. For example,
arn:aws:secretsmanager:us-east-1:123456789012:secret:db-AbCdEf:password::
reads the password key of the current version.
GCP Secret Manager: Use the secret version’s resource name. The version can
be a number or latest. Use the locations/<location> form for regional
secrets.
Azure Key Vault: Use the secret identifier URL. Omit the version to read the
latest version. Vaults in the Azure China and Azure US Government clouds use the
vault.azure.cn and vault.usgovcloudapi.net hosts.
Request a Native User at connection time
Append@<label> to the Formal username:
Control explicit overrides with policies
Native Users expose both the requested Native User and assigned default to policies. Each object containsid, label, and user_type.
This session policy blocks an explicit request that differs from the assigned
default:
Understand Native Users in logs
For Formal-authenticated sessions,user.formal.native contains the selected
Native User’s upstream username when applicable.
When a client connects directly with Resource credentials, user.type is
native. Formal identity fields and user.formal.native are absent.