Join our Newsletter — 33% off our NHI Course
Home› Guides› gRPC Security Guide: TLS, Authentication and Interceptors
Guide Web & API Security

gRPC Security Guide: TLS, Authentication and Interceptors

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 26 October 2026 16 min read
On this page

gRPC services are usually built for internal service-to-service traffic, and that assumption is exactly why so many of them run without TLS, without per-call authorisation and with reflection switched on. gRPC itself provides strong building blocks: TLS and mutual TLS transport credentials, per-call credentials carried in metadata, interceptors for cross-cutting checks, and a standard authorisation policy engine in some languages. None of them are enforced by default. This guide covers transport security, service and caller authentication, authorisation with interceptors and policies, resource limits for HTTP/2, error handling and observability for gRPC services in Go, Java, C++, Python and other languages. It is written for backend engineers, platform teams and application security reviewers, and it goes deeper on gRPC specifics than the general Microservices Security Guide.

Key takeaways

  • Insecure credentials are a deliberate choice, not a default to keep. Every production channel should use TLS 1.2 or later, and service-to-service channels should use mutual TLS with short-lived certificates.
  • Authentication and authorisation are separate layers. Transport credentials prove which workload is connecting; call credentials in metadata (OAuth tokens, JWTs) prove who the call is for. Authorise every method against both.
  • Unary interceptors do not protect streams. Register both unary and stream interceptors, or a whole class of streaming methods will run without checks.
  • HTTP/2 needs explicit limits. Set maximum message sizes, concurrent streams, keepalive enforcement and deadlines; CVE-2023-44487 (HTTP/2 Rapid Reset) is in CISA's Known Exploited Vulnerabilities catalogue.
  • Reflection is a map of your API. Disable server reflection in production unless the service is meant for external discovery, and keep error messages generic.

The gRPC security model

gRPC runs over HTTP/2 and serialises messages with Protocol Buffers. Its authentication API is built on two kinds of credentials, as the gRPC documentation describes:

  • Channel credentials: attached to a channel and applied to the whole connection. TLS (SslCredentials in C++, credentials.NewTLS in Go, grpc.ssl_channel_credentials in Python) and Google's ALTS are channel credentials.
  • Call credentials: attached to an individual call and sent as metadata, for example an OAuth 2.0 access token in the authorization header.
  • Composite credentials: CompositeChannelCredentials binds a channel credential and a call credential so every call on a TLS channel automatically carries a token. Most gRPC implementations refuse to send call credentials over an insecure channel, which is a useful safety net, not a reason to rely on plaintext elsewhere.
  • Interceptors: middleware that runs before the handler on the server (and around the call on the client). This is where authentication, authorisation, rate limiting, logging and tracing belong.

The gRPC documentation also warns that Google-issued OAuth tokens should only be sent to Google services: sending them to your own service exposes a token that can impersonate the client to Google. The same rule generalises: an access token should be accepted only by the audience it was issued for (ASVS V10.3.1).

Transport security: TLS and mutual TLS

