---
type: Development Guide
title: Authenticate and Authorize Users in ScalarDB Analytics
description: ScalarDB Analytics can authenticate and authorize users with resource-level access control. You can create users and grant or revoke permissions on catalogs, data sources, namespaces, and tables. Roles can also be created to group...
resource: https://scalardb.scalar-labs.com/docs/3.18/scalardb-analytics/authentication-and-authorization/
tags:
- scalardb
- v3.18
- phase:implement
- section:develop
- edition:enterprise-option
status: stable
product: scalardb
product_title: ScalarDB
version: '3.18'
patch_version: 3.18.1
doc_id: scalardb-analytics/authentication-and-authorization
lifecycle_phase: implement
breadcrumb:
- Develop
- Run Analytical Queries
- Advanced Configurations and Operations
editions:
- Enterprise Option
generated:
  by: process:okf-build/1.0.0
  at: '2026-08-04T23:50:49Z'
sources:
- id: docs-scalardb
  resource: https://github.com/scalar-labs/docs-scalardb/blob/6126dfe2f56389351d88b134752618641f9771dd/versioned_docs/version-3.18/scalardb-analytics/authentication-and-authorization.mdx
  title: ScalarDB documentation source (MDX)
  author: process:scalar-labs/docs-scalardb
  last_modified: '2026-08-04T15:05:02Z'
---

# Authenticate and Authorize Users in ScalarDB Analytics

ScalarDB Analytics can authenticate and authorize users with resource-level access control. You can create users and grant or revoke permissions on catalogs, data sources, namespaces, and tables. Roles can also be created to group permissions and can be granted to users. This guide describes how to use authentication and authorization in ScalarDB Analytics.

## Authentication

ScalarDB Analytics authenticates users by verifying their username and password against a configured authentication backend. After successful authentication, the server issues an access token that the client uses for subsequent requests. Each user can have only one active access token at a time; authenticating again invalidates the previous token.

### Authentication backends

ScalarDB Analytics supports the following authentication backends:

- **Internal:** Manages user credentials directly within ScalarDB Analytics. Users are registered by using the `user register` CLI command, and their passwords are stored (hashed) in the ScalarDB Analytics metadata database. This is the default backend.
- **ScalarDB Cluster:** Delegates credential verification to an external ScalarDB Cluster instance. When a user logs in for the first time, ScalarDB Analytics automatically creates a corresponding user record (just-in-time provisioning). The `user register` and `user unregister` commands are not available with this backend because the user lifecycle is managed in ScalarDB Cluster.

