Native Users - Formal Documentation

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 the legacy model, see Legacy Native Users.If you would like to migrate to new Native Users, see the migration guide.gRPC Resources do not support either model.

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 ID. 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 Formal console shows only the credential types supported by the Resource:

Credential type	`user_type`	Connector behavior
Password	`basic`	Sends an upstream username and password
SSH Key	`ssh_key`	Uses an SSH username, private key, and optional certificate
Snowflake Key	`snowflake_key`	Uses a Snowflake username and private key
AWS IAM	`aws_iam`	Uses the Connector’s ambient AWS credentials
AWS IAM Role	`aws_iam_role`	Assumes a specified AWS role
GCP IAM	`gcp_iam`	Uses the Connector’s ambient GCP service account
Azure IAM	`azure_iam`	Uses the Connector’s ambient Microsoft Entra identity
Kubeconfig Path	`kubernetes_path`	Reads a kubeconfig file on the Connector
Kubeconfig	`kubernetes_inline`	Uses an inline kubeconfig document
HTTP Basic	`http_basic`	Injects Basic credentials into a named header
HTTP Bearer	`http_bearer`	Injects a bearer token into a named header
API Key (Header)	`http_api_key_header`	Injects an API key into a named header
API Key (Query)	`http_api_key_query`	Injects an API key into a query parameter

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.

For static secrets, choose Value to store an encrypted value in Formal. Choose Environment Variable to resolve it on the Connector.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.The input argument contains the Resource and selected Native User:

type HookNativeUserInput = {
  resource: {
    id: string;
    name: string;
    technology: string;
    hostname: string;
    port: number;
    environment: string;
    provider: string;
  };
  native_user: {
    id: string;
    label: string;
    output_type: string;
  };
};

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.

Read a database password from the Connector

Select Password and allowlist DATABASE_PASSWORD.

export default async function credentials(
  input: HookNativeUserInput,
  env: HookNativeUserEnvironment,
): Promise<HookNativeUserOutput> {
  const password = env["DATABASE_PASSWORD"];
  if (!password) {
    throw new Error("DATABASE_PASSWORD is not set");
  }

  return {
    username: input.native_user.label,
    password,
  };
}

Fetch database credentials from Vault

Select Password. Allowlist the vault.example.com network host and the VAULT_TOKEN environment variable.

export default async function credentials(
  _input: HookNativeUserInput,
  env: HookNativeUserEnvironment,
): Promise<HookNativeUserOutput> {
  const token = env["VAULT_TOKEN"];
  if (!token) {
    throw new Error("VAULT_TOKEN is not set");
  }

  const response = await fetch(
    "https://vault.example.com/v1/database/creds/readonly",
    {
      headers: { "x-vault-token": token },
    },
  );
  if (!response.ok) {
    throw new Error(`Vault returned ${response.status}`);
  }

  const result = (await response.json()) as {
    data?: { username?: string; password?: string };
  };
  if (!result.data?.username || !result.data.password) {
    throw new Error("Vault returned invalid credentials");
  }

  return {
    username: result.data.username,
    password: result.data.password,
  };
}

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.

export default async function credentials(
  _input: HookNativeUserInput,
  env: HookNativeUserEnvironment,
): Promise<HookNativeUserOutput> {
  const clientId = env["OAUTH_CLIENT_ID"];
  const clientSecret = env["OAUTH_CLIENT_SECRET"];
  if (!clientId || !clientSecret) {
    throw new Error("OAuth client credentials are not set");
  }

  const body = [
    "grant_type=client_credentials",
    `client_id=${encodeURIComponent(clientId)}`,
    `client_secret=${encodeURIComponent(clientSecret)}`,
  ].join("&");
  const response = await fetch("https://auth.example.com/oauth/token", {
    method: "POST",
    headers: { "content-type": "application/x-www-form-urlencoded" },
    body,
  });
  if (!response.ok) {
    throw new Error(`OAuth server returned ${response.status}`);
  }

  const result = (await response.json()) as { access_token?: string };
  if (!result.access_token) {
    throw new Error("OAuth server did not return an access token");
  }

  return {
    header: "Authorization",
    token: result.access_token,
  };
}

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 ID. You can copy a Native User’s ID from its action menu to reference it in the CEL expression.

