SPIFFE Native Support for Temporal

[vedosis]

Is your feature request related to a problem? Please describe.

SPIFFE (Secure Production Identity Framework for Everyone) is a CNCF graduated project that provides a universal identity framework for distributed systems. It's widely adopted across the cloud-native ecosystem with proven integration patterns in Envoy, Istio, Kubernetes, and many other platforms. Native SPIFFE support in Temporal would strengthen its security posture and make it significantly easier for users to deploy secure, production-ready Temporal clusters.

Currently, Temporal supports TLS/mTLS via static certificate files. While functional, this approach requires users to either manually manage certificate rotation or integrate external tooling (cert-manager, spiffe-helper) which adds operational complexity. Additionally, when users do deploy Temporal with SPIFFE certificates today, the SPIFFE IDs in those certificates (URI SANs) are not extracted or used for authorization decisions - the workload identity information is present but unused.

Native SPIFFE support would provide:

• Automatic certificate lifecycle management via the Workload API - zero manual rotation or bolt on automation
• Identity-based authorization using SPIFFE IDs to drive authorization decisions
• Simplified deployments for users already running SPIFFE/SPIRE infrastructure
• Enhanced security story aligning Temporal with cloud-native zero-trust best practices
• Smooth migration path from traditional mTLS without requiring full cutover

This would improve Temporal's security positioning and make it easier for enterprises to trust and deploy Temporal in production environments.

Describe the solution you'd like

Native SPIFFE support integrated directly into Temporal server with:

1. Automatic Certificate Management

• Direct integration with SPIFFE Workload API (Unix socket)
• Automatic X.509-SVID fetching and rotation via GetCertificate callbacks
• Trust bundle management from Workload API
• Fallback to static TLS when Workload API unavailable (for mTLS -> SPIFFE migration)

2. SPIFFE-Based Authorization

• New ClaimMapper implementation that extracts SPIFFE IDs from client certificates (extends existing ClaimMapper interface)
• Regex-based pattern matching to map SPIFFE ID paths to Temporal's existing role model
• Trust domain validation (allowlist)
• Maps to existing namespace-level and system-level permissions via the Claims struct

3. Smooth Migration Path

• Claim mapper chains that try multiple authentication methods in order (extends GetClaimMapperFromConfig to support multiple mappers)
• Support both SPIFFE and traditional mTLS during migration
• Backward compatible configuration (extends Authorization config struct)

4. Full Mesh Coverage

• All services: Frontend, History, Matching, Internal Workers
• Both internode and client-facing connections

How This Integrates with Existing Architecture

This proposal builds on Temporal's existing TLS and authorization infrastructure:

• Extends existing TLS configuration: Adds SPIFFE support to RootTLS, GroupTLS, and ServerTLS structs without breaking existing static certificate configurations
• Implements existing interfaces: New SPIFFE and TLS claim mappers implement the existing ClaimMapper interface, so they integrate seamlessly with Interceptor
• Uses existing authorization model: SPIFFE IDs map to the same Claims struct and Role types that JWT-based auth uses today
• Leverages existing TLS helpers: Uses TLSInfoFromContext and PeerCert functions to extract certificate information
• No breaking changes: All existing configurations continue to work; SPIFFE is purely additive

Technical Approach

Key design considerations:

1. Workload API integration via go-spiffe SDK - Leverages upstream caching, automatic rotation
2. GetCertificate callbacks - No background goroutines needed, fetches current cert on each TLS handshake (standard Go tls.Config pattern)
3. Claim mapper chains - Extends existing ClaimMapper interface with ordered fallback (SPIFFE → TLS → JWT) for migration flexibility
4. Per-service configuration - Extends existing RootTLS config with global SPIFFE defaults and per-service overrides
5. Trust domain validation - Optional allowlist for multi-tenant environments
6. Integrates with existing authorization - Works with existing Interceptor and Authorizer without breaking changes

I have a detailed design covering architecture, configuration schema, implementation phases, testing strategy, migration patterns, and security considerations. However, I'm looking for alignment on the approach before investing in a full implementation, not approval of specific implementation details.