You can configure the authentication backend by using the `scalar.db.analytics.server.auth.password.backend` server property. For details, see [Configurations](#configurations).

### Users

A user is an entity that can authenticate with ScalarDB Analytics and perform operations based on assigned permissions. Users can log in to ScalarDB Analytics with a username and a password and execute operations if they have the required permissions.

Authentication and authorization support two types of users:

- **Superusers:** This type of user has all permissions. Only superusers can create catalogs and manage users and roles.
- **Normal users:** This type of user initially doesn't have any permissions, so they need to be granted permissions by a superuser or a user with catalog-level admin permission.

### Initial admin user

When you enable authentication and authorization, ScalarDB Analytics creates an initial admin user and assigns a built-in superuser role to that user. The behavior differs depending on the authentication backend.

#### Internal backend

When the server starts, ScalarDB Analytics creates the user specified by `scalar.db.analytics.server.auth.initial_admin_username` with the password specified by `scalar.db.analytics.server.auth.password.internal.initial_admin_password` and assigns the SUPERADMIN role to that user. This assignment occurs only if no users are already assigned to the SUPERADMIN role. You can log in with this user and create other users if necessary.

#### ScalarDB Cluster backend

The server does not create any users at startup. Instead, when the user specified by `scalar.db.analytics.server.auth.initial_admin_username` logs in for the first time, ScalarDB Analytics automatically registers that user through just-in-time provisioning and assigns the SUPERADMIN role. This assignment occurs only if no users are already assigned to the SUPERADMIN role. Other users are also provisioned on first login, but they are not assigned the SUPERADMIN role.

### User management

When using the internal backend, you can register and unregister users by using the CLI:

```console
scalardb-analytics-cli user register -u alice -p
scalardb-analytics-cli user unregister -u alice
```

The following commands are available regardless of the authentication backend:

```console
scalardb-analytics-cli user list
scalardb-analytics-cli user describe -u alice
```

## Authorization

ScalarDB Analytics provides resource-level access control through roles and permissions. This section describes how to manage roles, permissions, and access control.

### Roles

A role is a named collection of permissions that can be granted to users. Using roles provides a convenient way to manage permissions for multiple users, rather than granting individual permissions to each user.

Only superusers can create, delete, or list roles. Only superusers can assign roles to users or remove role assignments.

#### SUPERADMIN role

SUPERADMIN is a built-in role that is automatically created when the server starts. Users assigned to the SUPERADMIN role bypass all access control checks and can perform any operation. In API responses, users assigned to the SUPERADMIN role are represented with the `is_superuser` flag set to `true`.

#### Role management

You can manage roles by using the following CLI commands:

```console
scalardb-analytics-cli role create -n analyst
scalardb-analytics-cli role delete -n analyst
scalardb-analytics-cli role list
scalardb-analytics-cli role grant -r analyst -u alice
scalardb-analytics-cli role revoke -r analyst -u alice
```

### Permissions

ScalarDB Analytics uses resource-level access control. Permissions are granted on a specific resource and apply to the operations associated with the resource type. When granting or revoking permissions through the CLI, you specify the resource type as a subcommand and the permission level with the `-p` option.

The valid `-p` values depend on the resource type:

- **Catalog:** `read`, `write`, or `admin`
- **Data source:** `read` or `admin`
- **Namespace:** `read`
- **Table:** `read`

The following permissions are available:

| Permission          | Resource type | `-p` value | Description                                                                        |
|:--------------------|:--------------|:-----------|:-----------------------------------------------------------------------------------|
| `CATALOG_READ`      | Catalog       | `read`     | Read catalog metadata.                                                             |
| `CATALOG_WRITE`     | Catalog       | `write`    | Create or modify resources within a catalog (for example, register a data source). |
| `CATALOG_ADMIN`     | Catalog       | `admin`    | Delete a catalog and manage permissions on resources within the catalog.            |
| `DATA_SOURCE_READ`  | Data source   | `read`     | Read data source metadata.                                                         |
| `DATA_SOURCE_ADMIN` | Data source   | `admin`    | Delete a data source.                                                              |
| `NAMESPACE_READ`    | Namespace     | `read`     | Read namespace metadata.                                                           |
| `TABLE_READ`        | Table         | `read`     | Read table metadata.                                                               |

#### Resource hierarchy

Resources in ScalarDB Analytics are organized in a hierarchy. Permissions granted at a higher level in the hierarchy apply to all resources below that level.

```
System (SUPERADMIN only)
  └── Catalog
        └── Data source
              └── Namespace
                    └── Table
```

Permissions granted at a higher level propagate to all resources below that level. For example, granting `CATALOG_READ` on a catalog allows the user to read metadata for all data sources, namespaces, and tables within that catalog. However, the specific permissions required for each operation are defined individually. For details, see [Which permissions are required for each type of operation](#which-permissions-are-required-for-each-type-of-operation).

#### Direct and role-based grants

Permissions can be granted in two ways:

- **Direct grants:** A permission is granted directly to a specific user on a specific resource.
- **Role-based grants:** A permission is granted to a role on a specific resource. All users assigned to that role receive the permission.

A user's effective permissions are the union of all directly granted permissions and all permissions from assigned roles.

#### Permission management

You can grant and revoke permissions by specifying the resource type, the target resource, and the permission level. Permissions can be granted to a user (`--user`) or a role (`--role`).

Grant a permission to a user:

```console
scalardb-analytics-cli permission grant catalog --catalog my_catalog --user alice -p read
```

Grant a permission to a role:

```console
scalardb-analytics-cli permission grant catalog --catalog my_catalog --role analyst -p read
```

For data sources, namespaces, and tables, specify the parent resources:

```console
scalardb-analytics-cli permission grant data-source \
  --catalog my_catalog --data-source my_ds --user alice -p read

scalardb-analytics-cli permission grant namespace \
  --catalog my_catalog --data-source my_ds --namespace my_ns --user alice -p read

scalardb-analytics-cli permission grant table \
  --catalog my_catalog --data-source my_ds --namespace my_ns --table my_tbl \
  --user alice -p read
```

Revoke a permission:

```console
scalardb-analytics-cli permission revoke catalog --catalog my_catalog --user alice -p read
```

List the effective permissions for a user:

```console
scalardb-analytics-cli permission list -u alice
```

Users who hold `CATALOG_ADMIN` on a catalog can grant and revoke permissions on any resource within that catalog. Superusers can manage permissions on all resources.

#### Which permissions are required for each type of operation

The following table shows which permissions satisfy the authorization requirement for each operation. For operations that involve a resource hierarchy, the system checks permissions at each level, starting from the target resource and moving up to the catalog level. A match at any level is sufficient.

:::note

When [ScalarDB authorization delegation](#scalardb-authorization-delegation) is enabled, namespace-level and table-level authorization for ScalarDB data sources (databases that ScalarDB Cluster manages) is delegated to ScalarDB Cluster instead of following the permissions listed in the table below.

:::

| Operation                       | Satisfying permissions                                                                                                                      |
|:--------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------|
| Create a catalog                | SUPERADMIN only                                                                                                                             |
| Find a catalog                  | `CATALOG_READ` or `CATALOG_ADMIN` on the catalog                                                                                            |
| List catalogs                   | Same as find a catalog (results are filtered)                                                                                               |
| Initialize a catalog            | `CATALOG_WRITE` or `CATALOG_ADMIN` on the catalog                                                                                           |
| Delete a catalog                | `CATALOG_ADMIN` on the catalog                                                                                                              |
| Register a data source          | `CATALOG_WRITE` or `CATALOG_ADMIN` on the parent catalog                                                                                    |
| Find a data source              | `DATA_SOURCE_READ` or `DATA_SOURCE_ADMIN` on the data source, or `CATALOG_READ` or `CATALOG_ADMIN` on the parent catalog                    |
| List data sources               | Same as find a data source (results are filtered)                                                                                           |
| Delete a data source            | `DATA_SOURCE_ADMIN` on the data source, or `CATALOG_ADMIN` on the parent catalog                                                            |
| Describe a namespace            | `NAMESPACE_READ` on the namespace, `DATA_SOURCE_READ` or `DATA_SOURCE_ADMIN` on the parent data source, or `CATALOG_READ` or `CATALOG_ADMIN` on the parent catalog |
| List namespaces                 | Same as describe a namespace (results are filtered)                                                                                         |
| Describe a table                | `TABLE_READ` on the table, `NAMESPACE_READ` on the parent namespace, `DATA_SOURCE_READ` or `DATA_SOURCE_ADMIN` on the parent data source, or `CATALOG_READ` or `CATALOG_ADMIN` on the parent catalog |
| List tables                     | Same as describe a table (results are filtered)                                                                                             |
| Register or unregister a user   | SUPERADMIN only                                                                                                                             |
| Create, delete, or list roles   | SUPERADMIN only                                                                                                                             |
| Grant or revoke a role          | SUPERADMIN only                                                                                                                             |
| Grant or revoke a permission    | `CATALOG_ADMIN` on the target catalog, or SUPERADMIN                                                                                        |
| List permissions                | Same as the corresponding read operation for the resource                                                                                   |

### ScalarDB authorization delegation

When you use ScalarDB Cluster as the authentication backend, you can optionally delegate namespace-level and table-level authorization for ScalarDB data sources (databases that ScalarDB Cluster manages) to ScalarDB Cluster. This means that the privilege system in ScalarDB Cluster becomes the single source of truth for access control on ScalarDB data, eliminating the need to manage permissions in two places.

#### How delegation works

When authorization delegation is enabled, ScalarDB Analytics checks ScalarDB Cluster privileges (specifically, the `READ` privilege) instead of its own access control entries for namespace and table operations on ScalarDB data sources. Catalog-level and data source-level authorization remains under ScalarDB Analytics access control regardless of delegation settings.

#### Prerequisites

To use ScalarDB authorization delegation, the following conditions must be met:

- The authentication backend must be set to `scalardb-cluster`.
- The `scalar.db.analytics.server.auth.password.scalardb_cluster.acl_delegation` property must be set to `true`.
- The user must have been authenticated through the ScalarDB Cluster backend.

#### Authorization responsibility by resource level

The following table shows which system is responsible for authorization at each resource level when authorization delegation is enabled or disabled.

| Resource level                | Delegation enabled | Delegation disabled |
|:------------------------------|:-------------------|:--------------------|
| Catalog                       | ScalarDB Analytics | ScalarDB Analytics  |
| Data source                   | ScalarDB Analytics | ScalarDB Analytics  |
| Namespace (managed by ScalarDB Cluster)          | ScalarDB Cluster   | ScalarDB Analytics  |
| Table (managed by ScalarDB Cluster)              | ScalarDB Cluster   | ScalarDB Analytics  |
| Namespace (not managed by ScalarDB Cluster)      | ScalarDB Analytics | ScalarDB Analytics  |
| Table (not managed by ScalarDB Cluster)          | ScalarDB Analytics | ScalarDB Analytics  |

:::note

Only ScalarDB data sources support authorization delegation. Other data source types always use ScalarDB Analytics access control.

:::

## Configurations

This section describes the available configurations for authentication and authorization.

### ScalarDB Analytics server configurations

To enable authentication and authorization, you need to set `scalar.db.analytics.server.auth.enabled` to `true`.

#### `enabled`

- **Field:** `scalar.db.analytics.server.auth.enabled`
- **Description:** Whether authentication and authorization are enabled.
- **Default value:** `false`

You can also set the following configurations:

#### `initial_admin_username`

- **Field:** `scalar.db.analytics.server.auth.initial_admin_username`
- **Description:** The username of the initial admin user who will be assigned the SUPERADMIN role.
- **Default value:** None

#### `password.backend`

- **Field:** `scalar.db.analytics.server.auth.password.backend`
- **Description:** The authentication backend to use (`internal` or `scalardb-cluster`).
- **Default value:** `internal`

#### `password.token_ttl_seconds`

- **Field:** `scalar.db.analytics.server.auth.password.token_ttl_seconds`
- **Description:** The time-to-live (TTL) of access tokens in seconds.
- **Default value:** `86400`

#### `password.internal.initial_admin_password`

- **Field:** `scalar.db.analytics.server.auth.password.internal.initial_admin_password`
- **Description:** The initial password for the admin user. Only used when `auth.password.backend` is set to `internal`.
- **Default value:** None

If you use `scalardb-cluster` as the authentication backend, you can also set the following configurations:

#### `password.scalardb_cluster.host`

- **Field:** `scalar.db.analytics.server.auth.password.scalardb_cluster.host`
- **Description:** The hostname or IP address of the ScalarDB Cluster instance.
- **Default value:** `localhost`

#### `password.scalardb_cluster.port`

- **Field:** `scalar.db.analytics.server.auth.password.scalardb_cluster.port`
- **Description:** The port number of the ScalarDB Cluster instance.
- **Default value:** `60053`

#### `password.scalardb_cluster.deadline_millis`

- **Field:** `scalar.db.analytics.server.auth.password.scalardb_cluster.deadline_millis`
- **Description:** The gRPC deadline in milliseconds for authentication requests to ScalarDB Cluster.
- **Default value:** `5000`

#### `password.scalardb_cluster.acl_delegation`

- **Field:** `scalar.db.analytics.server.auth.password.scalardb_cluster.acl_delegation`
- **Description:** Whether to delegate namespace-level and table-level authorization for ScalarDB data sources to ScalarDB Cluster. For details, see [ScalarDB authorization delegation](#scalardb-authorization-delegation).
- **Default value:** `false`

#### `password.scalardb_cluster.tls.enabled`

- **Field:** `scalar.db.analytics.server.auth.password.scalardb_cluster.tls.enabled`
- **Description:** Whether to enable TLS for the connection to ScalarDB Cluster.
- **Default value:** `false`

#### `password.scalardb_cluster.tls.ca_root_cert_path`

- **Field:** `scalar.db.analytics.server.auth.password.scalardb_cluster.tls.ca_root_cert_path`
- **Description:** Path to the CA root certificate file for verifying the ScalarDB Cluster server certificate.
- **Default value:** None

#### `password.scalardb_cluster.tls.override_authority`

- **Field:** `scalar.db.analytics.server.auth.password.scalardb_cluster.tls.override_authority`
- **Description:** Override the server authority for TLS verification of the ScalarDB Cluster connection.
- **Default value:** None

### CLI client configurations

To authenticate with the ScalarDB Analytics server, configure the client credentials by using a properties file or environment variables.

#### `username`

- **Field:** `scalar.db.analytics.client.auth.username`
- **Description:** The username for authenticating with the ScalarDB Analytics server.
- **Default value:** None

#### `password`

- **Field:** `scalar.db.analytics.client.auth.password`
- **Description:** The password for authenticating with the ScalarDB Analytics server.
- **Default value:** None

You can also set credentials by using environment variables, which take precedence over configuration file properties.

#### `SCALAR_DB_ANALYTICS_CLIENT_AUTH_USERNAME`

- **Description:** The username for authentication.

#### `SCALAR_DB_ANALYTICS_CLIENT_AUTH_PASSWORD`

- **Description:** The password for authentication.

### Spark configurations

To authenticate Spark applications with the ScalarDB Analytics server, add the following properties to your Spark configuration. Replace `<catalog-name>` with the name of your catalog.

#### `username`

- **Field:** `spark.sql.catalog.<catalog-name>.server.auth.username`
- **Description:** The username for authenticating the Spark application with the ScalarDB Analytics server.
- **Default value:** None

#### `password`

- **Field:** `spark.sql.catalog.<catalog-name>.server.auth.password`
- **Description:** The password for authenticating the Spark application with the ScalarDB Analytics server.
- **Default value:** None

## Wire encryption

If you enable authentication and authorization, you must also enable TLS to protect user credentials in transit. For details about TLS configuration, see [ScalarDB Analytics Configurations](./configurations.md).

## Next steps

- [ScalarDB Analytics Configurations](./configurations.md) - View all available configuration options
- [Create a ScalarDB Analytics Catalog](./create-scalardb-analytics-catalog.md) - Learn how to create catalogs and add data sources