OptionWhat it provesUse whenWatch out for
Insecure (plaintext h2c)NothingLocal development and unit tests onlyinsecure.NewCredentials(), usePlaintext() or add_insecure_port reaching production code paths
Server-side TLSThe server's identity to the client; encryptionPublic APIs where callers authenticate with tokensClients that skip hostname verification or trust any certificate
Mutual TLSBoth workload identities, plus encryptionService-to-service traffic inside and across clustersAccepting any certificate from a broad internal CA without checking the identity (ASVS V12.1.3)
Mesh-provided mTLS (sidecar or ambient)Workload identity issued by the mesh, often SPIFFE IDsKubernetes estates with a service meshTraffic between the application and its local proxy is plaintext; services bypassing the mesh
ALTSGoogle workload identityWorkloads on Google Compute Engine or GKENot portable to other environments
  • Protocol version: grpc-go's TLS credentials set MinVersion to TLS 1.2 when the caller has not configured one, because HTTP/2 requires it. Set TLS 1.3 where both ends support it, and disable weak suites through your TLS library configuration.
  • Certificate identity: with mTLS, decide which field carries identity (a SPIFFE URI SAN such as spiffe://example.org/ns/payments/sa/api, or a DNS SAN) and check it in an interceptor or policy. A valid chain alone proves only that some workload got a certificate from your CA.
  • Lifetime and rotation: the OWASP gRPC cheat sheet recommends certificates of 90 days or less with automated rotation. Workload identity systems such as SPIRE issue certificates valid for hours. Make sure servers reload certificates without restart (grpc-go's advancedtls package and certificate providers support this). See the SPIFFE and SPIRE Guide and the mTLS Guide.
  • Private keys: the TLS private key of a gRPC service is a non-human credential. Keep it out of images and repositories, mount it from a secrets store, and restrict read access to the service's runtime identity.

Authenticating callers

Most real deployments need two identities on every call: the calling workload (from mTLS) and the end user or client application on whose behalf it acts (from a token). The OWASP gRPC cheat sheet advises passing credentials in metadata, such as the authorization header for bearer tokens, rather than in message fields, so interceptors can validate them uniformly and they are not logged with payloads.

MechanismCarried inStrengthsWeaknesses
mTLS client certificateTLS handshakeStrong workload identity, no shared secret on the wireIdentifies the workload, not the user; needs PKI operations
OAuth 2.0 access token (JWT or opaque)authorization: Bearer ... metadataStandard scopes and audiences; short-lived (15 to 60 minutes per OWASP)Replayable if stolen unless sender-constrained (ASVS V10.3.5)
Static API keyCustom metadata such as x-api-keySimple for external partnersLong-lived, hard to rotate, often shared; avoid for internal calls
Cloud workload identity tokenMetadata, issued by the platformNo stored secret; tied to the runtime identityPlatform specific; audience must be checked
  • Validate fully: check signature, issuer, audience, expiry and not-before for JWTs, and reject the none algorithm. See the JWT Security Guide.
  • Machine callers: service accounts calling gRPC APIs should obtain tokens through the client credentials grant or workload identity federation rather than holding static keys. See the Machine-to-Machine OAuth (Client Credentials) Guide.
  • Propagation: when service A calls service B on a user's behalf, exchange the user token for a narrower downstream token instead of forwarding the original. See the OAuth Token Exchange and Delegation Guide.
  • Status codes: return UNAUTHENTICATED (16) when credentials are missing or invalid and PERMISSION_DENIED (7) when the caller is known but not allowed. gRPC's status code guidance says PERMISSION_DENIED must not be used when the caller cannot be identified.

Interceptors and authorisation

Interceptor design

Interceptors are the enforcement point for most gRPC security controls. In Go they are registered with grpc.ChainUnaryInterceptor(...) and grpc.ChainStreamInterceptor(...); in Java with ServerInterceptors.intercept(); in Python with the interceptors argument to grpc.server().

  • Cover both call types: the OWASP cheat sheet stresses that token validation in a unary interceptor covers unary calls only. Server streaming, client streaming and bidirectional methods need the stream interceptor too.
  • Order matters: run recovery (panic handling) first, then authentication, then authorisation, then rate limiting keyed on the authenticated identity, then logging and tracing. Rate limiting before authentication should key on the connection's peer address, not on forwarded headers the client can set (ASVS V4.1.3).
  • Default deny: build an explicit map of full method names (/package.Service/Method) to required permissions, and reject any method missing from the map. A new RPC added without a policy entry should fail closed, not open.
  • Long-lived streams: a bidirectional stream may outlive the token that opened it. Re-check authorisation on sensitive messages within the stream, or cap stream duration so callers must reconnect and re-authenticate.
  • Object-level checks: interceptors can authorise the method; only the handler knows which record is requested. Check resource ownership in the handler as well, the gRPC equivalent of broken object level authorisation in REST APIs. See the Top 10 API Security Risks.

gRPC authorisation policies

The gRPC project's A43 proposal defines a standard JSON authorisation policy, implemented in C++, C-core and Go (in Go as authz.NewStatic for a fixed policy and authz.NewFileWatcher for a policy file reloaded on an interval). A policy has deny_rules and allow_rules; deny rules are evaluated first, then allow rules, and a request that matches no allow rule is denied. Rules match on the peer's principals (identities from the certificate) and on request paths and headers. A deny rule therefore wins even over an administrator's allow rule, which is the behaviour you want for methods that must never be called by a given principal.

Decision guidance. Use the built-in policy engine or mesh authorisation (for example an Istio AuthorizationPolicy keyed on SPIFFE principals) for coarse service-to-service rules: which workload may call which method. Use application interceptors and handler logic for user-level and object-level decisions that depend on token claims and data. Small teams with a handful of services can start with an interceptor and a method permission map; larger estates benefit from central policy so rules are reviewed in one place. See the Service Mesh Security Guide.

Resource limits and HTTP/2 abuse

HTTP/2 multiplexing lets one connection carry many concurrent streams, and protobuf decoding allocates memory for whatever arrives. Without limits, a single client can exhaust a server (ATT&CK T1499.003, Application Exhaustion Flood). In October 2023 the HTTP/2 Rapid Reset technique, CVE-2023-44487, used rapid stream creation and cancellation to cause denial of service at very large scale; CISA lists it as a known exploited vulnerability. The grpc-go advisory for this issue fixed it in versions 1.56.3, 1.57.1 and 1.58.3 and recommends setting grpc.MaxConcurrentStreams to bound what a single connection can consume.

Controlgrpc-go optiongRPC Core channel argumentDefault and guidance
Max received messagegrpc.MaxRecvMsgSizeGRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH4 MB in grpc-go; lower it per service to the largest legitimate message
Max sent messagegrpc.MaxSendMsgSizeGRPC_ARG_MAX_SEND_MESSAGE_LENGTHEffectively unlimited in grpc-go (math.MaxInt32); set a ceiling
Concurrent streams per connectiongrpc.MaxConcurrentStreamsGRPC_ARG_MAX_CONCURRENT_STREAMSSet explicitly; the key Rapid Reset mitigation
Header list sizegrpc.MaxHeaderListSizeGRPC_ARG_MAX_METADATA_SIZEBound metadata to stop oversized headers
Keepalive abusegrpc.KeepaliveEnforcementPolicyGRPC_ARG_HTTP2_MIN_RECV_PING_INTERVAL_WITHOUT_DATA_MS, GRPC_ARG_HTTP2_MAX_PING_STRIKESCore defaults: 5 minutes, 2 strikes, then GOAWAY with ENHANCE_YOUR_CALM
Connection agekeepalive.ServerParameters{MaxConnectionAge}GRPC_ARG_MAX_CONNECTION_AGE_MSForces reconnection, re-authentication and load rebalancing
Deadlinescontext.WithTimeout on client; enforce a server maximumPer-call deadlineNever allow calls without a deadline; OWASP's example caps server work at 5 seconds
  • Streams need their own limits: per-message limits do not cap a stream's total volume. Limit message counts and stream duration for client and bidirectional streams.
  • Validate content: protobuf enforces types, not business rules. Validate lengths, ranges, enums and formats in the handler or with a validation plugin such as protovalidate (the successor to protoc-gen-validate), and use parameterised queries for any data that reaches a database. See the Input Validation and Output Encoding Guide.
  • Rate limiting: apply per-identity limits that are shared across replicas. See the Rate Limiting and API Abuse Guide and the DDoS Protection Guide.

Reflection, errors and exposed metadata

  • Server reflection: the reflection service lets tools such as grpc_cli and grpcurl list services and build requests without the .proto files. That is useful in development and equivalent to publishing your full API schema in production, comparable to GraphQL introspection (ASVS V4.3.2). Register it only in non-production builds, or restrict it to an authenticated admin principal. Attackers use exposed reflection for service discovery (ATT&CK T1046 covers network service discovery).
  • Health checks: the standard grpc.health.v1.Health service is needed by load balancers and Kubernetes probes. It reveals little, but keep it on the same authenticated listener or a separate internal port, not a public one.
  • Error messages: return generic status messages to clients and log details server-side with a correlation ID (ASVS V16.5.1). Avoid putting stack traces, SQL errors or internal host names in the status message or in grpc-status-details-bin trailers.
  • Metadata hygiene: metadata keys ending in -bin carry binary values and are often skipped by log scrubbers. Strip internal headers at the edge, and never trust identity headers such as x-user-id that a client could set unless a trusted proxy overwrites them.
  • gRPC-Web and transcoding: gateways that expose gRPC to browsers or as JSON REST (Envoy gRPC-Web filter, grpc-gateway) bring CORS, cookie and CSRF concerns back. Apply browser-facing controls at the gateway and keep the gRPC service authenticating independently.

Implementation roadmap

  1. Inventory: list every gRPC server and client, its language and gRPC version, listeners and ports, credential type (insecure, TLS, mTLS), and whether reflection is registered. Search code for insecure.NewCredentials, WithInsecure, usePlaintext, add_insecure_port and reflection registration.
  2. Patch: upgrade gRPC libraries past the CVE-2023-44487 fixes and any later advisories, and set MaxConcurrentStreams, message sizes and keepalive enforcement in a shared server constructor.
  3. Encrypt: enable TLS on all listeners. Introduce mTLS in permissive mode first (accept both, log which callers are not presenting certificates) where a mesh supports it, then switch to strict once the logs show no plaintext callers.
  4. Authenticate and authorise: add unary and stream interceptors for token validation and a method permission map with default deny. Deploy a policy in audit or dry-run mode where your engine supports it (Istio supports a dry-run annotation), compare decisions with real traffic, then enforce.
  5. Test: add tests that call every method without credentials, with another service's identity, and over a stream, expecting UNAUTHENTICATED or PERMISSION_DENIED. Fuzz message decoding and send oversized messages expecting RESOURCE_EXHAUSTED.
  6. Roll out and roll back: change one service pair at a time behind a configuration flag. If error rates for UNAVAILABLE or PERMISSION_DENIED rise, revert the flag to permissive mode rather than removing TLS.
  7. Operate: automate certificate rotation, review the method permission map with each API change, and remove reflection from release builds through CI checks.

Detection and measurement

  • What to log: for every call, the full method name, authenticated workload and user identity, peer address, status code, deadline and duration. Never log tokens or full payloads containing personal data.
  • What to alert on: spikes in UNAUTHENTICATED or PERMISSION_DENIED from one principal, calls to unknown methods (UNIMPLEMENTED) that suggest enumeration, reflection requests in production, GOAWAY ENHANCE_YOUR_CALM events, and high stream reset rates on a connection.
  • Tracing: OpenTelemetry gRPC instrumentation gives per-method latency and status, and correlates calls across services during an investigation.

Metrics that show the programme is working:

  1. Percentage of gRPC listeners using TLS, and percentage of internal connections using mTLS (target 100% for production).
  2. Percentage of methods covered by an explicit authorisation rule (target 100%, with default deny for the rest).
  3. Number of production services with reflection enabled (target zero, or a documented exception).
  4. Median certificate lifetime and number of certificate expiry incidents.
  5. Percentage of services with explicit message size, concurrent stream and deadline limits.

Framework mapping

Control areaNIST SP 800-53 Rev. 5NIST CSF 2.0OWASP ASVS 5.0ATT&CK technique addressed
TLS and mTLS transportSC-8, SC-13, SC-17PR.DS-02V12.1.3, V12.3.4T1557 Adversary-in-the-Middle
Service and caller authenticationIA-9, IA-5PR.AA-03V10.3.1, V10.3.5T1552.001 Credentials In Files (key and token storage)
Per-method authorisationAC-3, AC-6PR.AA-05V4.1.3T1190 Exploit Public-Facing Application
Resource limitsSC-5PR.PS-06No direct requirementT1499.003 Application Exhaustion Flood
Reflection off, least functionalityCM-7PR.PS-01V13.4.2T1046 Network Service Discovery
Errors, logging and monitoringSI-11, AU-2, AU-12PR.PS-04, DE.CM-09V16.5.1Supports detection of all of the above

In ISO/IEC 27001:2022 Annex A, this work sits mainly under A.8.20 (networks security), A.8.24 (use of cryptography), A.8.26 (application security requirements) and A.8.28 (secure coding). CIS Controls v8.1 Control 16 (Application Software Security) and Control 3 (Data Protection, including encryption of data in transit) apply.

Common failure patterns

  • "It is internal, so plaintext is fine": gRPC services on flat networks with insecure credentials, letting any compromised pod read or replay traffic, including tokens in metadata.
  • mTLS without identity checks: the server trusts any certificate from the cluster CA, so every workload can call every method, including administrative ones.
  • Unary-only interceptors: authentication added to UnaryInterceptor while streaming methods (often the bulk export or sync endpoints) run unauthenticated.
  • Reflection shipped to production: left on from development, giving anyone who reaches the port a full list of services, methods and message schemas.
  • No limits or deadlines: default concurrent streams, unbounded send sizes and calls without deadlines, leaving servers exposed to Rapid Reset style abuse and slow-client exhaustion.
  • Trusting identity metadata: handlers that read x-user-id or similar headers set by the caller rather than claims from a validated token.

Practitioner checklist

  • Remove insecure credentials from all production code paths and enforce TLS 1.2 or later (1.3 where possible).
  • Use mTLS for service-to-service calls and check the peer identity (SPIFFE ID or SAN), not just the chain.
  • Carry user and client tokens in authorization metadata and validate issuer, audience, expiry and signature.
  • Register both unary and stream interceptors, with a default-deny method permission map.
  • Check object-level access in handlers, not only method-level access in interceptors.
  • Set MaxConcurrentStreams, receive and send message limits, keepalive enforcement, connection age and deadlines.
  • Upgrade gRPC libraries past CVE-2023-44487 fixes and track new advisories.
  • Disable server reflection in production and keep health checks off public listeners.
  • Return generic status messages and log method, identity, status and duration without tokens.
  • Automate certificate issuance and rotation with short lifetimes.

Standards and references

Related NHI Mgmt Group resources: Microservices Security Guide · mTLS Guide · Secure API Design Guide · Cloud Workload Identity Guide · Flask Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 26 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.