Seeking Alignment

I'm looking for confirmation that this type of contribution would be accepted before dedicating engineering resources to implementation. Specific questions:

1. Is SPIFFE support something Temporal would accept? - Does native SPIFFE integration align with Temporal's roadmap and architectural direction?

2. Architecture approach - Is Workload API integration via GetCertificate callbacks acceptable? Any concerns with adding the go-spiffe SDK dependency (it's currently a transitive dependency)?

3. Configuration extension - Does extending RootTLS and Authorization structs align with Temporal's configuration philosophy? Any preference for how config should be structured? I have a recommendation if that would be helpful.

4. Authorization integration - Is extending ClaimMapper with a chain mechanism the right pattern? Any concerns with SPIFFE ID regex pattern matching for authz decisions?

5. Contribution scope - Should this be:

   • One comprehensive PR?
   • Split into multiple PRs (Core infra → Authorization → Configuration → Hardening, this would be my preference because it's touching a lot of little places)?
   • Feature-flagged initially for gradual rollout? or is a graceful fallback config sufficient?

6. Testing and documentation expectations - Beyond standard unit/integration tests, are there specific test scenarios, performance benchmarks, or documentation requirements? My expectation is to adhere to the STUNNING quality of Temporal's existing end user documentation.

7. Temporal Cloud - I've primarily focused on the Temporal Server installations, but are there any Temporal Cloud considerations that need to be added?

I'm not asking for commitment to merge or review a specific design - just alignment that this type of contribution fits Temporal's direction and would be considered if implemented according to Temporal's standards and preferences.

Commitment and Resources

This is a business priority for us. We're allocating dedicated engineering resources to implement this feature properly if Temporal confirms alignment. Our commitment includes:

• Full implementation according to Temporal's architectural standards
• Comprehensive test coverage (unit, integration, migration scenarios)
• Documentation (configuration guides, migration guides, operational runbooks)
• Long-term maintenance and support for the feature

We're not looking for Temporal to implement this - we will do the work. We just need confirmation that the general approach aligns with Temporal's direction before committing resources to a potentially incompatible implementation.

Describe alternatives you've considered

Alternative 1: Continue using external tools

• spiffe-helper to fetch SVIDs and write to disk, Temporal reads static files
• Downsides: Extra process to manage, delayed rotation, no SPIFFE-based authz

Alternative 2: Custom sidecar container

• Custom sidecar that fetches SVIDs (i.e. Istio) and updates Temporal config dynamically
• Downsides: Similar to spiffe-helper, complex deployment, still no SPIFFE-based authz

Alternative 3: Proxy-based approach (Envoy + SPIRE integration)

• Use Envoy with SPIRE SDS for certificate management
• Downsides: Additional infrastructure layer, latency overhead, doesn't solve authz problem

Why native integration is better:

• Zero external dependencies - No sidecars, no external processes
• Immediate rotation - Certificates fetched on-demand, no disk writes
• SPIFFE-aware authorization - Can make authz decisions based on workload identity
• Simpler operations - One less moving part to manage and debug

Additional context

Production context

• We're running Temporal in Kubernetes with Defakto deployed (SPIRE enhanced server + agent DaemonSet)
• All workloads in our cluster already receive SPIFFE identities
• We want Temporal to be a native citizen in this zero-trust environment

Community interest

This feature would benefit any organization using SPIFFE/SPIRE infrastructure and wanting to integrate Temporal into their zero-trust architecture. SPIFFE is a CNCF graduated project with growing adoption.

Timeline and next steps

If Temporal confirms this approach aligns with their direction, we can:

• Provide a detailed design document for technical review
• Begin implementation immediately (this is a business priority for us and we'll be committing resources to it)
• Target initial PR(s) within 4-6 weeks
• Iterate based on code review feedback

Related work

• SPIFFE Workload API spec: https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md
• go-spiffe SDK: https://github.com/spiffe/go-spiffe
• SPIRE (reference SPIFFE implementation): https://github.com/spiffe/spire

---

Looking forward to hearing whether this aligns with Temporal's roadmap and architectural direction. Happy to discuss any aspects in more detail, provide additional technical details, or adjust the approach based on Temporal's preferences and requirements.

[simvlad]

Sorry about the delay here. Thanks for opening this issue and for the thorough write-up. We appreciate the offer to implement and maintain this.

We’re open to contributions in this area. A few thoughts on the approach:

Claim Mapper

We're open to adding a new cert-based claim mapper that extracts the URI SAN from client certificates into Claims. I think it should be a generic cert-based claim mapper, not SPIFFE-specific.

The claim mapper should be deliberately simple: extract identity from the cert, populate Claims.Subject - no role mapping, no policy decisions.

Authorization

In my opinion, the Authorizer is where the logic should live for mapping a URI SAN to an authorization decision - not the (provided by Temporal) claim mapper, and not in config.

We'd prefer for users to write their own Authorizer implementation with comprehensive test coverage rather than relying on config-driven regex patterns or fallback chains. Authorization policy is hard to test and audit compare to code. Config-driven regex policies are easy to misconfigure and hard to review.

We’re also considering ways to make authorizers easier to implement/deploy without modifying Temporal server code or rebasing changes when upgrading Temporal.

Certificate Management

On Alternative 1 in your document: Temporal supports hot-reloading TLS roots/certs from disk via RootTLS.RefreshInterval, so if you’re running spiffe-helper today and it writes certs to disk, Temporal can already pick them up without a restart. SPIFFE-based authorization is largely tangential to the question of how certs are delivered.

That said, we're open to accepting a SpiffeCertProvider that fetches certs directly from the SPIFFE Workload API, given thorough test coverage. Have you looked at the existing CertProvider interface in common/rpc/encryption/tls_factory.go? This seems like natural extension point. A SpiffeCertProvider implementing this interface would slot into the existing TLS stack cleanly without changes to the rest of the plumbing.

I don't think we need to modify RootTLS, GroupTLS, and ServerTLS with SPIFFE-specific fields. These structs mix cert source configuration with TLS behavior settings and adding more source specific fields makes that worse. The CertProvider abstraction is the right layer for this, the provider brings its own configuration, keeping the shared TLS config structs clean.

Summary

We are willing to accept

1. Cert-based claim mapper - extracts URI SANs into Claims.Subject. Generic X.509, no SPIFFE dependency
2. SpiffeCertProvider - implements the existing CertProvider interface, fetches certs using the Workload API socket. Thorough test coverage would be needed for something like this.

For authorization, I'd recommend handling that in a custom Authorizer implementation on your side, with proper tests, rather than building config-driven mapping into Temporal.

Happy to discuss further. Splitting into separate, focused PRs as you suggested would be ideal.

[vedosis]

Thanks for the follow up. I'll start with the claim mapper and cert provider.

RE the Authorizer:
I understand the preference for code over config-driven policy. The practical challenge is without a plugin mechanism, anyone wanting SPIFFE-based authorization still needs a server fork. I'm happy to maintain that in a separate temporal-spiffe image for now, but I'd like to understand the timeline and direction for the Authorizer deployment improvements you mentioned. It'll determine whether SPIFFE auth is a "build your own fork" story or something the broader community can adopt easily.

Would it be useful for me to open a separate issue scoping what an Authorizer plugin mechanism might look like? Our implementation work would give us concrete requirements to contribute to that design.

[simvlad]

It doesn't really require a server fork though. Instead of using pre-built Docker images, you have to write a custom main.go that imports Temporal server as a library. Something like:

 package main

  import (
      "go.temporal.io/server/temporal"
      "go.temporal.io/server/common/authorization"
      "my-example.com/temporal-spiffe/authorizer"
  )

  func main() {
      s, err := temporal.NewServer(
          temporal.ForServices(temporal.DefaultServices),
          temporal.WithConfig(cfg),
          temporal.WithAuthorizer(authorizer.NewSPIFFEAuthorizer()),
          temporal.WithClaimMapper(func(cfg *config.Config) authorization.ClaimMapper {
              return authorizer.NewCertClaimMapper()
          }),
      )
      s.Start()
  }