Native Users

Native users allow you to control which credentials the Connector will use when communicating with a resource. These credentials can be decoupled from the Formal credentials so that Formal identities do not need to pass these credentials to the Connector.

gRPC Resources do not support Native Users. Formal identities should pass native credentials in addition to (or instead of) their Formal credentials.

Formal Users and Groups can only be assigned one native user. If a Formal Group is assigned a native user, all the Formal Users within it will be assigned that native user. To avoid ambiguity, a Formal User that has a native user assignment cannot be added to a Formal Group that also has a native user assignment: the user’s assignment must be removed first. This is a safety measure to ensure purposeful intent when privileges are modified.

Web
Terraform

Create a native user

Go to Resources and open the resource.
Select Authentication, then click Add User.
Select an authentication method. The available methods depend on the resource technology. For AWS resources, AWS IAM (standard) uses the Connector’s ambient identity. AWS IAM (assume role) assumes the specified IAM role ARN.
Complete the fields and create the Native User. For password authentication, Username and Password are upstream credentials. Other methods show fields specific to their credential type. For example, AWS IAM (assume role) asks for a Formal label in Username and the role’s ARN in IAM Role ARN.

After creating a resource, the Formal console opens the Add Native User wizard automatically. Start at step three in that flow.

Configure the password of the native user

To configure the password of the native users, customers have the following options:

Password-based authentication

Set directly the password, Formal will keep it encrypted in the Control Plane and send it in the configuration of the Connectors.
Set it via an environment variable. You can specify the following value in the secret: ENV:NAME_OF_THE_ENV_VARIABLE_WITH_THE_PASSWORD_OF_THE_USER

Please make sure that the environment variable is set in the connector’s deployment.

IAM authentication

Instead of a stored password, the Connector can authenticate to the resource with a short-lived token minted from its own cloud identity in the environment where it runs. The secret value selects the cloud provider:

AWS: set the secret to iam to use the Connector’s ambient IAM role, or to an IAM role ARN (arn:aws:iam::<account>:role/<name>) to have the Connector assume that role first. The username is a database user configured for IAM authentication that the Connector’s role is granted rds-db:connect permission to connect as; it is not derived from the IAM identity.
GCP: set the secret to iam_gcp. The Connector authenticates to Cloud SQL with the service account resolved from its environment. That service account must be added as a Cloud SQL IAM user and granted the Cloud SQL instance-user role, and the username must match it (for a service account, the account email without the .gserviceaccount.com suffix).
Azure: set the secret to iam_azure. The Connector authenticates to Azure Database for PostgreSQL or MySQL Flexible Server with the Microsoft Entra identity resolved from its environment. The username is that identity’s Entra principal name, such as a user principal name or a managed identity name, provisioned as a login on the database.

Determine a Native User for a Formal User or Group

You can assign a native user to a Formal User or Group. This will override the default native user configured for the Resource.

Open the resource’s Authentication tab and select the Native User.
Under Linked Identities, click Add beside Formal Users or Formal Groups.
Select one or more identities, then click Add.

Create a native user

Use the formal_native_user resource to create a native user:

resource "formal_native_user" "example" {
  native_user_id   = "readonly"
  native_user_secret = "secure_password_123"
  resource_id      = "resource-123"
  use_as_default   = true
  termination_protection = false
}

Resource Schema

Required Arguments

native_user_id (String) - The upstream username, or a descriptive label for technologies such as AWS that do not use an upstream username
native_user_secret (String, Sensitive) - The upstream password or a technology-specific credential configuration, such as iam or an AWS IAM role ARN
resource_id (String) - The Sidecar ID for the resource this native user is for

Optional Arguments

termination_protection (Boolean) - If set to true, this native user cannot be deleted
use_as_default (Boolean) - Whether the connector uses this native user when a connection does not name one. Defaults to false, so set it on one native user per resource, otherwise connections that do not name a native user and match no link will fail

Read-Only Attributes

id (String) - The ID of the native user

Examples

Environment

resource "formal_native_user" "readonly_user" {
  native_user_id   = "readonly"
  native_user_secret = "ENV:DB_READONLY_PASSWORD"
  resource_id      = var.resource_id
  use_as_default   = true
}

IAM

AWS

Use the Connector’s ambient IAM role:

resource "formal_native_user" "iam_user" {
  native_user_id   = "iam_user"
  native_user_secret = "iam"
  resource_id      = var.resource_id
  use_as_default   = false
}

Assume a specific IAM role:

resource "formal_native_user" "custom_role_user" {
  native_user_id   = "custom_role"
  native_user_secret = "arn:aws:iam::123456789012:role/formal-db-role"
  resource_id      = var.resource_id
  use_as_default   = false
}

GCP

