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
{
"name": "NamespaceGlobalReadOnly",
"description": "Read-only access to all namespaces for monitoring and compliance",
"grants": [
{
"operation": "cloud.namespace.list",
"resourceType": "Namespace",
"scope": { "all": true }
},
{
"operation": "cloud.namespace.get",
"resourceType": "Namespace",
"scope": { "all": true }
}
]
}
Create Custom Roles from the Web UI
To create a Custom Role from the Web UI, select Org 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. Select the Resource Type from the drop-down; your choices are Namespace and Account.
If you select Namespace, search for the Namespace for which you want to add permissions, then click Add Resource. The Namespace you selected appears in the Permissions By Resource list.
If you select Account, the permissions apply to the current account, so only the Add Resource button appears. Click Add Resource, and the Account will be added to the Permissions By Resource list.
Once the Namespace or Account appears in the Permissions By Resource list, you can toggle individual permissions on or off for that resource. If you want to start with the permission set of one of the pre-defined Temporal roles, choose the role from the Select Preset drop-down, and the appropriate permissions will be toggled for you.
When you're done assiging permissions to resources, click Create Custom Role at the bottom of the page.
Create Custom Roles with the API
Create Custom Roles with Terraform
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.
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.