Add gRPC Interceptor Support for Kerberos Authentication

[makr-code]

📋 Summary

Implement a gRPC server interceptor to enable Kerberos/GSSAPI authentication for gRPC-based inter-shard communication and client connections.

Parent Feature: Issue #[parent-issue-number] - Kerberos/GSSAPI Authentication Support

🔍 Problem Statement

Current State

• ✅ Kerberos authentication implemented for HTTP/REST API
• ✅ AuthMiddleware supports Kerberos
• ❌ gRPC services lack Kerberos authentication support
• ❌ Inter-shard gRPC communication uses other authentication methods

Customer Need

Enterprise customers using gRPC need:

1. Consistent authentication across HTTP and gRPC endpoints
2. Mutual authentication for secure inter-shard communication
3. SSO integration for gRPC clients
4. Kerberos-based service-to-service authentication

Business Impact

Without gRPC Kerberos Support:

• Inconsistent authentication across protocols
• Cannot use Kerberos for inter-shard communication
• Reduced security for distributed deployments

With gRPC Kerberos Support:

• ✅ Unified authentication across all protocols
• ✅ Secure service-to-service communication
• ✅ Complete enterprise SSO integration

🎯 Requirements

Functional Requirements

FR-1: Server-Side Interceptor

• Implement KerberosServerInterceptor class
• Extract GSSAPI token from gRPC metadata
• Validate token using existing GSSAPIAuthenticator
• Add authenticated principal to gRPC context
• Support for multiple authentication methods (Kerberos + JWT)

FR-2: Client-Side Support

• Implement KerberosClientInterceptor class
• Acquire GSSAPI security context
• Add authentication token to gRPC metadata
• Automatic ticket renewal on expiration
• Error handling and retry logic

FR-3: Configuration

• Configure Kerberos for gRPC in config.yaml
• Per-service authentication requirements
• Fallback authentication options
• Integration with existing KerberosConfig

FR-4: Authorization

• Integrate with RBAC system
• Method-level authorization checks
• Principal-to-role mapping for gRPC calls
• Audit logging for gRPC authentication events

Non-Functional Requirements

NFR-1: Performance

• Minimal overhead (<5ms per call)
• Context caching to avoid repeated authentication
• Connection pooling with authenticated sessions

NFR-2: Compatibility

• Compatible with existing gRPC services
• Backward compatible with non-Kerberos clients
• Support for both unary and streaming RPCs

🛠️ Technical Design

Server Interceptor

// File: include/rpc/kerberos_interceptor.h
class KerberosServerInterceptor : public grpc::experimental::Interceptor {
public:
    explicit KerberosServerInterceptor(GSSAPIAuthenticator* authenticator);
    
    void Intercept(grpc::experimental::InterceptorBatchMethods* methods) override;
    
private:
    GSSAPIAuthenticator* authenticator_;
    
    std::string extractToken(const std::multimap<grpc::string_ref, grpc::string_ref>& metadata);
    bool validateAndSetContext(grpc::ServerContext* context, const std::string& token);
};

Client Interceptor

// File: include/rpc/kerberos_client_interceptor.h
class KerberosClientInterceptor : public grpc::experimental::ClientInterceptor {
public:
    explicit KerberosClientInterceptor(const std::string& service_principal);
    
    void Intercept(grpc::experimental::InterceptorBatchMethods* methods) override;
    
private:
    std::string service_principal_;
    gss_ctx_id_t context_;
    
    std::string acquireToken();
};

Usage Example

// Server-side
auto authenticator = std::make_shared<GSSAPIAuthenticator>();
authenticator->initialize(kerberos_config);

ServerBuilder builder;
builder.experimental().SetInterceptorCreators({
    std::make_unique<KerberosServerInterceptorFactory>(authenticator.get())
});

// Client-side
auto channel = grpc::CreateCustomChannel(
    server_address,
    grpc::InsecureChannelCredentials(),
    grpc::ChannelArguments()
);

auto interceptor = std::make_unique<KerberosClientInterceptor>(
    "themisdb/server@REALM.COM"
);

// Add interceptor to channel

📝 Implementation Plan

Phase 1: Server Interceptor (Week 1)

• Task 1.1: Create KerberosServerInterceptor class
• Task 1.2: Implement token extraction from metadata
• Task 1.3: Integrate with GSSAPIAuthenticator
• Task 1.4: Add principal to gRPC context
• Task 1.5: Unit tests for server interceptor

Phase 2: Client Interceptor (Week 2)

• Task 2.1: Create KerberosClientInterceptor class
• Task 2.2: Implement GSSAPI context acquisition
• Task 2.3: Add token to outgoing metadata
• Task 2.4: Ticket renewal logic
• Task 2.5: Unit tests for client interceptor

Phase 3: Integration & Testing (Week 3)

• Task 3.1: Integrate with shard RPC services
• Task 3.2: End-to-end testing with real KDC
• Task 3.3: Performance benchmarks
• Task 3.4: Update documentation
• Task 3.5: Example code and tutorials

✅ Acceptance Criteria

Functional Acceptance

• gRPC server accepts Kerberos-authenticated calls
• gRPC client can authenticate using Kerberos tickets
• Principal extracted and available in gRPC context
• Authorization checks work correctly
• Fallback to other auth methods when Kerberos unavailable

Technical Acceptance

• Unit test coverage >80%
• Integration tests pass with test KDC
• Authentication overhead <5ms
• No memory leaks (Valgrind clean)
• Compatible with existing gRPC services

Documentation Acceptance

• gRPC Kerberos setup guide
• Client and server code examples
• Configuration reference
• Troubleshooting section

🧪 Testing Strategy

Unit Tests

• Token extraction from metadata
• Invalid token handling
• Context caching logic
• Ticket renewal logic

Integration Tests

• End-to-end authentication with test KDC
• Service-to-service authentication
• Streaming RPC authentication
• Fallback authentication

📚 References

• gRPC Interceptors
• Kerberos Implementation PR
• GSSAPIAuthenticator Documentation

🔗 Related Issues

• Parent: Issue #[parent-issue-number] - Kerberos/GSSAPI Authentication Support
• Related: Issue #[audit-logging-issue] - Kerberos Audit Logging
• Related: Issue #[metrics-issue] - Kerberos Metrics

💬 Notes

Dependencies:

• Requires Kerberos/GSSAPI authentication implementation (completed)
• Requires gRPC support enabled (THEMIS_ENABLE_GRPC=ON)

Estimated Effort: 3 weeks (1 developer)

---

Created: 2026-01-12 (Future Enhancement from Kerberos Implementation)
Status: 📋 Planned
Priority: MEDIUM
Labels: type:enhancement, area:security, area:networking, priority:P2, effort:medium