Skip to main content

Temporal Web UI configuration reference

View Markdown
info

To set these keys with environment variables in the temporalio/ui Docker image, see the Temporal Web UI environment variables reference.

The Temporal Web UI Server reads its configuration from YAML files in its configuration directory. It loads base.yaml first, then the file for the current environment, such as development.yaml. Values in the environment file override values in base.yaml.

The configuration structs are defined in config.go in the ui-server repository. For a complete example, see development.yaml.

Each key on this page lists its environment variable and its default. The default is the value the Web UI Server uses when no configuration file sets the key. The Docker image sets its own defaults through environment variables.

Server settings​

temporalGrpcAddress​

Address of the Frontend Service that the Web UI Server connects to. The Web UI Server doesn't start without this value.

  • Environment variable: TEMPORAL_ADDRESS
  • Default: 127.0.0.1:7233, set in base.yaml

host​

Network interface that the Web UI Server listens on. When empty, the Web UI Server listens on every interface.

  • Environment variable: none
  • Default: empty

port​

Port that the Web UI Server listens on for the browser UI and the HTTP API.

publicPath​

Subpath to serve the Web UI from, such as /custom-path. Leave it empty to serve the Web UI from the root path.

enableUi​

Set to true to serve the browser UI. When false, the Web UI Server serves only its APIs.

uiAssetPath​

Directory to serve the Web UI's static files from, instead of the files built into the Web UI Server.

  • Environment variable: none
  • Default: empty

cloudUi​

Set to true to use the Temporal Cloud version of the Web UI.

refreshInterval​

How often the Web UI Server reloads its configuration files, such as 1m. Set it to 0s to turn off reloading. Settings that the Web UI Server reads only at startup, such as host, port, and publicPath, still need a restart.

forwardHeaders​

List of HTTP headers that the Web UI Server forwards from HTTP API requests to the Temporal Service's gRPC API.

forwardHeaders:
  - X-Forwarded-For

hideLogs​

Set to true to stop the Web UI Server from printing its logs to the console.

distribution​

How the Web UI was installed: cli, docker, helm, or server. When notifyOnNewVersion is true, the Web UI Server uses this value to choose which release to check for updates.

distributionVersion​

Version of the distribution that installed the Web UI, such as the Temporal CLI version. Only the cli distribution uses this value.

Web UI behavior settings​

defaultNamespace​

Namespace that the Web UI opens first.

feedbackUrl​

URL that the Feedback button in the Web UI opens. When empty, the button opens the Web UI's GitHub issues page.

showTemporalSystemNamespace​

Set to true to show the Temporal System Namespace in the Web UI. The System Namespace holds the Workflow Executions that the Temporal Service runs internally.

disableNewsFetch​

Set to true to stop the Web UI from requesting the news feed. The Web UI also hides the button that opens the news feed panel.

notifyOnNewVersion​

Set to true to show a notice in the Web UI when a newer release is available. The Web UI Server checks the release that matches distribution.

Set to true to collapse the left navigation and the saved views navigation when the Web UI loads.

hideWorkflowQueryErrors​

Set to true to hide server errors from Workflow Queries in the Web UI.

refreshWorkflowCountsDisabled​

Set to true to stop the Web UI from refreshing the Workflow status counts on the Workflows page.

Workflow and Activity action settings​

These keys disable actions in the Web UI that change Workflow Executions or Activities. Each key hides or disables the matching control in the Web UI.

disableWriteActions​

Set to true to disable every action in the Web UI that changes a Workflow Execution or Activity, including batch actions. This key overrides the other keys in this section.

The Web UI Server also rejects write requests to its HTTP API. Workflow Queries still work.

workflowTerminateDisabled​

Set to true to prevent users from terminating Workflow Executions from the Web UI.

workflowCancelDisabled​

Set to true to prevent users from canceling Workflow Executions from the Web UI.

workflowSignalDisabled​

Set to true to prevent users from sending Signals to Workflow Executions from the Web UI.

workflowUpdateDisabled​

Set to true to prevent users from sending Updates to Workflow Executions from the Web UI.

workflowResetDisabled​

Set to true to prevent users from resetting Workflow Executions from the Web UI.

workflowPauseDisabled​

Set to true to prevent users from pausing Workflow Executions from the Web UI.

batchActionsDisabled​

Set to true to prevent users from running batch actions on multiple Workflow Executions from the Web UI.

startWorkflowDisabled​

Set to true to prevent users from starting Workflow Executions from the Web UI.

activityCommandsDisabled​

Set to true to hide the commands for pending Activities in the Web UI. These commands pause, unpause, and reset an Activity, and update its options.

cors​

The cors section controls which origins can call the Web UI Server APIs and how the Web UI Server sets its cross-site request forgery (CSRF) cookie. CORS stands for Cross-Origin Resource Sharing.

