Home  /  Manage Materialize  /  User and service accounts

Create service accounts

It’s a best practice to use service accounts (i.e., non-human users) to connect external applications and services to Materialize. As an administrator of a Materialize organization, you can create service accounts manually via the Materialize Console or programatically via Terraform.

More granular permissions for the service account can then be configured using role-based access control (RBAC).

NOTE:

  • The new account creation is not finished until the first time you connect with the account.

  • The first time the account connects, a database role with the same name as the specified service account User is created, and the service account creation is complete.

Materialize Console

  1. Log in to the Materialize Console.

  2. In the side navigation bar, click + Create New > App Password.

  3. In the New app password modal, specify the type and required field(s):

    Field Details
    Type Select Service
    Name Specify a descriptive name.
    User Specify a service account user name. If the specified account user does not exist, it will be automatically created the first time the application connects with the user name and password.
    Roles

    Select the organization role:

    Organization role Description
    Organization Admin

    • Console access: Has access to all Materialize console features, including administrative features (e.g., invite users, create service accounts, manage billing, and organization settings).

    • Database access: Has superuser privileges in the database.
    Organization Member

    • Console access: Has no access to Materialize console administrative features.

    • Database access: Inherits role-level privileges defined by the PUBLIC role; may also have additional privileges via grants or default privileges. See Access control control.
    NOTE:

    • The first user for an organization is automatically assigned the Organization Admin role.

    • An Organization Admin has superuser privileges in the database. Following the principle of least privilege, only assign Organization Admin role to those users who require superuser privileges.

    • Users/service accounts can be granted additional database roles and privileges as needed.

  4. Click Create Password to generate a new password for your service account.

  5. Store the new password securely.

    NOTE: Do not reload or navigate away from the screen before storing the password. This information is not displayed again.

  6. Connect with the new service account to finish creating the new account.

    NOTE:

    • The new account creation is not finished until the first time you connect with the account.

    • The first time the account connects, a database role with the same name as the specified service account User is created, and the service account creation is complete.

    1. Find your new service account in the App Passwords table.

    2. Click on the Connect button to get details on connecting with the new account.

        If you have psql installed:

        1. Click on the Terminal tab.
        2. From a terminal, connect using the psql command displayed.
        3. When prompted for the password, enter the app’s password.

        The first time the account connects, a database role with the same name as the specified service account User is created, and the service account creation is complete.

        To use a different client to connect,

        1. Click on the External tools tab to get the connection details.

        2. Update the client to use these details and connect.

        The first time the account connects, a database role with the same name as the specified service account User is created, and the service account creation is complete.

    Terraform

    Minimum requirements: terraform-provider-materialize v0.8.1+

    1. Create a new service user using the materialize_role resource:

      resource "materialize_role" "production_dashboard" {
  name   = "svc_production_dashboard"
  region = "aws/us-east-1"
}

    2. Create a new service app password using the materialize_app_password resource, and associate it with the service user created in the previous step:

      resource "materialize_app_password" "production_dashboard" {
  name = "production_dashboard_app_password"
  type = "service"
  user = materialize_role.production_dashboard.name
  roles = ["Member"]
}

    3. Optionally, associate the new service user with existing roles to grant it existing database privileges.

      resource "materialize_database_grant" "database_usage" {
  role_name     = materialize_role.production_dashboard.name
  privilege     = "USAGE"
  database_name = "production_analytics"
  region        = "aws/us-east-1"
}

    4. Export the user and password for use in the external application or service.

      output "production_dashboard_user" {
  value = materialize_role.production_dashboard.name
}
output "production_dashboard_password" {
  value = materialize_app_password.production_dashboard.password
}

    For general guidance on using the Materialize Terraform provider to manage resources in your region, see the reference documentation.

    Next steps

    The organization role for a user/service account determines the default level of database access. Once the account creation is complete, you can use role-based access control (RBAC) to control access for that account.
    Back to top ↑