gRPC Authentication and TLS
On this page
gRPC security: who is the server, who is the caller?
- Is this really the server I meant to call? Answered by TLS and certificate validation.
- Who is calling? Answered by per-call credentials (tokens in metadata) or mutual TLS (the client presents a certificate too).
Plaintext gRPC (insecure.NewCredentials()) is for local development only. Inside a network, unencrypted service traffic can be read and altered by anything that gets a foothold.
Setting up server TLS for gRPC
The course's lab created a private certificate authority and a server certificate valid for orders.internal, localhost and 127.0.0.1, then started the server with it:
creds, err := credentials.NewServerTLSFromFile("tls/server.crt", "tls/server.key")
if err != nil {
log.Fatal(err)
}
s := grpc.NewServer(grpc.Creds(creds))The client trusts the CA:
creds, err := credentials.NewClientTLSFromFile("tls/ca.crt", "") // "" = use the target host name
conn, err := grpc.NewClient("orders.internal:443", grpc.WithTransportCredentials(creds))Four attempts with grpcurl against the TLS server:
plaintext client -> Failed to dial target host "127.0.0.1:50443": EOF
TLS, CA not trusted -> tls: failed to verify certificate: x509: "orders.internal" certificate is not trusted
TLS with the CA -> {"order":{"id":"o1"}}
TLS, wrong server name -> x509: certificate is valid for orders.internal, localhost, not payments.internalThe last case matters: checking the name is what stops a valid certificate for another service being accepted. Never disable verification to "fix" these errors (see the security fundamentals course).
A gotcha from the lab: the first set of certificates, created with macOS's built-in LibreSSL using elliptic-curve keys, failed to load in Go with x509: invalid ECDSA parameters, because the keys were written with explicit curve parameters. Regenerating them (RSA keys, or EC keys with named curves from OpenSSL 3) fixed it.
Authenticating callers with tokens or mutual TLS
Per-call credentials: a token in metadata on every call, validated by a server interceptor (Day 16):
type tokenAuth struct{ token string }
func (t tokenAuth) GetRequestMetadata(ctx context.Context, _ ...string) (map[string]string, error) {
return map[string]string{"authorization": "Bearer " + t.token}, nil
}
func (tokenAuth) RequireTransportSecurity() bool { return true } // refuse to send over plaintext
conn, err := grpc.NewClient(target, grpc.WithTransportCredentials(creds),
grpc.WithPerRPCCredentials(tokenAuth{token: jwt}))Use short-lived tokens: OAuth client credentials, JWTs from your identity provider, or cloud workload identity (Google's oauth package, AWS SigV4 for AWS services).
Mutual TLS: the client presents a certificate, and the server verifies it with ClientAuth: tls.RequireAndVerifyClientCert. The certificate identifies the calling service. Managing certificates for every service by hand is painful, so this is usually done by a service mesh (Istio, Linkerd) or SPIFFE/SPIRE, which issue short-lived certificates automatically and rotate them.
Authorizing gRPC methods
Authentication says who; authorization says what they may do. In an interceptor, map the caller's identity (token claims or the mTLS SPIFFE ID) to allowed methods: "the checkout service may call GetOrder, only the admin tool may call DeleteOrder". Then check object-level access in handlers (see the API design course on BOLA).
Check yourself
The certificate only listed orders.internal, localhost and 127.0.0.1 in its subject alternative names. Hostname checking prevents accepting a certificate issued for a different service, which is what stops one service impersonating another.
It makes gRPC refuse to send the per-call token over an unencrypted connection, so a configuration mistake can't leak credentials in plain text.
The client also presents a certificate, so the server can verify which service is calling and authorize by that identity. It's common for service-to-service traffic, often handled by a mesh.
An interceptor extracts the caller's identity, from a verified token or the client certificate, and checks it against rules keyed by the full method name, such as /orders.v1.OrderService/CancelOrder. Unauthorized calls get PERMISSION_DENIED before the handler runs.
An attacker inside the network could otherwise read or alter calls. TLS with identity checks limits what one breach exposes.