> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provisionr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication & Authorization

> Provisionr authenticates every human through SSO and secures API access with service accounts, personal access tokens, and fine-grained RBAC roles and permissions.

Now that you've seen how Provisionr keeps access in sync across your connected systems, the next question is who can access Provisionr itself, and what they can do once they're in. People sign in through your single sign-on (SSO) provider, scripts and services call the API with tokens, and roles decide what each of them is allowed to see and change.

This page covers access to your workspace in this order:

* How people sign in, and how their user accounts are created
* How the API authenticates personal access tokens and service accounts
* How permissions and roles are named, and which roles every new user receives

***

## Single Sign-On (SSO)

Provisionr uses your single sign-on (SSO) provider to authenticate every person who signs in. When someone signs in, the SSO authentication response includes their SSO provider ID, their first and last name, and their email address, and we encrypt these values before we save them in the Provisionr database.

You can choose either of these vendors when you install Provisionr:

* Google
* Okta Workforce Identity

We may add more vendors in the future if they are a [supported provider](https://www.socialiteproviders.com). If your SSO provider isn't supported, you can sign up for a free Okta Customer Identity (Auth0) account, which supports native integrations with a wider range of vendors.

### Password Management

Since we rely on your SSO provider for authentication, Provisionr doesn't manage or store any passwords. You configure password policies in your SSO provider, and you can also configure passkey support there for a smoother sign-in experience.

### Two-Factor Authentication

Two-factor authentication is handled by your SSO provider as well. You can configure two-factor policies there and assign them to the Provisionr application configuration in your SSO provider.

## User Management

We create each user account just-in-time, the first time that a person authenticates with SSO using OpenID Connect (OIDC). We don't currently support SCIM provisioning or deprovisioning.

Today, the account that a person signs in with, which we call an Authentication User or Auth User, is separate from their [Directory User](https://docs.provisionr.io/concepts/control/users.md). We plan to link the two in a future release, and the [Feature Roadmap](https://docs.provisionr.io/roadmap/features.md) is where we share planned work. Once they're linked, we'll be able to create an Auth User automatically when a person is provisioned in an integration such as Okta. Because the Auth User will be tied to the Directory User, we'll also be able to deprovision it along with the many other resources and user accounts that have been provisioned for that person over time.

## API Authentication

The API authenticates requests with access tokens and refresh tokens, and each token belongs to either a service account or a user account. [Authentication](https://docs.provisionr.io/api/workspace/v1/authentication.md) in the API reference shows how to send a token with each request.

Every endpoint is also tied to a permission, and the service account or user has to be granted that permission before it can use the endpoint. In other words, a token can only reach the endpoints that its owner's permissions allow. [Roles and Permissions](#roles-and-permissions) describes how those permissions are named and grouped.

Each kind of token has its own lifetime, which matches how it's used.

| Token | Used for | Lifetime |
| - | - | - |
| CLI access token | Each request that the CLI makes on your behalf | 60 minutes |
| CLI refresh token | Getting a new CLI access token without signing in again | 30 days |
| Personal access token (PAT) | Testing an endpoint | 4 hours |
| Service account access token | Each request that a script or service makes | 90 days by default, and no more than 90 days |

### Personal Access Tokens (PAT)

When you need to test a GET, POST, PATCH, or DELETE endpoint, you can use a personal access token (PAT). Creating one requires the `wks.access.pat` role, which every new user receives by [default](#default-roles).

A Provisionr PAT is valid for only 4 hours, because it's designed for testing rather than for lasting access with the full level of permissions that your user account has. The short lifetime discourages the practice of an engineer putting a PAT in a script or service, which should use a [service account](#service-accounts) instead.

## Service Accounts

A service account gives a script or vendor service non-human, machine-to-machine access to the API, with granular permissions. It's similar to a user account, except that it can only authenticate with API tokens, so there's no UI experience or SSO for a service account. Service accounts are for inbound requests, which are the calls that your scripts or vendor services make to the Provisionr API.

The default permissions of a service account only include the ability to run an authentication test. From there, you grant it the permissions for the endpoints that it actively uses. Since permissions map nearly one-to-one to URL endpoints, a service account can be granted access to exactly the endpoints it needs and nothing more.

### Service Account Managers

Each service account has users associated with it who have permission to manage it. We call these users **Service Account Managers**, and their roles support least privilege and separation of duties, because the people who grant a service account's permissions don't have to be the people who handle its tokens.

| Role | What it allows |
| - | - |
| `admin` | Can view and manage the service account, its permissions, its tokens, and its logs |
| `permission` | Can view the service account and change its permissions, but can't view or manage its tokens |
| `token` | Can view the service account and its permissions, and can generate and revoke its tokens |
| `audit` | Can view the service account, its permissions, and its logs, but can't make any changes or view or manage its tokens |

> [!TIP]
>
> Service Account Managers separate the authority to change what a service account can do from the authority to issue its credentials. A person with the `permission` role cannot view or manage tokens, and a person with the `token` role cannot change permissions, so when the two roles are held by different people, no one person can both widen a service account's access and obtain a credential to use it. The `audit` role gives reviewers read-only visibility into the service account and its permissions without access to its tokens.

### Service Account Tokens

A service account authenticates with an access token, which lasts 90 days by default. You can set an earlier expiration date when you create the token, but not a later one.

A service account token that goes unused for 30 days is treated as dormant. We refuse a dormant token the next time it's presented and deactivate it, and the `workspace.service.access.token.deactivating.inactivity` event in the [event log](https://docs.provisionr.io/concepts/workspace/logs.md) records that it happened. This means that a token left behind by a retired script can't be picked up and used later. A token that has never been used counts from the day it was created.

## Roles and Permissions

Provisionr has fine-grained access control, using roles and permissions that are assigned to people and to service accounts. Each permission allows one action on one kind of record, and each role groups the permissions that a particular kind of person needs.

### Permission Schema

Every permission name follows the pattern `wks.{namespace}.{entity}.{action}`. The `wks.` prefix marks it as a workspace permission, and the rest reads from the general to the specific in the same way as [event types](https://docs.provisionr.io/concepts/workspace/logs.md#event-types). For example, these are the permissions for the actions on a Directory Attribute:

* `wks.directory.attribute.view`, which applies to both list and describe
* `wks.directory.attribute.export`
* `wks.directory.attribute.create`
* `wks.directory.attribute.update`
* `wks.directory.attribute.activate`
* `wks.directory.attribute.deprecate`
* `wks.directory.attribute.deactivate`

When a record has sensitive data in its child relationships, which are usually many-to-many relationships, we add another level to the permission, such as `wks.workspace.role.user.view` for the users who hold a role. If the child relationship data isn't sensitive, we use either the related record's permission or the parent record's permission, depending on the use case.

### Role Schema

We were inspired by [Google Cloud Platform (GCP) IAM roles](https://cloud.google.com/iam/docs/understanding-roles#predefined_roles), and we've created a standardized schema for role-based access control (RBAC) with the permissions that people need already defined. People are only assigned to roles with predefined permissions, and never to permissions directly.

### Role Personas

Entity roles and global roles are each built around one of five personas, which describe the kind of person the role is meant for.

| Persona | Description |
| - | - |
| Admin | Can perform all actions. Intended for change management practitioners or system administrators. |
| Ops | Can make day-to-day changes and get things up and running. |
| Contributor | Can view records and create them in a draft state, but can't update, activate, deprecate, or deactivate them. |
| Auditor | Read-only, with export permissions, for audit, compliance, and security assurance engineers. |
| Viewer | Read-only, for exploring what is configured. Some companies restrict this persona to specific users, while others make it available to all employees for self-service information. |

### Role and Permission Mapping

This table shows which actions each persona's role includes. Each entity only has the actions that apply to it, so a Directory Identity, for example, only has `view`.

| Permission | Admin | Ops | Contributor | Auditor | Viewer |
| - | - | - | - | - | - |
| `wks.{namespace}.{entity}.view` | | | | | |
| `wks.{namespace}.{entity}.export` | | | | | |
| `wks.{namespace}.{entity}.create` | | | | | |
| `wks.{namespace}.{entity}.monitor` | | | | | |
| `wks.{namespace}.{entity}.manage` | | | | | |
| `wks.{namespace}.{entity}.update` | | | | | |
| `wks.{namespace}.{entity}.activate` | | | | | |
| `wks.{namespace}.{entity}.deprecate` | | | | | |
| `wks.{namespace}.{entity}.deactivate` | | | | | |
| `wks.{namespace}.{entity}.sync` | | | | | |

The maintenance namespace has its own actions. Its admin and ops roles can work with the cache, the queue, and database migrations, and every maintenance role can read the event log through `wks.maintenance.log`, which the [event log API](https://docs.provisionr.io/concepts/workspace/logs.md#rest-api) requires.

### Entity Roles

An entity role applies a persona to a single entity, and its name adds the persona to the entity's namespace and name.

| Schema | Example |
| - | - |
| `wks.{namespace}.{entity}.admin` | `wks.directory.attribute.admin` |
| `wks.{namespace}.{entity}.ops` | `wks.directory.attribute.ops` |
| `wks.{namespace}.{entity}.contributor` | `wks.directory.attribute.contributor` |
| `wks.{namespace}.{entity}.auditor` | `wks.directory.attribute.auditor` |
| `wks.{namespace}.{entity}.viewer` | `wks.directory.attribute.viewer` |

### Global Roles

A global role applies a persona without restriction, across every namespace and entity, so each one carries far more risk than an entity role. The table shows the risk level of each global role, along with guidance on who should hold it.

> [!WARNING]
>
> If your IT or Security team has a secondary admin or elevated account, it's best practice to assign global roles to that account rather than to the person's primary account.

| Global Role | Risk Level | Description |
| - | - | - |
| `wks.global.admin` | Insane | Unrestricted access to every action. Equivalent to a break-glass root account. Assign to fewer than 5 people. |
| `wks.global.ops` | Extreme | Unrestricted read-write for day-to-day operations, without export. Assign to fewer than 25 people. |
| `wks.global.contributor` | High | Unrestricted read, and can create records in a draft state in every namespace. |
| `wks.global.auditor` | Moderate | Unrestricted read-only with export. For audit, compliance, and security assurance engineers. |
| `wks.global.viewer` | Moderate | Unrestricted read-only without export. For IAM stakeholders who need visibility into configuration. Can also be assigned to most employees if your organization encourages transparency. |

### Default Roles

When a new user authenticates for the first time, we assign them the roles in this table by default.

| Role | Description |
| - | - |
| `wks.access.ui` | Can log in to the UI and view the dashboard. Each page is restricted based on the user's roles and permissions. |
| `wks.access.pat` | Can create short-lived personal access tokens (PATs) for API access to the API endpoints their roles allow. |
| `wks.access.cli` | Can authenticate with the CLI using their user account, with access to the API endpoints their roles allow. |
| `wks.access.doc` | Can view the workspace's built-in API documentation. |
| `wks.workspace.abbreviation.viewer` | Can view the abbreviations used for short-hand handle calculation. |
| `wks.workspace.role.viewer` | Can view Roles & Permissions to see which additional roles they can request access to. |

### Default Role Catalog

Provisionr has a default catalog of roles and permissions that you can assign to users, and you can also create custom roles with specific permissions as you need them.

```json List of Provisionr Roles theme={null}
[
    "wks.access.api",
    "wks.access.cli",
    "wks.access.doc",
    "wks.access.pat",
    "wks.access.svc",
    "wks.access.ui",
    "wks.aws.identity.group.admin",
    "wks.aws.identity.group.auditor",
    "wks.aws.identity.group.contributor",
    "wks.aws.identity.group.ops",
    "wks.aws.identity.group.viewer",
    "wks.directory.attribute.admin",
    "wks.directory.attribute.auditor",
    "wks.directory.attribute.contributor",
    "wks.directory.attribute.ops",
    "wks.directory.attribute.viewer",
    "wks.directory.dimension.admin",
    "wks.directory.dimension.auditor",
    "wks.directory.dimension.contributor",
    "wks.directory.dimension.ops",
    "wks.directory.dimension.viewer",
    "wks.directory.identity.admin",
    "wks.directory.identity.auditor",
    "wks.directory.identity.contributor",
    "wks.directory.identity.ops",
    "wks.directory.identity.viewer",
    "wks.directory.user.admin",
    "wks.directory.user.auditor",
    "wks.directory.user.contributor",
    "wks.directory.user.ops",
    "wks.directory.user.viewer",
    "wks.gitlab.group.admin",
    "wks.gitlab.group.auditor",
    "wks.gitlab.group.contributor",
    "wks.gitlab.group.ops",
    "wks.gitlab.group.viewer",
    "wks.gitlab.project.admin",
    "wks.gitlab.project.auditor",
    "wks.gitlab.project.contributor",
    "wks.gitlab.project.ops",
    "wks.gitlab.project.viewer",
    "wks.global.admin",
    "wks.global.auditor",
    "wks.global.contributor",
    "wks.global.ops",
    "wks.global.viewer",
    "wks.google.cloud.folder.admin",
    "wks.google.cloud.folder.auditor",
    "wks.google.cloud.folder.contributor",
    "wks.google.cloud.folder.ops",
    "wks.google.cloud.folder.viewer",
    "wks.google.cloud.project.admin",
    "wks.google.cloud.project.auditor",
    "wks.google.cloud.project.contributor",
    "wks.google.cloud.project.ops",
    "wks.google.cloud.project.viewer",
    "wks.google.credential.admin",
    "wks.google.credential.auditor",
    "wks.google.credential.contributor",
    "wks.google.credential.ops",
    "wks.google.credential.viewer",
    "wks.google.drive.doc.admin",
    "wks.google.drive.doc.auditor",
    "wks.google.drive.doc.contributor",
    "wks.google.drive.doc.ops",
    "wks.google.drive.doc.viewer",
    "wks.google.drive.file.admin",
    "wks.google.drive.file.auditor",
    "wks.google.drive.file.contributor",
    "wks.google.drive.file.ops",
    "wks.google.drive.file.viewer",
    "wks.google.drive.folder.admin",
    "wks.google.drive.folder.auditor",
    "wks.google.drive.folder.contributor",
    "wks.google.drive.folder.ops",
    "wks.google.drive.folder.viewer",
    "wks.google.drive.sheet.admin",
    "wks.google.drive.sheet.auditor",
    "wks.google.drive.sheet.contributor",
    "wks.google.drive.sheet.ops",
    "wks.google.drive.sheet.viewer",
    "wks.google.drive.slide.admin",
    "wks.google.drive.slide.auditor",
    "wks.google.drive.slide.contributor",
    "wks.google.drive.slide.ops",
    "wks.google.drive.slide.viewer",
    "wks.google.identity.group.admin",
    "wks.google.identity.group.auditor",
    "wks.google.identity.group.contributor",
    "wks.google.identity.group.ops",
    "wks.google.identity.group.viewer",
    "wks.google.integration.admin",
    "wks.google.integration.auditor",
    "wks.google.integration.contributor",
    "wks.google.integration.ops",
    "wks.google.integration.viewer",
    "wks.google.workspace.drive.admin",
    "wks.google.workspace.drive.auditor",
    "wks.google.workspace.drive.contributor",
    "wks.google.workspace.drive.ops",
    "wks.google.workspace.drive.viewer",
    "wks.google.workspace.group.admin",
    "wks.google.workspace.group.auditor",
    "wks.google.workspace.group.contributor",
    "wks.google.workspace.group.ops",
    "wks.google.workspace.group.viewer",
    "wks.maintenance.admin",
    "wks.maintenance.auditor",
    "wks.maintenance.ops",
    "wks.maintenance.viewer",
    "wks.okta.app.admin",
    "wks.okta.app.auditor",
    "wks.okta.app.contributor",
    "wks.okta.app.ops",
    "wks.okta.app.viewer",
    "wks.okta.credential.admin",
    "wks.okta.credential.auditor",
    "wks.okta.credential.contributor",
    "wks.okta.credential.ops",
    "wks.okta.credential.viewer",
    "wks.okta.group.admin",
    "wks.okta.group.auditor",
    "wks.okta.group.contributor",
    "wks.okta.group.ops",
    "wks.okta.group.viewer",
    "wks.okta.integration.admin",
    "wks.okta.integration.auditor",
    "wks.okta.integration.contributor",
    "wks.okta.integration.ops",
    "wks.okta.integration.viewer",
    "wks.policy.role.admin",
    "wks.policy.role.auditor",
    "wks.policy.role.contributor",
    "wks.policy.role.ops",
    "wks.policy.role.viewer",
    "wks.policy.rule.admin",
    "wks.policy.rule.admin.admin",
    "wks.policy.rule.admin.contributor",
    "wks.policy.rule.admin.ops",
    "wks.policy.rule.auditor",
    "wks.policy.rule.contributor",
    "wks.policy.rule.ops",
    "wks.policy.rule.viewer",
    "wks.policy.user.admin",
    "wks.policy.user.auditor",
    "wks.policy.user.contributor",
    "wks.policy.user.ops",
    "wks.policy.user.viewer",
    "wks.slack.channel.admin",
    "wks.slack.channel.auditor",
    "wks.slack.channel.contributor",
    "wks.slack.channel.ops",
    "wks.slack.channel.viewer",
    "wks.slack.group.admin",
    "wks.slack.group.auditor",
    "wks.slack.group.contributor",
    "wks.slack.group.ops",
    "wks.slack.group.viewer",
    "wks.workspace.abbreviation.admin",
    "wks.workspace.abbreviation.auditor",
    "wks.workspace.abbreviation.contributor",
    "wks.workspace.abbreviation.ops",
    "wks.workspace.abbreviation.viewer",
    "wks.workspace.device.admin",
    "wks.workspace.device.auditor",
    "wks.workspace.device.contributor",
    "wks.workspace.device.ops",
    "wks.workspace.device.viewer",
    "wks.workspace.global.token.admin",
    "wks.workspace.global.token.auditor",
    "wks.workspace.global.token.contributor",
    "wks.workspace.global.token.ops",
    "wks.workspace.global.token.viewer",
    "wks.workspace.role.admin",
    "wks.workspace.role.auditor",
    "wks.workspace.role.contributor",
    "wks.workspace.role.ops",
    "wks.workspace.role.permission.admin",
    "wks.workspace.role.permission.contributor",
    "wks.workspace.role.permission.ops",
    "wks.workspace.role.service.admin",
    "wks.workspace.role.service.auditor",
    "wks.workspace.role.service.contributor",
    "wks.workspace.role.service.ops",
    "wks.workspace.role.service.viewer",
    "wks.workspace.role.user.admin",
    "wks.workspace.role.user.auditor",
    "wks.workspace.role.user.contributor",
    "wks.workspace.role.user.ops",
    "wks.workspace.role.user.viewer",
    "wks.workspace.role.viewer",
    "wks.workspace.service.admin",
    "wks.workspace.service.admin.admin",
    "wks.workspace.service.admin.contributor",
    "wks.workspace.service.admin.ops",
    "wks.workspace.service.auditor",
    "wks.workspace.service.contributor",
    "wks.workspace.service.ops",
    "wks.workspace.service.token.admin",
    "wks.workspace.service.token.contributor",
    "wks.workspace.service.token.ops",
    "wks.workspace.service.viewer",
    "wks.workspace.token.admin",
    "wks.workspace.token.auditor",
    "wks.workspace.token.contributor",
    "wks.workspace.token.ops",
    "wks.workspace.token.viewer",
    "wks.workspace.user.admin",
    "wks.workspace.user.auditor",
    "wks.workspace.user.contributor",
    "wks.workspace.user.ops",
    "wks.workspace.user.token.admin",
    "wks.workspace.user.token.auditor",
    "wks.workspace.user.token.contributor",
    "wks.workspace.user.token.ops",
    "wks.workspace.user.token.viewer",
    "wks.workspace.user.viewer"
]
```

***

With people and service accounts signed in and their roles in place, the next page looks at where your workspace runs and how it's isolated from every other workspace.

[Continue reading: Tenant Infrastructure Isolation →](https://docs.provisionr.io/concepts/workspace/infrastructure.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.