You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/best-practices/cloud-access-control.mdx
+61-7Lines changed: 61 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,6 +22,13 @@ Temporal Cloud supports two secure authentication methods for Workers:
22
22
23
23
Both options help secure communication between workers and Temporal Cloud. Choosing the right method and managing it properly is key to maintaining security and minimizing downtime.
24
24
25
+
Use this page to define your operating model for machine access to Temporal Cloud. For setup steps and product-specific
26
+
mechanics, see [Manage API keys](/cloud/api-keys) and [Manage service accounts](/cloud/service-accounts).
27
+
28
+
Related guidance:
29
+
-[Namespace best practices](/best-practices/managing-namespace)
1.**Generate new credentials**: Create new certificates or API keys in Temporal Cloud before the current ones expire
@@ -45,17 +52,64 @@ In the case that you are using multiple certificates signed by the same CA, and
45
52
46
53
One convention is to give certificates a common name that matches the namespace. If you do this when using the same CA for dev and prod, then you can leverage Certificate Filters to prevent access to production environments. This is described in detail under the [authorization section](https://docs.temporal.io/cloud/certificates#control-authorization) of the documentation.
47
54
48
-
## Best practices:
49
-
#### 1. Establish clear guidelines on authentication methods: Teams should standardize on either [mTLS certificates](https://docs.temporal.io/cloud/certificates) or [API keys](https://docs.temporal.io/cloud/api-keys) for the following operations:
55
+
## Best practices
56
+
57
+
### Establish clear guidelines on authentication methods
58
+
59
+
Teams should standardize on either [mTLS certificates](https://docs.temporal.io/cloud/certificates) or
60
+
[API keys](https://docs.temporal.io/cloud/api-keys) for the following operations:
50
61
- Connect Temporal clients to Temporal Cloud (e.g. Worker processes)
By default, it is recommended for teams to use API keys and [service accounts](https://docs.temporal.io/cloud/service-accounts) for both operations because API keys are easier to manage and rotate for most teams. In addition, you can control account-level and namespace-level roles for service accounts.
64
+
By default, teams should use API keys with [service accounts](/cloud/service-accounts) for both operations. API keys
65
+
are generally easier to set up and rotate than mTLS certificates, and service accounts let you assign account-level and
66
+
namespace-level roles.
67
+
68
+
If your organization requires mutual authentication and stronger cryptographic guarantees, use
69
+
[mTLS certificates](/cloud/certificates) to authenticate Temporal clients to Temporal Cloud and use API keys for
70
+
automation, because the Temporal Cloud [Operations API](/ops) and [Terraform provider](/cloud/terraform-provider) only
71
+
support API key authentication. Unlike API keys tied to users or service accounts, mTLS certificate authentication is
72
+
not tied to Temporal Cloud RBAC identities. Namespace access is based on CA trust, with optional
73
+
[Certificate Filters](/cloud/certificates#manage-certificate-filters) to narrow access by Common Name.
74
+
75
+
### Default operating model for service accounts and API keys
76
+
77
+
For most organizations, use the following defaults:
78
+
79
+
- Create one Service Account per service or worker deployment, not one shared Service Account for an entire team
80
+
- Use account-level Service Accounts only when a service genuinely needs cross-Namespace or account-wide access
81
+
- Prefer Namespace-scoped Service Accounts when a service should only access one Namespace
82
+
- Grant Service Accounts namespace-level access only to the specific Namespaces they need
83
+
84
+
This approach gives you cleaner ownership, easier rotation, and better auditability than sharing a single machine
85
+
identity across multiple services.
86
+
87
+
### Use access boundaries that match your Namespace boundaries
88
+
89
+
The way you partition Namespaces should usually match the way you partition machine identities.
90
+
91
+
- If multiple services share a Namespace, you may still want one Service Account per service so that each deployment can
92
+
rotate credentials independently.
93
+
- If you split workloads into separate Namespaces for security, capacity, or team ownership reasons, those Namespaces
94
+
should usually have separate Service Accounts and API keys as well.
95
+
- If you use Namespace-per-tenant isolation, expect your credential model and RBAC model to become correspondingly more
96
+
granular.
97
+
98
+
For more on topology tradeoffs, see [Namespace best practices](/best-practices/managing-namespace) and
Use the following sequence when rotating credentials:
54
104
55
-
If your organization requires mutual authentication and stronger cryptographic guarantees, then it is encouraged for your teams to use mTLS certificates to authenticate Temporal clients to Temporal Cloud and use API keys for automation (because Temporal Cloud [Operations API](https://docs.temporal.io/ops) and [Terraform provider](https://docs.temporal.io/cloud/terraform-provider) only supports API key for authentication)
105
+
1. Create the replacement credential before the existing one expires.
106
+
2. For API keys, create the new valid key while the old key still works, then roll your Workers and clients to use the new key.
107
+
3. For client certificates, stage the new certificate before removing the old one when your deployment process supports that transition.
108
+
4. Validate connectivity and normal Workflow execution using the new credential.
109
+
5. Remove the old credential only after all clients and Workers have switched.
56
110
57
-
#### 2. Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`):
111
+
###Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`)
58
112
59
-
Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.
113
+
Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.
60
114
61
-
If you do this when using the same CA for dev and prod environments, then you can leverage Certificate Filters to prevent access to production.
115
+
If you do this when using the same CA for dev and prod environments, then you can leverage Certificate Filters to prevent access to production.
-[Managing Actions per Second (APS) limits in Temporal Cloud](/best-practices/managing-aps-limits)
38
+
30
39
## Naming Conventions
31
40
32
41
### Use lowercase and hyphens
@@ -66,30 +75,72 @@ If you need to include region, use short codes (e.g., `aps1`, `use1`).
66
75
67
76
## Organizational Patterns
68
77
78
+
### Choose your Namespace boundary intentionally
79
+
80
+
Start with the smallest number of Namespaces that gives you clear ownership and safe isolation.
81
+
In Temporal Cloud, a Namespace boundary affects:
82
+
83
+
-[APS limits](/cloud/limits#actions-per-second) and rate limiting
84
+
- access control and credential scope
85
+
- blast radius for misconfigured or overloaded Workers
86
+
- observability boundaries for dashboards and alerts
87
+
- operational overhead for provisioning, tagging, and lifecycle management
88
+
89
+
Use the following decision table as a starting point:
90
+
91
+
| If you need... | Prefer... | Why |
92
+
|---|---|---|
93
+
| Basic environment isolation for a single application or use case | Namespace per use case and environment | This is the simplest pattern and works well for most initial deployments |
94
+
| Separate operational ownership for services within the same use case | Namespace per use case, service, and environment | This isolates credentials, limits, and operational changes per service |
95
+
| Stronger boundaries across teams, domains, or business capabilities | Namespace per use case, domain, and environment | This reduces blast radius and lets teams own their own Namespace contracts |
96
+
| Tenant-specific credentials, rate limits, or compliance boundaries | Namespace per tenant | Use this only for a small number of high-value tenants because of the operational overhead |
97
+
98
+
As a default, start with one Namespace per use case and environment. Split later when APS pressure, security
99
+
requirements, ownership boundaries, or troubleshooting needs justify the extra operational cost.
100
+
69
101
### Pattern 1: Namespace per use case and environment
70
102
71
103
For simple configurations without multiple services or team boundaries.
72
104
73
-
**Naming convention**: `<use-case>_<environment>`
105
+
**Naming convention**: `<use-case>-<environment>`
106
+
107
+
**Example**: `payments-prd`, `orders-dev`
74
108
75
-
**Example**: `payments_prod`, `orders_dev`
109
+
Choose this pattern when:
110
+
111
+
- one team owns the use case
112
+
- environments need clean separation
113
+
- workload volume and criticality do not yet require further isolation
76
114
77
115
### Pattern 2: Namespace per use case, service, and environment
78
116
79
117
When multiple services that are part of the same use case communicate externally to Temporal via API (HTTP/gRPC).
- multiple teams or domains need independent release cadence and ownership
141
+
- failures in one domain should not affect the others
142
+
- you want a stronger permission boundary between capabilities
143
+
- you plan to expose cross-Namespace contracts through Nexus
93
144
94
145
For systems without Nexus, services can communicate via [Signals](/sending-messages#sending-signals) or [Child Workflows](/child-workflows) within the same Namespace.
95
146
@@ -98,6 +149,33 @@ When multiple teams share a Namespace, prefix each Workflow ID with a service-sp
98
149
Task Queue names must also be unique within the Namespace.
99
150
:::
100
151
152
+
### Pattern 4: Namespace per tenant
153
+
154
+
Use a separate [Namespace](/namespaces) per tenant only when each tenant needs a true isolation boundary.
155
+
156
+
This is usually appropriate only for a small number of high-value tenants that require:
157
+
158
+
- dedicated credentials and access control
159
+
- tenant-specific rate limits or capacity decisions
160
+
- strict compliance or data-isolation boundaries
161
+
- independent debugging, alerting, and operational ownership
162
+
163
+
For most SaaS use cases, a shared Namespace with per-tenant [Task Queues](/task-queue) is simpler and more scalable.
164
+
See [Multi-tenant application patterns](/production-deployment/multi-tenant-patterns) for those designs.
165
+
166
+
### What should cause you to split a Namespace later?
167
+
168
+
Revisit your topology when one or more of the following becomes true:
169
+
170
+
- one workload is consuming enough APS that it regularly threatens others in the same Namespace
171
+
- one team needs tighter access controls or dedicated credentials
172
+
- production troubleshooting requires clearer dashboards, alerts, or ownership boundaries
173
+
- one application or domain is business-critical enough that its blast radius must be reduced
174
+
- a tenant or regulated workload needs stronger separation than Task Queue isolation can provide
175
+
176
+
Splitting a Namespace increases safety, but it also adds overhead for provisioning, tagging, credentials, and cross-Namespace coordination.
177
+
Use [Nexus](/nexus) where possible instead of sharing Temporal primitives across team or domain boundaries.
178
+
101
179
## Production Safeguards
102
180
103
181
### Use an Authorizer (open source only) {#authorizer}
0 commit comments