Legacy Native Users - Formal Documentation

Overview

Legacy Native Users define the upstream credentials used by Resources that have not migrated to new Native Users.

A new version of Native Users is available with Formal Connector version 2.17.0 or later. See the migration guide for configuration steps.

Legacy Native Users use identity links and a default flag. Native Users replace these assignments with a Resource-level CEL expression.

How legacy selection works

A legacy Native User contains an upstream username, secret, and optional default setting. You can assign one Native User directly to a Formal User or Group. Group members inherit the Group’s assignment. A Formal User with a direct assignment cannot join a Group that also has an assignment. Remove the direct assignment first. Clients can request a specific Native User with the @<native_user> connection username suffix.

Web
Terraform

Create a legacy Native User

Go to Resources and open the Resource.
Select Authentication.
Confirm that the page shows the legacy Native Users interface.
Click Add User.
Select an authentication method.
Enter the upstream username and credential values.
Set Use as Default when this user should handle unmatched sessions.
Click Create.

Verify: Confirm that the user appears in the list. Check that the Default indicator matches your configuration.

Reference a Connector environment variable

Set the secret to ENV:<VARIABLE_NAME>:

ENV:DB_READONLY_PASSWORD

The Connector reads DB_READONLY_PASSWORD when it resolves the credential.

Define the environment variable in every Connector deployment serving this Resource.

Use legacy IAM authentication

Legacy Native Users encode cloud authentication in the secret field:

Provider	Secret value
AWS ambient identity	`iam`
AWS assumed role	An IAM role ARN
GCP ambient identity	`iam_gcp`
Azure ambient identity	`iam_azure`

For AWS database authentication, the username is the IAM-enabled database user. The Connector identity needs rds-db:connect permission for that user.For GCP Cloud SQL, use the service account email without the .gserviceaccount.com suffix as the username.For Azure Database, use the Microsoft Entra principal provisioned as the database login.

Configure a legacy Snowflake key pair

Create a Password Native User and store the PEM-encoded private key in its secret field. The Connector detects the PEM format and uses SNOWFLAKE_JWT.Snowflake clients must also select the SNOWFLAKE_JWT authenticator.

Configure legacy HTTP credentials

Legacy HTTP Native Users store a JSON document in the secret field.Use this shape for HTTP Basic authentication:

{
  "type": "http",
  "sub_type": "basic",
  "http_basic": {
    "header": "Authorization",
    "username": "<UPSTREAM_USERNAME>",
    "password": "<UPSTREAM_PASSWORD>"
  }
}

Use this shape for a header API key:

{
  "type": "http",
  "sub_type": "api_key",
  "http_api_key": {
    "type": "header",
    "key": "Authorization",
    "value": "<API_KEY>"
  }
}

Use this shape for a bearer token:

{
  "type": "http",
  "sub_type": "bearer_token",
  "http_bearer_token": {
    "header": "Authorization",
    "token": "<BEARER_TOKEN>"
  }
}

Native Users replace these documents with typed credential fields.

Configure a legacy SSH certificate

Legacy SSH certificate authentication stores a JSON document in the secret:

{
  "key": "-----BEGIN OPENSSH PRIVATE KEY-----...",
  "cert": "ssh-ed25519-cert-v01@openssh.com ..."
}

Native Users provide separate private key and certificate fields.

Assign a legacy Native User

Select the Native User from the Authentication tab.
Find Linked Identities.
Click Add beside Formal Users or Formal Groups.
Select the identities and click Add.

The assignment overrides the Resource’s default Native User.Verify: Connect as an assigned identity and confirm the expected upstream username appears in session logs.

Create a legacy Native User

Use formal_native_user:

resource "formal_native_user" "read_only" {
  native_user_id        = "readonly"
  native_user_secret    = "ENV:DB_READONLY_PASSWORD"
  resource_id           = formal_resource.database.id
  use_as_default        = true
  termination_protection = false
}

Argument	Description
`native_user_id`	Upstream username
`native_user_secret`	Password, environment reference, or legacy IAM marker
`resource_id`	Resource ID
`use_as_default`	Uses this Native User when no other assignment resolves
`termination_protection`	Prevents deletion when `true`

Verify:

terraform plan
terraform apply

Assign a Formal identity

Use the generated Formal resource IDs, not usernames:

resource "formal_native_user_link" "analysts" {
  formal_identity_id   = formal_group.analysts.id
  formal_identity_type = "group"
  native_user_id       = formal_native_user.read_only.id
}

formal_identity_type accepts user or group.Verify:

terraform plan

Confirm that the plan links the intended Formal identity and Native User.

Request a legacy Native User

Append @<native_user> to the Formal username:

<formal_username>@<native_user>

For example:

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

For legacy users, the requested value is the configured upstream username.

Use legacy values in policies

input.native_user contains the upstream username. The input.native_user_assignment value can be:

Value	Meaning
`user-requested`	The client requested the Native User
`user`	A direct Formal User link selected it
`group`	A Formal Group link selected it
`resource-hostname`	A Resource hostname link selected it
`default`	The Resource default selected it

This policy blocks a privileged legacy username:

package formal.v2

import future.keywords.if

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

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  input.native_user == "admin"
}

See policy evaluation for more policy examples.

Migrate to new Native Users

A new version of Native Users is available with typed credentials, hooks, and default Native User selection. This guide explains how to configure it.

Web
Terraform

New Native Users require Connector version 2.17.0 or later. Upgrade every Connector serving this Resource before opting in.

Preview and create new Native Users

Click the Preview button to add new Native Users. Previewed changes are saved, but Connectors continue using legacy credentials. Formal does not copy legacy secrets into the replacements.Create one replacement for each legacy Native User:

Legacy credential	New credential type
Username and password	Password
AWS ambient IAM marker `iam`	AWS IAM
AWS IAM role ARN used for authentication	AWS IAM Role
GCP IAM marker `iam_gcp`	GCP IAM
Azure IAM marker `iam_azure`	Azure IAM
Snowflake PEM private key	Snowflake Key
SSH key or key and certificate JSON	SSH Key
HTTP authentication JSON	Matching HTTP credential type

For an ENV:<NAME> secret, choose Environment Variable and enter <NAME>. Do not include the ENV: prefix.

New Native Users use labels for explicit Native User selection, rather than usernames. If you rely on a specific username for selection, match the new label to the legacy username.

Replace identity links with a default selection

Legacy identity links do not migrate automatically. Recreate their behavior in Default Native User with CEL.Place specific User rules before Group rules, then return the legacy default:

user.id == "user_01k9fanpwmbsnpn32ep6axj1qr" // alice
  ? "nativeuser_01k3wxrm9zyfj2yce5m2w0xcav" // admin
  : "group_01kzrt34v7c2wv0ygtekyycctr" in user.group_ids // analysts
    ? "nativeuser_01km5mz0x5t6t9gs195s5dhe73" // readonly
    : "nativeuser_01kepdb116rvbjv9trev7p3nhm" // default

You can retrieve native user IDs by clicking the respective row in the Native Users table.See select a default Native User for supported identity fields and more examples.

Review policies

New Native Users expose their label through input.native_user. Preserve legacy usernames as labels to keep these comparisons stable.Update policies that inspect input.native_user_assignment. New Native Users return cel or user-requested instead of legacy assignment values.

Activate and verify

Click Opt in, enter confirm, and complete these checks:

Connect without a label and confirm the expected default selection.
Connect as an identity with a User or Group rule.
Connect with @<label> if clients request Native Users explicitly.
Confirm the upstream identity and policy result in session logs.

Legacy Native Users remain stored after activation, if a rollback is needed.

Roll back if needed

To roll back, click Roll back and enter confirm. The Resource resumes using its stored legacy configuration.New Native Users and their selection remain stored. Fix the configuration, then opt in again.

New Native Users require Formal Terraform Provider 4.26.0 or later and Connector version 2.17.0 or later. Upgrade every Connector serving the Resource before opting in.

Add formal_native_user_v3 resources alongside legacy resources

Keep every formal_native_user and formal_native_user_link block. Add separate formal_native_user_v3 replacements. Expand each credential type for its before-and-after configuration.

New Native Users use labels for explicit Native User selection, rather than usernames. If you rely on a specific username for selection, match the new label to the legacy username.

Password or environment variable

Before

resource "formal_native_user" "read_only" {
  resource_id        = formal_resource.database.id
  native_user_id     = "readonly"
  native_user_secret = "ENV:DB_READONLY_PASSWORD"
}

After

resource "formal_native_user_v3" "read_only" {
  resource_id = formal_resource.database.id
  label       = "readonly"

  basic {
    username = "readonly"
    password {
      environment_variable = "DB_READONLY_PASSWORD"
    }
  }
}

Remove ENV: from the V3 environment_variable value. To store the password in Formal instead, replace environment_variable with literal.

AWS ambient IAM

Before

