Skip to main content
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.
S3 and gRPC Resources do not support Native Users. For S3, the Connector automatically uses AWS credentials provided via the Instance Metadata Service (IMDS), environment variables, or Pod Identity. See the AWS S3 documentation for more details on S3 authentication.For gRPC, 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

  1. Navigate to the Resources app. In the list of Resources, click on the arrow at the end of the row corresponding to the desired Resource to which you wish to create a native user.
  2. Scroll down to the Native User section and click on the New Native User button.
  3. Complete the form by entering the username and password for the native user role.

​
Configure the password of the native user

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

​
Password-based authentication

  1. Set directly the password, Formal will keep it encrypted in the control plane and send it in the configuration of the Connectors.
  2. 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

  1. Set the value iam for the secret, the Connector will attempt to connect via the IAM role of the running environment. You need to make sure that the Connector has the required permissions.
  2. Use IAM authentication with a custom role, the Connector will assume the specified IAM role to connect to the Resource. The value should be the ARN of the IAM role.

​
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.
  1. Navigate to the list of native users in the details of the Resource.
  2. Under Use for Formal Users or Use for Formal Groups, select the desired Formal User or Group by clicking on the input and clicking on add next to the desired Formal User or Group.

​
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:
  1. Assign native users to Formal identities in the control plane
  2. Specify the native user at connection time
  3. 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 deetermine the relevant native user using the Formal identity. Specify which native user to use via the control plane 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 applicalbe) 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