encryption & security

23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Temporal Cloud API key connection with environment variables

To connect to Temporal Cloud with an API key, set these environment variables with values from Temporal Cloud API key settings: - TEMPORAL_ADDRESS: <your-namespace>.<your-account-id>.tmprl.cloud:7233 - TEMPORAL_NAMESPACE: <your-namespace>.<your-account-id> - TEMPORAL_API_KEY: <your-api-key>

Temporal Cloud mTLS connection with environment variables

To connect to Temporal Cloud with mTLS, set these environment variables with values from Temporal Cloud Namespace settings: - TEMPORAL_ADDRESS: <your-namespace>.<your-account-id>.tmprl.cloud:7233 - TEMPORAL_NAMESPACE: <your-namespace>.<your-account-id> - TEMPORAL_TLS_CLIENT_CERT_PATH: path/to/your/client.pem - TEMPORAL_TLS_CLIENT_KEY_PATH: path/to/your/client.key

Temporal Cloud preconfigured account-level roles

Temporal Cloud provides the following preconfigured account-level roles: Account Owner, Finance Admin, Global Admin, Developer, and Read-Only. Namespace-level permissions are also available.

Automated user provisioning with SCIM

Temporal Cloud supports SCIM and the Temporal Cloud user management API for automating adding and removing user accounts, ensuring timely removal of access when people change roles or leave the organization.

Service Accounts for non-human access

Service Accounts are machine identities in Temporal Cloud that can be granted specific permissions without ties to an individual. For non-human access such as CI/CD pipelines and backend services, use Service Accounts instead of shared user logins. Create separate Service Accounts with unique API keys for different applications or microservices and apply least privilege to each, such as access to only one Namespace.

Mutual TLS (mTLS) for Temporal Cloud authentication

Temporal Cloud secures its gRPC endpoint per Namespace via mutual TLS. You provide a Certificate Authority (CA) certificate for your Namespace, and all Temporal clients and workers must present client certificates signed by that CA. This ensures only systems holding a valid certificate issued by your trusted CA can connect.

Certificate rotation best practices

Track expiration dates of client and Certificate Authority certificates, as Temporal Cloud trusts the uploaded CA and if it expires, all client authorizations will fail. Establish and automate a certificate rotation schedule such as rotating client certificates quarterly and CA certificates annually, well before expiry. Temporal supports uploading a new CA certificate alongside the old one to allow seamless rollover. Always test new certificates in a staging environment if possible.

Temporal Cloud API key security practices

If using API Keys for authentication of SDKs, CLI, and automation, handle them with strict care: store in a secrets manager, never in code or Git; rotate at least every 90 days by creating a new key, swapping it in, then deleting the old one; use one key per service/person with no sharing or reuse; monitor usage and revoke on anomalies by feeding Temporal audit logs to SIEM; admins can optionally disable all user API keys if policy is 'mTLS only'.

Data Converter for client-side encryption

Temporal provides an optional data conversion framework (Data Converter) and payload codec interface for client-side encryption of workflow data. Customers must implement, deploy, and operate their own custom codec and manage encryption keys. Encryption keys stay under your control, and you are responsible for key generation, secure storage, rotation, and versioning. This involves developing a custom codec plugin in your Temporal SDK and optionally deploying a dedicated codec server if you need to inspect decrypted payloads in the Web UI or CLI.

Failure Converter for encrypting error information

Temporal's default behavior copies error messages and call stacks as plain text, directly accessible in the Message field of Workflow Executions. If failure messages and stack traces contain sensitive information, configure the Failure Converter to encrypt the error information, which encrypts the message and stack_trace fields in the payloads.

SAML SSO integration with Temporal Cloud

Temporal Cloud can be integrated with your organization's identity provider via SAML 2.0 for centralized authentication. This allows you to enforce your corporate login policies such as MFA and password complexity. Social logins (Microsoft, Google) can be disabled by opening a support ticket.

Temporal Cloud server-side encryption at rest

Temporal Cloud already encrypts all data at rest on the server side. Additional layers of encryption can be added through client-side encryption mechanisms.

Setting custom Payload Codec on TemporalClient

When creating a client, the default DataConverter can be updated with a custom payload codec like this: ```csharp var myClient = await TemporalClient.ConnectAsync(new("localhost:7233") { DataConverter = DataConverter.Default with { PayloadCodec = new EncryptionCodec() }, }); ```

