For information about the general security habits of Temporal Technologies, see our company security page.
For information about Temporal Cloud security features, see our Cloud security page
The Temporal Platform is designed with security in mind, and there are many features that you can use to keep both the Platform itself and your user's data secure.
A secured Temporal Server has its network communication encrypted and has authentication and authorization protocols set up for API calls made to it. Without these, your server could be accessed by unwanted entities.
What is documented on this page are the built-in opt-in security measures that come with Temporal. However users may also choose to design their own security architecture with reverse proxies or run unsecured instances inside of a VPC environment.
The https://github.com/temporalio/samples-server repo offers two examples, which are further explained below:
- TLS: how to configure Transport Layer Security (TLS) to secure network communication with and within a Temporal cluster.
- Authorizer: how to inject a low-level authorizer component that can control access to all API calls.
Encryption in transit with mTLS
Temporal supports Mutual Transport Layer Security (mTLS) as a way of encrypting network traffic between the services of a cluster and also between application processes and a Cluster. Self-signed or properly minted certificates can be used for mTLS. mTLS is set in Temporal's TLS configuration. The configuration includes two sections such that intra-Cluster and external traffic can be encrypted with different sets of certificates and settings:
internode: Configuration for encrypting communication between nodes in the cluster.
frontend: Configuration for encrypting the Frontend's public endpoints.
See TLS configuration reference for more details.
There are a few authentication protocols available to prevent unwanted access such as authentication of servers, clients, and users.
To prevent spoofing and MITM attacks you can specify the
serverName in the
client section of your respective mTLS configuration.
This enables established connections to authenticate the endpoint, ensuring that the server certificate presented to any connecting Client has the appropriate server name in its CN property.
It can be used for both
More guidance on mTLS setup can be found in the
samples-server repo and you can reach out to us for further guidance.
To restrict a client's network access to cluster endpoints you can limit it to clients with certificates issued by a specific Certificate Authority (CA).
requireClientAuth properties in both the
frontend sections of the mTLS configuration.
To restrict access to specific users, authentication and authorization is performed through extensibility points and plugins as described in the Authorization section below.
Temporal offers two plugin interfaces for implementing API call authorization:
The authorization and claim mapping logic is customizable, making it available to a variety of use cases and identity schemes. When these are provided the frontend invokes the implementation of these interfaces before executing the requested operation.
See https://github.com/temporalio/samples-server/blob/main/extensibility/authorizer for a sample implementation.
Single sign-on integration
Temporal can be integrated with a single sign-on (SSO) experience by utilizing the
The default JWT
ClaimMapper implementation can be used as is or as a base for a custom implementation of a similar plugin.
To enable SSO for the Temporal Web UI edit the web service's configuration per the Temporal Web README.
Temporal Cluster plugins
Temporal Clusters support some pluggable components.
What is a ClaimMapper Plugin?
The Claim Mapper component is a pluggable component that extracts Claims from JSON Web Tokens (JWTs).
This process is achieved with the method
GetClaims, which translates
AuthInfo structs from the caller into
Claims about the caller's roles within Temporal.
Role (within Temporal) is a bit mask that combines one or more of the role constants.
In the following example, the role is assigned constants that allow the caller to read and write information.
role := authorization.RoleReader | authorization.RoleWriter
GetClaims is customizable and can be modified with the
temporal.WithClaimMapper server option.
Temporal also offers a default JWT
ClaimMapper for your use.
A typical approach is for
ClaimMapper to interpret custom
Claims from a caller's JWT, such as membership in groups, and map them to Temporal roles for the user.
The subject information from the caller's mTLS certificate can also be a parameter in determining roles.
AuthInfo is a struct that is passed to
AuthInfo contains an authorization token extracted from the
authorization header of the gRPC request.
AuthInfo includes a pointer to the
This struct contains an x.509 Distinguished Name from the caller's mTLS certificate.
Claims is a struct that contains information about permission claims granted to the caller.
Authorizer assumes that the caller has been properly authenticated, and trusts the
Claims when making an authorization decision.
Default JWT ClaimMapper
Temporal offers a default JWT
ClaimMapper that extracts the information needed to form Temporal
This plugin requires a public key to validate digital signatures.
To get an instance of the default JWT
NewDefaultJWTClaimMapper and provide it with the following:
- a logger
The code for the default
ClaimMapper can also be used to build a custom
Token key provider
TokenKeyProvider obtains public keys from specified issuers' URIs that adhere to a specific format.
The default JWT
ClaimMapper uses this component to obtain and refresh public keys over time.
Temporal provides an
This component dynamically obtains public keys that follow the JWKS format.
rsaTokenKeyProvider uses only the
provider := authorization.NewRSAKeyProvider(cfg)
By default, "permissions" is used to name the
Configure the plugin with
JSON Web Token format
The default JWT
ClaimMapper expects authorization tokens to be formatted as follows:
The Permissions Claim in the JWT Token is expected to be a collection of Individual Permission Claims. Each Individual Permission Claim must be formatted as follows:
<namespace> : <permission>
These permissions are then converted into Temporal roles for the caller. This can be one of Temporal's four values:
Multiple permissions for the same Namespace are overridden by the
Example of a payload for the default JWT ClaimMapper
What is an Authorizer Plugin?
Authorizer plugin contains a single
Authorize method, which is invoked for each incoming API call.
Authorize receives information about the API call, along with the role and permission claims of the caller.
Authorizer allows for a wide range of authorization logic, including call target, role/permissions claims, and other data available to the system.
The following arguments must be passed to
context.Context: General context of the call.
authorization.Claims: Claims about the roles assigned to the caller. Its intended use is described in the
Claimssection earlier on this page.
authorization.CallTarget: Target of the API call.
Authorizer then returns one of two decisions:
DecisionDeny: the requested API call is not invoked and an error is returned to the caller.
DecisionAllow: the requested API call is invoked.
Authorizer allows all API calls pass by default. Disable the
nopAuthority authorizer and configure your own to prevent this behavior.
Authorizer when you start the server via the
temporal.WithAuthorizer server option.
Authorizer is not set in the server options, Temporal uses the
nopAuthority authorizer that unconditionally allows all API calls to pass through.
a := authorization.NewDefaultAuthorizer()
How to authorize SDK API calls
When authentication is enabled, you can authorize API calls made to the Frontend Service.
Authorization Tokens may be provided to the Temporal Java SDK by implementing a
The implementation should be used to create
io.temporal.authorization.AuthorizationGrpcMetadataProvider that may be configured on ServiceStub gRPC interceptors list.
The implementation is called for each SDK gRPC request and may supply dynamic tokens.
One of the token types that may be passed this way are JWT tokens. Temporal Server provides a default implementation of JWT authentication.
AuthorizationTokenSupplier tokenSupplier =
//your implementation of token supplier
() -> "Bearer <Base64 url-encoded value of the token for default JWT ClaimMapper>";
WorkflowServiceStubsOptions serviceStubOptions =
//other service stub options
WorkflowServiceStubs service = WorkflowServiceStubs.newServiceStubs(serviceStubOptions);
WorkflowClient client = WorkflowClient.newInstance(service);
For details on what data can be encoded, how to secure it, and what to consider when using encryption, see Data encryption.
You can use a Codec Server with your custom Payload Codec to decode the data you see on your Web UI and CLI locally through remote endpoints. However, ensure that you consider all security implications of remote data encoding before using a Codec Server.
For details on how to set up a Codec Server, see Codec Server setup.