resource "formal_native_user" "aws_ambient" {
  resource_id        = formal_resource.database.id
  native_user_id     = "iam_database_user"
  native_user_secret = "iam"
}

After

resource "formal_native_user_v3" "aws_ambient" {
  resource_id = formal_resource.database.id
  label       = "iam_database_user"

  aws_iam {
    username = "iam_database_user"
  }
}

AWS IAM role

Before

resource "formal_native_user" "aws_role" {
  resource_id        = formal_resource.database.id
  native_user_id     = "iam_database_user"
  native_user_secret = "arn:aws:iam::123456789012:role/formal-database-access"
}

After

resource "formal_native_user_v3" "aws_role" {
  resource_id = formal_resource.database.id
  label       = "iam_database_user"

  aws_iam_role {
    username = "iam_database_user"
    role     = "arn:aws:iam::123456789012:role/formal-database-access"
  }
}

GCP IAM

Before

resource "formal_native_user" "gcp_iam" {
  resource_id        = formal_resource.database.id
  native_user_id     = "formal-connector"
  native_user_secret = "iam_gcp"
}

After

resource "formal_native_user_v3" "gcp_iam" {
  resource_id = formal_resource.database.id
  label       = "formal-connector"

  gcp_iam {
    username = "formal-connector"
  }
}

Continue using the service account email without the .gserviceaccount.com suffix as the username.

Azure IAM

Before

resource "formal_native_user" "azure_iam" {
  resource_id        = formal_resource.database.id
  native_user_id     = "formal-connector"
  native_user_secret = "iam_azure"
}

After

resource "formal_native_user_v3" "azure_iam" {
  resource_id = formal_resource.database.id
  label       = "formal-connector"

  azure_iam {
    username = "formal-connector"
  }
}

Snowflake private key

Before

resource "formal_native_user" "snowflake" {
  resource_id        = formal_resource.snowflake.id
  native_user_id     = "FORMAL_CONNECTOR"
  native_user_secret = "ENV:SNOWFLAKE_PRIVATE_KEY"
}

After

resource "formal_native_user_v3" "snowflake" {
  resource_id = formal_resource.snowflake.id
  label       = "FORMAL_CONNECTOR"

  snowflake_key {
    username = "FORMAL_CONNECTOR"
    key {
      environment_variable = "SNOWFLAKE_PRIVATE_KEY"
    }
  }
}

SSH private key and certificate

Before

resource "formal_native_user" "ssh" {
  resource_id    = formal_resource.ssh.id
  native_user_id = "ubuntu"
  native_user_secret = jsonencode({
    key  = file("${path.module}/id_rsa")
    cert = file("${path.module}/id_rsa-cert.pub")
  })
}

After

resource "formal_native_user_v3" "ssh" {
  resource_id = formal_resource.ssh.id
  label       = "ubuntu"

  ssh_key {
    username = "ubuntu"
    key {
      literal = file("${path.module}/id_rsa")
    }
    certificate {
      literal = file("${path.module}/id_rsa-cert.pub")
    }
  }
}

For private-key-only authentication, use the same ssh_key block without certificate.

HTTP Basic

Before

resource "formal_native_user" "http_basic" {
  resource_id    = formal_resource.api.id
  native_user_id = "basic-auth"
  native_user_secret = jsonencode({
    type     = "http"
    sub_type = "basic"
    http_basic = {
      header   = "Authorization"
      username = "api_user"
      password = "ENV:HTTP_BASIC_PASSWORD"
    }
  })
}

After

resource "formal_native_user_v3" "http_basic" {
  resource_id = formal_resource.api.id
  label       = "basic-auth"

  http_basic {
    header   = "Authorization"
    username = "api_user"
    password {
      environment_variable = "HTTP_BASIC_PASSWORD"
    }
  }
}

HTTP bearer token

Before

resource "formal_native_user" "http_bearer" {
  resource_id    = formal_resource.api.id
  native_user_id = "bearer"
  native_user_secret = jsonencode({
    type     = "http"
    sub_type = "bearer_token"
    http_bearer_token = {
      header = "Authorization"
      token  = "ENV:HTTP_BEARER_TOKEN"
    }
  })
}

After

resource "formal_native_user_v3" "http_bearer" {
  resource_id = formal_resource.api.id
  label       = "bearer"

  http_bearer {
    header = "Authorization"
    token {
      environment_variable = "HTTP_BEARER_TOKEN"
    }
  }
}

HTTP API key header

Before