Client-side encryption model for Payloads

Temporal's security model is designed around client-side encryption of Payloads. A client may encrypt Payloads before sending them to the server and decrypt them after receiving them from the server. This provides high confidentiality because the Temporal Server itself has no knowledge of the actual data. Implementers can control access with keys, algorithms, or other security measures.

Server does not add encryption to Payloads

The Temporal Server itself never adds encryption over Payloads. Unless client-side encryption is implemented, Payload data will be persisted in non-encrypted form to the data store, and any Client that can make requests to a Temporal namespace (including the Temporal UI and CLI) will be able to read Payloads contained in Workflows.

Implementing encryption with Custom Payload Codec

A Temporal developer adds client-side encryption of Payloads by providing a Custom Payload Codec to its Client. Depending on business needs, a complete implementation of Payload Encryption may involve selecting appropriate encryption algorithms, managing encryption keys, restricting a subset of users from viewing payload output, or a combination of these.

IPayloadCodec interface requirements

The IPayloadCodec interface needs to implement EncodeAsync() and DecodeAsync() methods. These methods should convert the given payloads as needed into new payloads, using the "encoding" metadata field. The existing payloads must not be mutated.

Custom Payload Codec example in .NET

Example EncryptionCodec implementation: ```csharp public class EncryptionCodec : IPayloadCodec { public Task<IReadOnlyCollection<Payload>> EncodeAsync(IReadOnlyCollection<Payload> payloads) => Task.FromResult<IReadOnlyCollection<Payload>>(payloads.Select(p => { return new Payload() { // Set our specific encoding. We may also want to add a key ID in here for use by // the decode side Metadata = { ["encoding"] = "binary/my-payload-encoding" }, Data = ByteString.CopyFrom(Encrypt(p.ToByteArray())), }; }).ToList()); public Task<IReadOnlyCollection<Payload>> DecodeAsync(IReadOnlyCollection<Payload> payloads) => Task.FromResult<IReadOnlyCollection<Payload>>(payloads.Select(p => { // Ignore if it doesn't have our expected encoding if (p.Metadata.GetValueOrDefault("encoding") != "binary/my-payload-encoding") { return p; } // Decrypt return Payload.Parser.ParseFrom(Decrypt(p.Data.ToByteArray())); }).ToList()); private byte[] Encrypt(byte[] data) => Encoding.ASCII.GetBytes(Convert.ToBase64String(data)); private byte[] Decrypt(byte[] data) => Convert.FromBase64String(Encoding.ASCII.GetString(data)); } ```

Data encoding and decoding flow

Data encoding is performed by the client using the converters and codecs provided by Temporal or custom implementation when passing input to the Temporal Cluster. Plain text input is usually serialized into a JSON object and can then be compressed or encrypted. Data decoding may be performed by application logic during Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Cluster. Instead, they are stored encoded on the Cluster.

Codec Server purpose and deployment

A Codec Server is an HTTP server that uses custom Codec logic to decode encrypted data remotely. The Codec Server is independent of the Temporal Cluster and decodes encrypted payloads through predefined endpoints. The implementer creates, operates, and manages access to the Codec Server in their own environment. The Temporal CLI and Web UI provide built-in hooks to call the Codec Server to decode encrypted payloads on demand.

TLS/CA loading workaround on AWS Lambda .NET

Some AWS Lambda .NET images override the SSL_CERT_FILE environment variable in a way that prevents the SDK's Rust-based runtime from loading system root CAs. If you encounter TLS certificate errors on Lambda, see the AWS Lambda .NET CA loading workaround in the SDK README.

Lambda execution role permissions for X-Ray and CloudWatch

The Lambda execution role must have permissions to write to X-Ray and CloudWatch. Add xray:PutTraceSegments, xray:PutTelemetryRecords, and cloudwatch:PutMetricData permissions to the execution role. Without these permissions, the Collector fails silently and no telemetry appears.

Workflow ID sensitivity and security

Do not include sensitive data, secrets, or personally identifiable information (PII) as a Workflow ID. Workflow IDs are stored in plain text, are not processed by a custom Payload Codec, and are visible in the Temporal Web UI, CLI output, Event History, and system logs. The same applies to Workflow Type names, Task Queue names, Activity names, and Signal/Query/Update names. Using sensitive data risks exposure to anyone with Namespace access and may violate data protection regulations such as GDPR, HIPAA, or SOC 2.

Give your agent this brain