resource "formal_native_user" "gcp_iam_user" {
  native_user_id   = "readonly@my-project.iam"
  native_user_secret = "iam_gcp"
  resource_id      = var.resource_id
  use_as_default   = false
}

Azure

resource "formal_native_user" "azure_iam_user" {
  native_user_id   = "user@tenant.onmicrosoft.com"
  native_user_secret = "iam_azure"
  resource_id      = var.resource_id
  use_as_default   = false
}

Determine a Native User for a Formal User or Group

You can assign a native user to a Formal User or Group. This will override the default native user configured for the Resource.

resource "formal_native_user_link" "group_native_user_assignment" {
  formal_identity_id = "user_123456abcdef" # formal_user.id, not formal_user.db_username
  formal_identity_type = "user"
  native_user_id = "nativeuser_123456abcdef" # formal_native_user.id, not formal_native_user.native_user_id
}

Verify:

terraform plan
terraform apply

Control Which Credentials are Used Between the Connector and the Resource

There are three ways to control which credentials are passed between a Connector and Resource for individual requests:

Assign native users to Formal identities in the Control Plane
Specify the native user at connection time
Use resource credentials at connection time

Assign Native Users to Formal Identities in the Control Plane

If Formal credentials are passed at connection time, the Connector will determine the relevant native user using the Formal identity. Specify which native user to use via the Formal console or via Terraform.

Specify the Native User at Connection Time

To connect using a specific native user, use the following format for your connection username:

<formal_username>@<native_user>

For example, if the user john@joinformal.com wants to connect to a Postgres database using the native user readonly, the connection username would be:

idp:formal:human:john@joinformal.com@readonly

Example PostgreSQL connection command:

psql -h HOSTNAME_OF_CONNECTOR -p 5432 -d DATABASE_NAME -U "idp:formal:human:john@joinformal.com@readonly"

Example MySQL connection command:

mysql -h HOSTNAME_OF_CONNECTOR -P 3306 -u "idp:formal:human:john@joinformal.com@readonly" -p

Use Resource Credentials at Connection Time

Although not recommended, Formal identities can also pass the credentials of the resource at connection time. In that case, the Connector will transparently forward these credentials to the resource.

Understanding Native Users in Logs

If formal identities are used at connection time, the resulting native user username will be specified at user.formal.native. If formal identities are not used, user.type will be native and the username (if applicable) will be specified in user.username. Accessing resources using native resource role credentials means that the user type will be native instead of formal and the formal user information will be empty. In addition, the native resource role’s username will be specified at the user.username level in logs but user.native will be absent.

Access Control

You can control which users can access which native users through Formal policies. In particular, you can control which users can access specific native users when they attempt to connect using the @<native_user> syntax. This is useful for enforcing least-privilege access and preventing users from accessing highly privileged accounts. The following policy blocks the user john@joinformal.com from using the native user devops:

package formal.v2

import future.keywords.if
import future.keywords.in

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  input.native_user == "devops"
  input.user.email == "john@joinformal.com"
}

You can extend this pattern to:

Block multiple users from specific native users
Allow only certain users to access privileged native users
Require additional authentication for certain native users

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Create a native user

Configure the password of the native user

Password-based authentication

IAM authentication

Determine a Native User for a Formal User or Group

Create a native user

Resource Schema

Required Arguments

Optional Arguments

Read-Only Attributes

Examples

Environment

IAM

AWS

GCP

Azure

Determine a Native User for a Formal User or Group

Control Which Credentials are Used Between the Connector and the Resource

Assign Native Users to Formal Identities in the Control Plane

Specify the Native User at Connection Time

Use Resource Credentials at Connection Time

Understanding Native Users in Logs

Access Control

​Create a native user

​Configure the password of the native user

​Password-based authentication

​IAM authentication

​Determine a Native User for a Formal User or Group

​Create a native user

​Resource Schema

​Required Arguments

​Optional Arguments

​Read-Only Attributes

​Examples

​Environment

​IAM

​AWS

​GCP

​Azure

​Determine a Native User for a Formal User or Group

​Control Which Credentials are Used Between the Connector and the Resource

​Assign Native Users to Formal Identities in the Control Plane

​Specify the Native User at Connection Time

​Use Resource Credentials at Connection Time

​Understanding Native Users in Logs

​Access Control

Create a native user

Configure the password of the native user

Password-based authentication

IAM authentication

Determine a Native User for a Formal User or Group

Create a native user

Resource Schema

Required Arguments

Optional Arguments

Read-Only Attributes

Examples

Environment

IAM

AWS

GCP

Azure

Determine a Native User for a Formal User or Group

Control Which Credentials are Used Between the Connector and the Resource

Assign Native Users to Formal Identities in the Control Plane

Specify the Native User at Connection Time

Use Resource Credentials at Connection Time

Understanding Native Users in Logs

Access Control