KerberosCCache 1.0.0

KerberosCCache

A lightweight .NET utility to dynamically set the KRB5CCNAME environment variable at runtime on Linux for Kerberos authentication.

Overview

The KerberosCCache NuGet package provides a safe and efficient way to programmatically set the KRB5CCNAME environment variable in .NET applications running on Linux. This variable tells Kerberos-aware tools (like kinit, curl, or .NET’s HttpClient with SPNEGO) where to find the Kerberos credentials cache (ticket file).

This is especially useful in containerized or server-side scenarios where your application needs to:

• Impersonate different users,
• Manage multiple Kerberos identities,
• Switch tickets dynamically (e.g., per HTTP request in a reverse-proxy setup).

⚠️ Only supported on Linux. Windows and macOS use native authentication mechanisms and do not rely on KRB5CCNAME.

Limitations & Known Issues

Known Limitations:

• Only affects the current process and its child processes—does not modify the parent shell’s environment.
• Requires read access to the specified cache file path.
• Does not validate whether the cache file exists or is valid—only sets the environment variable.

⚠️ On non-Linux platforms, Kerberos authentication uses native mechanisms (SSPI on Windows, KCM on macOS) and ignores KRB5CCNAME. This package is not applicable outside Linux.

Getting Started

1. Install the Package

Install via the .NET CLI:

dotnet add package KerberosCCache

Or via Package Manager Console:

Install-Package KerberosCCache

2. Use in Your Code

Add the namespace and call the static method:

using KerberosCCache;

// Set the Kerberos credentials cache path
KerberosCache.SetKrb5Cache("/tmp/krb5cc_1000");

That’s it! Your application (and any child processes) will now use the specified Kerberos ticket cache.

Visual Guide

Typical workflow in a Linux container:

+---------------------+
| .NET App (Linux)    |
|                     |
| Calls:              |
| SetKrb5Cache(...)   |
+----------+----------+
           |
           v
+---------------------+
| Environment Variable|
| KRB5CCNAME = /tmp/...|
+----------+----------+
           |
           v
+---------------------+
| Kerberos Client     |
| (e.g., curl, kinit) |
| Uses ticket from    |
| specified cache     |
+---------------------+

Examples

Example 1: Basic Usage

try
{
    KerberosCache.SetKrb5Cache("/tmp/krb5cc_custom");
    Console.WriteLine("KRB5CCNAME set successfully.");
}
catch (PlatformNotSupportedException ex)
{
    Console.WriteLine($"Platform not supported: {ex.Message}");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Failed to set KRB5CCNAME: {ex.Message}");
}

Example 2: Avoid Overwriting Existing Value

// Only set if KRB5CCNAME is not already defined
KerberosCache.SetKrb5Cache("/tmp/krb5cc_backup", overwrite: false);

🔒 The overwrite parameter maps directly to the overwrite argument in the underlying setenv() C function (1 = overwrite, 0 = do not overwrite).

Sample Project Snippet

This is an example of a minimal ASP.NET Core application that uses KerberosCCache to dynamically switch Kerberos credentials per HTTP request—ideal for reverse-proxy authentication (e.g., Apache + mod_auth_kerb or nginx + SPNEGO).

⚠️ Important: For Kerberos delegation to work end-to-end, the client browser must be configured to allow credential delegation to your service domain.

Browser Configuration (Firefox Example)

In Firefox, users (or administrators) must configure the following settings in about:config:

Application Code

using System;
using Npgsql;
using KerberosCCache;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);
        var app = builder.Build();

        // Map a secure endpoint that uses Kerberos delegation
        app.MapGet("/api/data", async(HttpContext context) => await GetDataAsync(context));
        app.Run();
    }

    /// <summary>
    /// Handles an authenticated request by switching to the user's Kerberos ticket cache
    /// and connecting to a PostgreSQL database using GSSAPI (Kerberos) authentication.
    /// </summary>
    /// <param name="context">The current HTTP context.</param>

    public static async Task GetDataAsync(HttpContext context)
    {

        // ⚠️ SECURITY:
        // These headers (X_KRB5CCNAME, X_GSS_NAME) must ONLY be set by a trusted reverse proxy
        // (e.g., Apache with mod_auth_kerb or nginx with SPNEGO module).
        // Never accept them from untrusted clients!

        // Get user's credential cache (KRB5CCNAME) and username from headers

        if (!context.Request.Headers.TryGetValue("X_KRB5CCNAME", out var krb5ccname) ||
            !context.Request.Headers.TryGetValue("X_GSS_NAME", out var gssName))
        {
            context.Response.StatusCode = 400;
            await context.Response.WriteAsync("Missing auth headers.");
            return;
        }

        try
        {
            // Dynamically set KRB5CCNAME (user's credential cache) for the current process
            // This affects all subsequent Kerberos operations in this process

            KerberosCache.SetKrb5Cache(krb5_path);

            // Connect to PostgreSQL using GSSAPI (Kerberos) authentication
            // 'Include Realm=true' ensures the realm is used during auth

            string cs = $"Host=my.example.com;Database=postgres;Include Realm=true;Username={user};";

            using var con = new NpgsqlConnection(cs);

            await con.OpenAsync();
            ...
        }
        catch (Exception ex)
        {
	        ...
        }
        finally
        {
            con.Close();
            ...
        }
}

Required Packages (*.csproj)

<PackageReference Include="KerberosCCache" Version="1.0.0" />
<PackageReference Include="Npgsql" Version="7.0.0" />
<PackageReference Include="Microsoft.AspNetCore.App" Version="7.0.0" />

Important Security & Deployment Notes

1. Trusted Headers Only

The headers X_KRB5CCNAME and X_GSS_NAME must be injected by a trusted reverse proxy (e.g., Apache with mod_auth_kerb or mod_auth_gssapi). Never allow end-users to set these directly.

2. Thread Safety

Since KRB5CCNAME is a process-wide environment variable, changing it affects all threads in the application. → This example assumes one request at a time or that all concurrent requests belong to the same user. → For true multi-tenancy, consider:

• Using separate processes per user (e.g., via gunicorn-style workers), or
• Leveraging Kerberos impersonation with constrained delegation (advanced).

3. File Permissions

Ensure the .NET process has read access to the Kerberos cache file (e.g., /tmp/krb5cc_XXXX).

4. Linux Only This will fail on Windows/macOS with PlatformNotSupportedException. Deploy only on Linux.

Additional Resources

• Kerberos Documentation (MIT)
• .NET on Linux with Kerberos – Microsoft Guide
• Understanding KRB5CCNAME