Skip to main content

Manage custom roles

Temporal Cloud offers a set of predefined account-level roles and Namespace-level permissions. These roles are sufficient for many Temporal use cases, but can't cover all combinations of least privilege, delegation, and automation-safe permissions often required in large enterprises.

What are Custom Roles?​

Custom Roles enable you to define your own roles as bundles of permission primitives (operations/actions) scoped to applicable resources (namespaces or account objects) and assign them to any principal (user, group, service account).

Why use Custom Roles?​

Use Custom Roles if you want more fine-grained authentication than Temporal Cloud's predefined roles and permissions provide.

Use Custom Roles if your access model enforces least-privilege access to grant users and service accounts only the operations they explicitly need, and no more.

Using Custom Roles with Service Accounts can make them more secure for automation purposes.

Custom Roles limits​

For more information about the limits of Custom Roles, see Custom Roles limits.

Defining Custom Roles​

Custom Roles are made up of bundles of permission operations that map to Temporal Control Plane operations. You can scope a permission to all resources of a type, or to specific resources.

For example, the following JSON code defines a global, read-only Namespace role called NamespaceGlobalReadOnly, to use for auditing and monitoring. Users with this role will be able to retrieve information about any Namespace, but will not be able to modify them. The grants field is an array of the available permission operations, in this case cloud.namespace.list and cloud.namespace.get. The operations are limited to a resourceType of Namespace, and the scope is all.

You can scope roles to:

  • All resources of a given type
  • Specific resources by explicit ID list

::: warning Custom Roles are additive only

Custom Roles define a set of granular permissions and assign them alongside a predefined role. The effective access is the union of both. You cannot use custom roles to narrow down or remove permissions from a predefined role.

:::

Available permissions​

Most of the Control Plane operations listed in the API references (HTTP, GRPC) can be assigned to a Custom Role. For the operations that are supported by Custom Roles, you will see the naming specification available next to each API call description.

The following operations are not available to Custom Roles:

  • Creating an API key or a service account. These operations are part of the pre-defined roles (admin or above) and cannot be assigned to other less-privileged roles.
  • Operations that require additional role and permission validation, such as Create a Nexus Endpoint.
  • Separating or splitting operations that are part of UpdateNamespace.

Create Custom Roles​

To create a Custom Role from the Web UI, select Settings in the left sidebar, and then click the Custom Roles tab on the Settings page.

On the Custom Roles tab, you'll see a list of the roles that have already been defined for your account, 50 to a page. Click the three dots menu to view details about an existing Custom Role, or to edit or delete that role.

Click the Create Custom Role button to create a new role. On the Create Custom Role page, give the Custom Role a name, and optionally a description.

In the Permissions section, you'll assign the appropriate resources and its permissions. The following resources are available for Custom Roles:

  • Account: Permissions scoped to the current account, listed by type.
  • Project: Permissions scoped to the selected Project, listed by type. You must have at least one Project enabled before you can assign Project permissions to a Custom Role.
  • Namespace: Permissions scoped to the selected Namespace, listed by type. You can only assign permissions to Namespaces to which you have access.
  • Nexus Endpoint: Permissions scoped to the selected Nexus Endpoint, listed by type. You much have at least one Nexus Endpoint enabled before you can assign Nexus Endpoint permissions to a Custom Role.
  • Connectivity Rules: Permissions scoped to the selected Connectivity Rules, listed by type.

Account-level permissions apply to the current account. For each of the other resources, you'll need to first select the resource that you want to grant permissions for. Once you select a resource, the list of available permissions will appear, and you can turn them on or off as desired.

TODO: Resolve how we're going to talk about Projects for this release; get clarity on Connectivity Rules.

At the bottom of the Account tab are permissions that relate to Custom Roles. Here, you can define whether members of the Custom Role you're creating will be able to create, update, or delete Custom Roles.

When you're done assiging permissions to resources, click Create Custom Role at the bottom of the page.

Assigning Custom Roles to users​

Once you have created a Custom Role, it is available on the Identities page to assign to a user or group, the same as the pre-defined Temporal permissions. See How to update an account-level role in Temporal Cloud for more inforamtion.

Modifying a Custom Role​

To modify a Custom Role from the Web UI, select Settings in the left sidebar, and then click the Custom Roles tab on the Settings page.

On the Custom Roles tab, you'll see a list of the roles that have already been defined for your account, 50 to a page. Click the three dots menu of the Custom Role you want to modify and select Edit.

The Edit Custom Role page has the same options as the Create Custom Role page. You can change the Custom Role's name or description, or you can modify any of the current permissions assigned to that Role.

When finished, click Update Custom Role.

Delete a Custom Role​

To delete a Custom Role from the Web UI, select Settings in the left sidebar, and then click the Custom Roles tab on the Settings page.

On the Custom Roles tab, you'll see a list of the roles that have already been defined for your account, 50 to a page. Click the three dots menu of the Custom Role you want to delete and select Delete. A pop-up notification will let you know that the Custom Role has been deleted.