gRPC Authentication with TLS

Analogy categoryAnalogies

TLS Fundamentals in gRPC

gRPC is built on HTTP/2, and its default expectation for production traffic is Transport Layer Security — you establish this by passing credentials.NewTLS(tlsConfig) (or grpc.WithTransportCredentials on the client, grpc.Creds on the server) rather than grpc.WithInsecure(), which is intended only for local development. TLS in gRPC does the same job it does in any HTTPS connection: the server presents a certificate chain, the client validates it against a trusted CA root, and a certificate whose Common Name or Subject Alternative Name doesn't match the dialed hostname causes the handshake to fail before any RPC method is invoked.

🏏

Cricket analogy: Like a stadium turnstile that checks every ticket's hologram against a master authority list before letting a spectator in, gRPC's TLS handshake checks the server's certificate chain against a trusted CA root before any RPC can proceed.

Mutual TLS (mTLS) for Service-to-Service Auth

Mutual TLS (mTLS) flips the verification around so the server also demands and validates a certificate from the client, which is the standard pattern for service-to-service auth inside a microservices mesh — Istio and Linkerd both issue short-lived per-pod certificates automatically and enforce mTLS at the sidecar proxy so application code never has to construct its own tls.Config. Configuring mTLS on a bare gRPC server means setting tls.Config.ClientAuth to tls.RequireAndVerifyClientCert and populating ClientCAs with the trusted CA pool, after which the server can read the verified client certificate's identity from the connection's peer info during an interceptor.

🏏

Cricket analogy: Like a domestic T20 league requiring both the player and the franchise to present verified contracts before a match, not just the player, mTLS requires both client and server to present verified certificates, not just the server.

caCert, _ := os.ReadFile("ca.pem")
certPool := x509.NewCertPool()
certPool.AppendCertsFromPEM(caCert)

serverCert, _ := tls.LoadX509KeyPair("server.pem", "server.key")
tlsConfig := &tls.Config{
    Certificates: []tls.Certificate{serverCert},
    ClientAuth:   tls.RequireAndVerifyClientCert,
    ClientCAs:    certPool,
}

srv := grpc.NewServer(grpc.Creds(credentials.NewTLS(tlsConfig)))

Combining TLS with Token-Based Auth

TLS alone authenticates the connection, not the caller, so most production gRPC services layer call credentials on top — implementing the PerRPCCredentials interface to attach a bearer token (say, an OAuth2 access token or a signed JWT) as metadata on every outgoing RPC, independent of whichever transport credentials secured the channel. Because PerRPCCredentials.RequireTransportSecurity() typically returns true, gRPC will refuse to send that token unless the underlying channel is already TLS-encrypted — this guards against a misconfiguration that would otherwise leak a bearer token over plaintext.

🏏

Cricket analogy: Like a player's central contract (identity) being separate from their match fee payment authorization (access), TLS authenticates the connection's identity while a bearer token in PerRPCCredentials authorizes what that caller can actually do.

PerRPCCredentials.RequireTransportSecurity() should almost always return true for token-based call credentials — gRPC will then refuse to attach the token unless the channel is already TLS-encrypted, preventing an accidental plaintext leak of a bearer token or JWT.

Certificate Rotation and Common Pitfalls

Certificates expire, and a service that doesn't automate rotation will eventually fail every incoming mTLS handshake the moment its cert crosses its NotAfter timestamp — the standard fix is a short-lived certificate issuer like SPIRE/SPIFFE or cert-manager that reissues certs well before expiry and reloads them into the running server via a tls.Config.GetCertificate callback rather than restarting the process. A related and much more dangerous pitfall is InsecureSkipVerify: true, which disables hostname and chain verification entirely and is sometimes left in during a debugging session, silently turning a supposedly secure mTLS deployment into one that will accept any certificate, including an attacker's.

🏏

Cricket analogy: Like a player's annual fitness certificate needing renewal well before it lapses, or they're benched mid-season, a service's TLS certificate needs automated rotation before its NotAfter date, or every mTLS handshake starts failing.

Never set tls.Config{InsecureSkipVerify: true} in a production build. It disables both hostname verification and certificate chain validation, meaning your 'secure' mTLS deployment will silently accept a self-signed certificate from any attacker who can intercept the connection.

gRPC production traffic should always use TLS; grpc.WithInsecure()/insecure credentials are for local development only.
TLS validates the server's certificate chain and hostname (CN/SAN) before any RPC is invoked.
mTLS additionally requires and validates a client certificate, standard for service-to-service auth in a mesh.
Service meshes like Istio and Linkerd automate mTLS with short-lived, per-pod certificates via sidecars.
PerRPCCredentials layers token-based auth (OAuth2/JWT) on top of TLS, and typically requires transport security.
Certificate rotation must be automated (e.g. via SPIFFE/SPIRE or cert-manager) to avoid handshake failures at expiry.
InsecureSkipVerify: true disables all certificate validation and must never ship to production.