Skip to content

Users

Users are utilized to access organization resources.

Actions available to a given user depend on the attached permission set.

Passwords

If user has their password attached to their account, they can use it to access Document Rails.

Superadmins can disable password-based authentication for a given user at any time.

import { loginWithPassword } from "@vaultie/document-rails";

const response = await loginWithPassword(client, {
    email: "...",
    password: "...",
});

Permissions

All protected Document Rails endpoints require authorization using the role-based system.

Initially, all tenancies have one user with the superadmin permission. This user, in turn, is utilized to bootstrap other, purpose-specific user accounts.

For more information about how to configure user roles, see the roles documentation page.

SSO authentication

Dashboard authentication

Document Rails supports SSO authentication using organization-wide third-party SSO providers.

These SSO providers are meant to be used by regular dashboard users, not for machine-to-machine authentication. For machine-to-machine authentication, see service accounts.

Superadmins can configure SSO providers using the following OpenID Connect options:

  • Client ID
  • Client secret
  • Claim list
  • Issuer URL
  • Display name

All SSO providers must support OpenID Connect Discovery.

Service accounts

Service accounts are utilized for machine-to-machine authentication and are configured organization-wide.

To configure service account connectors, superadmins have to provide the following configuration options:

  • JWT issuer

  • Trusted JWK set URL

To authenticate with the API using a service account, a machine-based actor has to provide a valid JWT token as a Bearer token in the Authorization header: Authorization: Bearer ....

This token has to contain the iss claim, which identifies the JWT issuer. The issuer will be matched against a list of existing service account connectors.

The JWT token also has to be signed with a trusted key contained within a configured trusted JWK set.

To determine the authenticated user, Document Rails utilizes the sub claim. Usually, it's a provider-specific unique user identifier.

Document Rails transforms the sub field into a randomized deterministic internal-only email address with the impressum.localdomain domain (e.g cf80cd8aed482d5...@impressum.localdomain).

If the user with a generated email does not exist, it will be created. Otherwise, Document Rails authenticates the machine as an existing user.

JWT token metadata

JWT tokens may contain additional fields that can be used for automatically adding the user to organizations, or for automatically providing users with superadmin privileges.

Document Rails supports the following custom JWT claims:

  • impressumRoles (string[]) - ensure the provided roles are available for the user. If the user already exists, this option does not change existing roles, only attaching the provided ones if they are missing.

  • impressumOrganizations (number[]) - change user organization membership. If the user already exists, removes them from all current organizations and attaches them to the provided ones.