resource "formal_native_user" "http_api_key_header" {
  resource_id    = formal_resource.api.id
  native_user_id = "header-api-key"
  native_user_secret = jsonencode({
    type     = "http"
    sub_type = "api_key"
    http_api_key = {
      type  = "header"
      key   = "X-Api-Key"
      value = "ENV:HTTP_API_KEY"
    }
  })
}

After

resource "formal_native_user_v3" "http_api_key_header" {
  resource_id = formal_resource.api.id
  label       = "header-api-key"

  http_api_key_header {
    key = "X-Api-Key"
    value {
      environment_variable = "HTTP_API_KEY"
    }
  }
}

HTTP API key query parameter

Before

resource "formal_native_user" "http_api_key_query" {
  resource_id    = formal_resource.api.id
  native_user_id = "query-api-key"
  native_user_secret = jsonencode({
    type     = "http"
    sub_type = "api_key"
    http_api_key = {
      type  = "query_params"
      key   = "api_key"
      value = "ENV:HTTP_API_KEY"
    }
  })
}

After

resource "formal_native_user_v3" "http_api_key_query" {
  resource_id = formal_resource.api.id
  label       = "query-api-key"

  http_api_key_query {
    key = "api_key"
    value {
      environment_variable = "HTTP_API_KEY"
    }
  }
}

Default and identity links

Before

resource "formal_native_user" "readonly" {
  resource_id        = formal_resource.database.id
  native_user_id     = "readonly"
  native_user_secret = "ENV:DB_READONLY_PASSWORD"
  use_as_default     = true
}

resource "formal_native_user_link" "alice" {
  native_user_id       = formal_native_user.admin.id
  formal_identity_id   = formal_user.alice.id
  formal_identity_type = "user"
}

resource "formal_native_user_link" "dev" {
  native_user_id       = formal_native_user.readwrite_all.id
  formal_identity_id   = formal_group.dev.id
  formal_identity_type = "group"
}

resource "formal_native_user_link" "sales" {
  native_user_id       = formal_native_user.readwrite_sales.id
  formal_identity_id   = formal_group.sales.id
  formal_identity_type = "group"
}

AfterAfter creating V3 replacements named admin, readwrite_all, readwrite_sales, and readonly, replace the default and links with one selection:

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

  cel = <<-CEL
    user.id == "${formal_user.alice.id}"
      ? "${formal_native_user_v3.admin.id}"
      : "${formal_group.dev.id}" in user.group_ids
        ? "${formal_native_user_v3.readwrite_all.id}"
        : "${formal_group.sales.id}" in user.group_ids
          ? "${formal_native_user_v3.readwrite_sales.id}"
          : "${formal_native_user_v3.readonly.id}"
  CEL
}

The final branch replaces use_as_default. Place User rules before Group rules.

Use the default selection examples to translate User and Group links.Selection CEL has no Resource Hostname object. For a resource_hostname link, match the machine identity through user.id, user.username, or user.external_ids.Do not use terraform state mv. V3 Native Users are separate records with new IDs.

Apply the staged configuration

terraform plan
terraform apply

Verify: The plan creates V3 Native Users and the selection. It must not destroy legacy resources or enable V3.

Activate V3 in a separate apply

Change only the mode flag:

native_users_v3_enabled = true

Then apply:

terraform plan
terraform apply

Verify: The plan changes the Resource in place. It must not replace the Resource or either set of Native Users.Test default, User, Group, and explicit label selection after activation. Confirm the upstream identity and policy result in session logs.

Roll back or remove legacy resources

To roll back, set native_users_v3_enabled = false and apply.Keep legacy resources in configuration until you no longer need rollback. Then remove their formal_native_user and formal_native_user_link blocks.Disable termination protection before removing protected legacy resources. Run terraform plan and confirm that only legacy resources are destroyed.

​Overview

​How legacy selection works

​Create a legacy Native User

​Reference a Connector environment variable

​Use legacy IAM authentication

​Configure a legacy Snowflake key pair

​Configure legacy HTTP credentials

​Configure a legacy SSH certificate

​Assign a legacy Native User

​Create a legacy Native User

​Assign a Formal identity

​Request a legacy Native User

​Use legacy values in policies

​Migrate to new Native Users

Overview

How legacy selection works

Create a legacy Native User

Reference a Connector environment variable

Use legacy IAM authentication

Configure a legacy Snowflake key pair

Configure legacy HTTP credentials

Configure a legacy SSH certificate

Assign a legacy Native User

Create a legacy Native User

Assign a Formal identity

Request a legacy Native User

Use legacy values in policies

Migrate to new Native Users