Skip to main content

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.
You can configure a default Native User selection for each Formal identity. The selection returns a Native User, usually by its label. A user can instead request a Native User by appending @<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:

Create a Native User

  1. Go to Resources and open your Resource. Resources list with a Resource ready to open
  2. Select Authentication.
  3. Click Add User. Authentication tab with the Native Users section and Add User button
  4. Select a credential type. Add Native User credential type picker
  5. Enter a unique Label.
  6. Choose Static or Hook as the credential source.
  7. Configure the credential fields and termination protection.
  8. Click Create.
For static secrets, choose Value to store an encrypted value in Formal. Choose Environment Variable to resolve it on the Connector. Choose Secret Manager to have the Connector fetch it from AWS Secrets Manager, GCP Secret Manager, or Azure Key Vault with its own cloud credentials. See Secret manager references for the accepted formats.Enter only the environment variable name, such as 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’s env 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:
The Formal identity is intentionally absent from hook input. Use the default selection to choose credentials by identity.

Hook examples

The editor provides HookNativeUserInput, HookNativeUserEnvironment, and HookNativeUserOutput types for your selected credential type.
Select Password and allowlist DATABASE_PASSWORD.
Select Password. Allowlist the vault.example.com network host and the VAULT_TOKEN environment variable.
Select HTTP Bearer. Allowlist the auth.example.com network host. Allowlist the OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET environment variables.
Network access is denied unless you allowlist the destination hostname. See Hooks for network and runtime limits.

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.Native User details with credential and termination protection settings

Select a default Native User

Default Native User maps a Formal identity to a Native User. Reference a Native User by its label with native_users["<label>"].
Selecting by label requires Connector version 2.25.3 or later.
Default Native User CEL expression editorReturn one label to use the same Native User for everyone:
Use a conditional expression to select by identity:
To inject a credential for one group and let everyone else use their own, point the other branch at a Passthrough Native User:
The 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:
This rejection also applies when the client requests a label explicitly.

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:
For example:
The label selects the Native User. It does not need to match the upstream username. An explicit request takes precedence over the assigned default. Use policies to restrict overrides and privileged labels.

Control explicit overrides with policies

Native Users expose both the requested Native User and assigned default to policies. Each object contains id, label, and user_type. This session policy blocks an explicit request that differs from the assigned default:
See policy evaluation for the complete input shape.

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.