Default Native User CEL expression editor

Return one ID to use the same Native User for everyone:

"nativeuser_01km5mz0x5t6t9gs195s5dhe73" // readonly

Use a conditional expression to select by identity:

"admins" in user.groups
  ? "nativeuser_01k3wxrm9zyfj2yce5m2w0xcav" // admin
  : "nativeuser_01km5mz0x5t6t9gs195s5dhe73" // readonly

The user object supports these fields:

Field	Type
`user.id`	String
`user.email`	String
`user.username`	String
`user.type`	String
`user.external_ids`	List of strings
`user.groups`	List of strings
`user.group_ids`	List of strings

CEL result branches must contain literal Native User IDs. Computed result strings 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.A CEL branch can return an empty string to reject matching identities:

user.type == "machine"
  ? "nativeuser_01kw0tsje6ztr0sw1fyr4t3845" // service account
  : ""

This rejection also applies when the client requests a label explicitly.

Create a Native User

Define each Native User with a typed credential block:

resource "formal_resource" "database" {
  name       = "analytics-postgres"
  hostname   = "analytics.internal"
  technology = "postgres"
  port       = 5432
}

resource "formal_native_user_v3" "admin" {
  resource_id = formal_resource.database.id
  label       = "admin"

  basic {
    username = "app_admin"
    password {
      environment_variable = "ANALYTICS_ADMIN_PASSWORD"
    }
  }
}

resource "formal_native_user_v3" "read_only" {
  resource_id = formal_resource.database.id
  label       = "read-only"

  basic {
    username = "app_readonly"
    password {
      environment_variable = "ANALYTICS_READONLY_PASSWORD"
    }
  }
}

resource "formal_resource_native_user_selection" "database" {
  resource_id = formal_resource.database.id

  cel = <<-CEL
    "admins" in user.groups
      ? "${formal_native_user_v3.admin.id}"
      : "${formal_native_user_v3.read_only.id}"
  CEL
}

An environment_variable value names an environment variable on the Connector. A literal value stores the secret in Terraform state.Verify:

terraform plan
terraform apply

Confirm that the plan creates two formal_native_user_v3 resources and one formal_resource_native_user_selection.

Use a hook

Hooks run on the Connector at connection time. Declare the output shape and allowlist each environment variable:

resource "formal_native_user_v3" "dynamic" {
  resource_id = formal_resource.database.id
  label       = "dynamic"

  hook {
    output_type               = "basic"
    allowlisted_env_variables = ["FORMAL_ENV_USER", "FORMAL_ENV_PASSWORD"]
    code                      = <<-TYPESCRIPT
      export default async function (_input, env) {
        return {
          username: env.FORMAL_ENV_USER,
          password: env.FORMAL_ENV_PASSWORD,
        };
      }
    TYPESCRIPT
  }
}

Request a Native User at connection time

Append @<label> to the Formal username:

<formal_username>@<native_user_label>

For example:

psql \
  --host "<CONNECTOR_HOSTNAME>" \
  --port 5432 \
  --dbname "<DATABASE_NAME>" \
  --username "idp:formal:human:john@example.com@read-only"

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:

package formal.v2

import future.keywords.if

default session := {"action": "allow"}

session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "This Native User is not assigned to your identity"
} if {
  input.native_user_assignment == "user-requested"
  input.native_user_selection.requested.id != input.native_user_selection.assigned.id
}

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.

​Overview

​How Native Users work

​Supported credential types

​Create a Native User

​Resolve credentials with a hook

​Hook examples

​Rotate or edit credentials

​Select a default Native User

​Require an explicit selection

​Create a Native User

​Use a hook

​Request a Native User at connection time

​Control explicit overrides with policies

​Understand Native Users in logs

Overview

How Native Users work

Supported credential types

Create a Native User

Resolve credentials with a hook

Hook examples

Rotate or edit credentials

Select a default Native User

Require an explicit selection

Create a Native User

Use a hook

Request a Native User at connection time

Control explicit overrides with policies

Understand Native Users in logs