cors:
  allowOrigins:
    - http://localhost:3000
  unsafeAllowAllOrigins: false
  cookieInsecure: false
  • allowOrigins: List of origins that can make cross-origin requests to the Web UI Server APIs. A value of * allows every origin.
  • unsafeAllowAllOrigins: Set to true to accept cross-origin requests from any origin and ignore allowOrigins. Use it only for local development.
  • cookieInsecure: Set to true to send the CSRF cookie over connections the browser considers insecure, such as plain HTTP. Use it only when something other than HTTPS secures the connection, such as a VPN.

auth​

The auth section configures sign-in to the Web UI through an identity provider (IdP). It controls who can access the Web UI, not authorization against the Temporal Service.

auth:
  enabled: true
  providers:
    - label: sso
      type: oidc
      providerUrl: https://accounts.google.com
      issuerUrl:
      clientId: xxxxx-xxxx.apps.googleusercontent.com
      clientSecret: xxxxxxxxxxxxxxxxxxxx
      callbackUrl: https://xxxx.com:8080/auth/sso/callback
      scopes:
        - openid
        - profile
        - email
  • enabled: Set to true to require users to sign in to the Web UI. The other auth keys take effect only when this key is true.
  • redirectToProvider: Set to true to skip the Web UI sign-in page and send users who aren't signed in directly to the IdP.
  • maxSessionDuration: Longest a user session can last, such as 8h or 168h. After this duration, users must sign in again even if their tokens are still valid. When empty, sessions have no maximum duration.
  • providers: List of IdPs. The Web UI Server uses only the first provider in the list.
    • Default: empty

providers​

Each provider takes the following keys. When enabled is true, the Web UI Server doesn't start unless providerUrl, clientId, and callbackUrl are set.

  • label: Label for the IdP.
  • type: Authentication type. Only oidc is supported.
  • providerUrl: IdP URL that the Web UI Server uses for OpenID Connect (OIDC) discovery, such as https://accounts.google.com.
  • issuerUrl: URL of the token issuer. Set it only when the issuer differs from providerUrl.
  • clientId: OAuth client ID that the IdP issued for the Web UI.
  • clientSecret: OAuth client secret that the IdP issued for the Web UI.
  • callbackUrl: URL that the IdP redirects users to after they sign in, such as https://xxxx.com:8080/auth/sso/callback.
  • scopes: List of OIDC scopes to request, such as openid, profile, and email.
  • options: Map of query parameters that the Web UI Server adds to the redirect URL for the IdP. Use it for IdP-specific sign-in flows, such as the Auth0 audience and organization parameters.
    • Environment variable: none
    • Default: empty
  • useIdTokenAsBearer: Set to true to send the ID token instead of the access token as the bearer token in the Authorization header.
  • refreshTokenDuration: Lifetime of the refresh tokens that the IdP issues, such as 24h. Set it only when the IdP issues opaque refresh tokens, because the Web UI Server can't read their expiration. For JSON Web Token (JWT) refresh tokens, the Web UI Server uses the token's exp claim and ignores this value. When neither is available, the Web UI Server assumes a lifetime of 7 days.

tls​

The tls section configures Transport Layer Security (TLS) for the Web UI Server's connection to the Frontend Service. It doesn't configure TLS for the Web UI itself. To serve the Web UI over HTTPS, see uiServerTLS.

tls:
  caFile: ../ca.cert
  certFile: ../cluster.pem
  keyFile: ../cluster.key
  caData:
  certData:
  keyData:
  enableHostVerification: true
  serverName: tls-server
  • caFile: Path to the Certificate Authority (CA) certificate that verifies the Frontend Service's certificate.
  • certFile: Path to the client certificate that the Web UI Server presents to the Frontend Service for mutual TLS (mTLS).
  • keyFile: Path to the private key for the certificate in certFile.
  • caData: PEM data for the CA certificate. Use it instead of caFile.
  • certData: PEM data for the client certificate. Use it instead of certFile.
  • keyData: PEM data for the private key. Use it instead of keyFile.
  • enableHostVerification: Set to true to verify that the Frontend Service's certificate matches its hostname.
  • serverName: Overrides the server name sent for Server Name Indication (SNI) and checked against the Frontend Service's certificate.

uiServerTLS​

The uiServerTLS section configures the Web UI Server to serve the Web UI over HTTPS. The Web UI Server starts in TLS mode only when you set both keys.

uiServerTLS:
  certFile: ../ui-server.pem
  keyFile: ../ui-server.key
  • certFile: Path to the certificate that the Web UI Server presents to browsers.
  • keyFile: Path to the private key for the certificate in certFile.

codec​

The codec section configures how the Web UI sends payloads to a Codec Server for decoding.

codec:
  endpoint: https://your-codec-server-endpoint
  passAccessToken: false
  includeCredentials: false
  defaultErrorMessage:
  defaultErrorLink: