grpc-security

name	grpc-security
description	gRPC security best practices for ASP.NET Core — TLS configuration, JWT authentication, authorization policies, message size limits, input validation, and PII protection. Use when securing gRPC services.

gRPC Security Best Practices

Transport Layer Security (TLS)

Kestrel HTTPS Configuration

builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenLocalhost(5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("certificate.pfx", "password");
    });
});

Minimum TLS Version

listenOptions.UseHttps(httpsOptions =>
{
    httpsOptions.SslProtocols = System.Security.Authentication.SslProtocols.Tls12
                              | System.Security.Authentication.SslProtocols.Tls13;
});

Production Rule

Never serve gRPC over unencrypted HTTP/2 in production. Unencrypted HTTP/2 is acceptable only for local development.

---

Authentication

JWT Bearer Setup

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://your-identity-server";
        options.Audience = "grpc-api";
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromSeconds(30)
        };
    });

builder.Services.AddAuthorization();

Apply to Services

// All methods require auth
[Authorize]
public class UserService(ILogger<UserService> logger) : UserProto.UserProtoBase
{
    // This method allows anonymous access
    [AllowAnonymous]
    public override Task<HealthResponse> CheckHealth(Empty request, ServerCallContext context)
    {
        return Task.FromResult(new HealthResponse { Status = "Healthy" });
    }
}

Client-Side Token Injection (Interceptor)

public class AuthInterceptor(ITokenProvider tokenProvider) : Interceptor
{
    public override AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>(
        TRequest request,
        ClientInterceptorContext<TRequest, TResponse> context,
        AsyncUnaryCallContinuation<TRequest, TResponse> continuation)
    {
        var token = tokenProvider.GetToken();
        var headers = context.Options.Headers ?? new Metadata();
        headers.Add("Authorization", $"Bearer {token}");

        var newContext = new ClientInterceptorContext<TRequest, TResponse>(
            context.Method, context.Host,
            context.Options.WithHeaders(headers));

        return continuation(request, newContext);
    }
}

---

Authorization Policies

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AdminOnly", policy =>
        policy.RequireRole("Admin"));

    options.AddPolicy("ReadAccess", policy =>
        policy.RequireClaim("scope", "read"));

    options.AddPolicy("WriteAccess", policy =>
        policy.RequireClaim("scope", "write"));
});

Apply to Methods

[Authorize(Policy = "AdminOnly")]
public override Task<DeleteResponse> DeleteUser(DeleteUserRequest request, ServerCallContext context)
{
    // Only admins can delete
}

---

Message Size Limits

Server-Side

builder.Services.AddGrpc(options =>
{
    options.MaxReceiveMessageSize = 1 * 1024 * 1024; // 1 MB
    options.MaxSendMessageSize = 1 * 1024 * 1024;    // 1 MB
});

Per-Service Override

builder.Services.AddGrpc()
    .AddServiceOptions<FileUploadService>(options =>
    {
        options.MaxReceiveMessageSize = 10 * 1024 * 1024; // 10 MB for uploads
    });

Client-Side

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions
{
    MaxReceiveMessageSize = 1 * 1024 * 1024,
    MaxSendMessageSize = 1 * 1024 * 1024
});

Guidelines

• Default (null) means unlimited — always set explicit limits
• Use streaming for payloads larger than the limit
• Keep binary payloads under 85KB to avoid Large Object Heap (LOH) allocations

---

Error Handling & Information Disclosure

Development vs Production

builder.Services.AddGrpc(options =>
{
    // ONLY true in Development — exposes stack traces and exception details
    options.EnableDetailedErrors = builder.Environment.IsDevelopment();
});

Safe Error Messages

// GOOD: generic message, no internal details
throw new RpcException(new Status(StatusCode.Internal, "An unexpected error occurred."));

// BAD: leaks internal information
throw new RpcException(new Status(StatusCode.Internal, ex.ToString()));
throw new RpcException(new Status(StatusCode.Internal, $"Database error: {connectionString}"));

Error Handling Interceptor

public class ErrorHandlingInterceptor(ILogger<ErrorHandlingInterceptor> logger, IHostEnvironment env) : Interceptor
{
    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request, ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        try
        {
            return await continuation(request, context);
        }
        catch (RpcException)
        {
            throw; // Already a proper gRPC exception
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled exception in {Method}", context.Method);
            var detail = env.IsDevelopment() ? ex.Message : "An internal error occurred.";
            throw new RpcException(new Status(StatusCode.Internal, detail));
        }
    }
}

---

Input Validation

Validation Interceptor

public class ValidationInterceptor : Interceptor
{
    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request, ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        if (request is IValidatable validatable)
        {
            var errors = validatable.Validate();
            if (errors.Any())
            {
                throw new RpcException(new Status(
                    StatusCode.InvalidArgument,
                    string.Join("; ", errors)));
            }
        }
        return await continuation(request, context);
    }
}

Field Validation Rules

• String fields: check for null/empty, enforce max length
• Numeric fields: check for valid ranges
• Enum fields: reject _UNSPECIFIED (0) when a value is required
• Repeated fields: enforce maximum element count
• Byte fields: enforce maximum size

---

Logging & PII Protection

Safe Logging

// GOOD: log identifiers, not sensitive data
logger.LogInformation("Processing request for user {UserId}", request.UserId);

// BAD: logs sensitive data
logger.LogInformation("Login with password {Password}", request.Password);
logger.LogInformation("Request: {@Request}", request); // May contain PII

Rules

• Never log passwords, tokens, API keys, or credentials
• Never log full request/response objects in production (use Information level selectively)
• Use "Grpc": "Debug" log level ONLY in Development
• Do not log authentication headers in interceptors
• Anonymize user identifiers when required by privacy regulations

---

Rate Limiting

ASP.NET Core Rate Limiting Middleware

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("grpc", limiterOptions =>
    {
        limiterOptions.PermitLimit = 100;
        limiterOptions.Window = TimeSpan.FromMinutes(1);
        limiterOptions.QueueLimit = 0;
    });
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
});

app.UseRateLimiter();

Streaming Protection

• Set maximum message count per stream
• Set maximum stream duration
• Check CancellationToken in all stream processing loops
• Implement server-side timeout for idle streams

---

Mutual TLS (mTLS) / Certificate Authentication

mTLS requires both server and client to present certificates, providing strong machine-to-machine authentication without tokens.

Kestrel Configuration (Server)

builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenAnyIP(5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps(httpsOptions =>
        {
            httpsOptions.ServerCertificate = X509CertificateLoader
                .LoadPkcs12FromFile("server.pfx", "password");
            httpsOptions.ClientCertificateMode = ClientCertificateMode.RequireCertificate;
            httpsOptions.SslProtocols = SslProtocols.Tls12 | SslProtocols.Tls13;
        });
    });
});

Certificate Authentication Setup

builder.Services.AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme)
    .AddCertificate(options =>
    {
        options.AllowedCertificateTypes = CertificateTypes.Chained;
        options.RevocationMode = X509RevocationMode.Online;
        options.ValidateCertificateUse = true;
        options.ValidateValidityPeriod = true;

        options.Events = new CertificateAuthenticationEvents
        {
            OnCertificateValidated = context =>
            {
                var thumbprint = context.ClientCertificate.Thumbprint;
                var subject = context.ClientCertificate.Subject;

                var claims = new[]
                {
                    new Claim(ClaimTypes.NameIdentifier, thumbprint),
                    new Claim(ClaimTypes.Name, subject)
                };

                context.Principal = new ClaimsPrincipal(
                    new ClaimsIdentity(claims, context.Scheme.Name));
                context.Success();
                return Task.CompletedTask;
            },
            OnAuthenticationFailed = context =>
            {
                context.Fail("Invalid client certificate.");
                return Task.CompletedTask;
            }
        };
    });

builder.Services.AddAuthorization();

Client-Side mTLS

var clientCert = X509CertificateLoader.LoadPkcs12FromFile("client.pfx", "password");

var handler = new SocketsHttpHandler();
handler.SslOptions.ClientCertificates = new X509CertificateCollection { clientCert };

var channel = GrpcChannel.ForAddress("https://server:5001", new GrpcChannelOptions
{
    HttpHandler = handler
});

Certificate Thumbprint Authorization

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("TrustedClient", policy =>
        policy.RequireClaim(ClaimTypes.NameIdentifier,
            "AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00"));
});

Certificate Rotation

• Use CA-signed certificate chains, not self-signed certificates in production
• Monitor certificate expiry with health checks
• Deploy new certificates before old ones expire (overlap period)
• Use X509RevocationMode.Online to check CRL/OCSP for revoked certificates
• Store certificates in Azure Key Vault, AWS Secrets Manager, or Kubernetes Secrets — never in the repository

---

Security Checklist Summary

Category	Key Rule
TLS	Always HTTPS in production, TLS 1.2+
mTLS	Use certificate authentication for service-to-service communication
Auth	JWT Bearer with strict validation parameters
Authorization	[Authorize] on services, policies for fine-grained control
Message Size	Always set MaxReceiveMessageSize and MaxSendMessageSize
Errors	EnableDetailedErrors only in Development
Logging	Never log credentials, tokens, or PII
Validation	Validate all inputs before business logic
Rate Limiting	Protect against DoS with rate limiters
Reflection	MapGrpcReflectionService() only in Development
Interceptors	Auth interceptor first, error handler catches all
Certificates	Rotate before expiry, revoke compromised certs, never store in repo