public static IServiceCollection AddWFAuthentication(
    this IServiceCollection services,
    IConfiguration configuration,
    IWebHostEnvironment environment)
{
    // Register claims transformation for role mapping
    services.AddTransient<IClaimsTransformation, KeycloakRolesClaimsTransformation>();

    var keycloakOptions = configuration.GetSection("Keycloak").Get<KeycloakOptions>()
        ?? new KeycloakOptions
        {
            BaseUrl = "http://localhost:8080",
            Realm = "wallet-realm"
        };

    var authority = $"{keycloakOptions.BaseUrl}/realms/{keycloakOptions.Realm}";

    services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    })
    .AddJwtBearer(options =>
    {
        options.Authority = authority;
        options.RequireHttpsMetadata = environment.IsProduction();
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateAudience = environment.IsProduction(),
            ValidateIssuer = true,
            ValidIssuer = authority
        };
    });

    return services;
}

public class KeycloakRolesClaimsTransformation : IClaimsTransformation
{
    public Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        var claimsIdentity = principal.Identity as ClaimsIdentity;
        if (claimsIdentity == null || !claimsIdentity.IsAuthenticated)
        {
            return Task.FromResult(principal);
        }

        // Skip if roles already transformed
        if (claimsIdentity.HasClaim(c => c.Type == ClaimTypes.Role && c.Value.StartsWith("wf-")))
        {
            return Task.FromResult(principal);
        }

        // Extract roles from realm_access claim
        var realmAccessClaim = claimsIdentity.FindFirst("realm_access");
        if (realmAccessClaim != null && !string.IsNullOrWhiteSpace(realmAccessClaim.Value))
        {
            using var document = JsonDocument.Parse(realmAccessClaim.Value);
            var root = document.RootElement;

            if (root.TryGetProperty("roles", out var rolesElement) && rolesElement.ValueKind == JsonValueKind.Array)
            {
                foreach (var roleElement in rolesElement.EnumerateArray())
                {
                    var role = roleElement.GetString();
                    // Only add roles prefixed with "wf-"
                    if (!string.IsNullOrWhiteSpace(role) && role.StartsWith("wf-", StringComparison.OrdinalIgnoreCase))
                    {
                        claimsIdentity.AddClaim(new Claim(ClaimTypes.Role, role));
                    }
                }
            }
        }

        return Task.FromResult(principal);
    }
}

services.AddAuthorization(options =>
{
    // Service-to-service communication
    options.AddPolicy("ServiceToService", policy =>
    {
        policy.RequireAuthenticatedUser();
        policy.RequireClaim("azp", "wallet-client", "fraud-client");
    });

    // Admin-only access
    options.AddPolicy("Admin", policy =>
        policy.RequireRole(KeycloakRoles.Admin.GetRoleName()));

    // Customer access
    options.AddPolicy("Customer", policy =>
        policy.RequireRole(KeycloakRoles.Customer.GetRoleName()));

    // Officer access (includes Admin)
    options.AddPolicy("Officer", policy =>
        policy.RequireRole(
            KeycloakRoles.Admin.GetRoleName(), 
            KeycloakRoles.Officer.GetRoleName()));

    // Support access (includes Admin and Officer)
    options.AddPolicy("Support", policy =>
        policy.RequireRole(
            KeycloakRoles.Admin.GetRoleName(), 
            KeycloakRoles.Officer.GetRoleName(), 
            KeycloakRoles.Support.GetRoleName()));
});

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/customers")]
public class CustomersController : BaseController
{
    [HttpPost]
    [AllowAnonymous]  // Public registration endpoint
    public async Task<IActionResult> Register([FromBody] CreateCustomerCommand command)
    {
        // Registration logic
    }
}

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/customers")]
[Authorize]  // Requires authentication, any role
public class CustomersController : BaseController
{
    [HttpGet("{id}")]
    public async Task<IActionResult> GetCustomer(Guid id)
    {
        // Customer can only access their own data
        // Additional authorization logic in handler
    }
}

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/admin/customers")]
[Authorize(Policy = "Admin")]  // Requires wf-admin role
public class AdminCustomersController : BaseController
{
    [HttpGet]
    public async Task<IActionResult> GetAllCustomers()
    {
        // Admin-only operation
    }
}

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/internal/customers")]
[Authorize(Policy = "ServiceToService")]  // Requires service client credentials
[ApiExplorerSettings(IgnoreApi = true)]  // Hidden from Swagger
public class CustomerInternalController : BaseController
{
    [HttpGet("by-identity/{identityId}")]
    public async Task<IActionResult> GetCustomerByIdentity(string identityId)
    {
        // Internal service-to-service call
    }
}

public class KeycloakTokenService : IKeycloakTokenService
{
    public async Task<TokenResult> GetTokenAsync(CancellationToken cancellationToken = default)
    {
        using var httpClient = httpClientFactory.CreateClient("Keycloak");
        
        var tokenEndpoint = $"{options.Value.BaseUrl}/realms/{options.Value.Realm}/protocol/openid-connect/token";

        var requestBody = new Dictionary<string, string>
        {
            { "grant_type", "client_credentials" },
            { "client_id", options.Value.ClientId },
            { "client_secret", options.Value.ClientSecret }
        };

        var request = new HttpRequestMessage(HttpMethod.Post, tokenEndpoint)
        {
            Content = new FormUrlEncodedContent(requestBody)
        };

        var response = await httpClient.SendAsync(request, cancellationToken);
        response.EnsureSuccessStatusCode();

        var tokenResponse = await response.Content.ReadFromJsonAsync<TokenResponse>(JsonOptions, cancellationToken);
        
        return new TokenResult
        {
            AccessToken = tokenResponse.AccessToken,
            ExpiresIn = tokenResponse.ExpiresIn
        };
    }
}

public class TokenCacheService : ITokenCacheService
{
    private const string CacheKey = "service_auth_token";
    private const int RefreshBufferSeconds = 60;  // Refresh 60 seconds before expiry
    private readonly SemaphoreSlim _semaphore = new(1, 1);

    public async Task<string> GetTokenAsync(CancellationToken cancellationToken = default)
    {
        // Check cache first
        var cachedToken = await GetCachedTokenAsync(cancellationToken);
        if (cachedToken != null && !IsTokenExpiringSoon(cachedToken))
        {
            return cachedToken.Token;
        }

        // Thread-safe token refresh
        await _semaphore.WaitAsync(cancellationToken);
        try
        {
            // Double-check after acquiring lock
            cachedToken = await GetCachedTokenAsync(cancellationToken);
            if (cachedToken != null && !IsTokenExpiringSoon(cachedToken))
            {
                return cachedToken.Token;
            }

            // Refresh token from Keycloak
            var tokenResult = await keycloakTokenService.GetTokenAsync(cancellationToken);
            
            // Cache with expiry
            var cacheExpirySeconds = Math.Max(tokenResult.ExpiresIn - RefreshBufferSeconds, 30);
            var cacheOptions = new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(cacheExpirySeconds)
            };

            await distributedCache.SetStringAsync(
                CacheKey,
                JsonSerializer.Serialize(new CachedToken { Token = tokenResult.AccessToken, ... }),
                cacheOptions,
                cancellationToken);

            return tokenResult.AccessToken;
        }
        finally
        {
            _semaphore.Release();
        }
    }
}

public class ServiceAuthenticationHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        try
        {
            var token = await tokenCacheService.GetTokenAsync(cancellationToken);
            
            if (!string.IsNullOrWhiteSpace(token))
            {
                request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
                logger.LogDebug("Service authentication token added to outgoing request {RequestUri}", request.RequestUri);
            }
            else
            {
                logger.LogWarning("No service authentication token available for request {RequestUri}", request.RequestUri);
            }
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Failed to add service authentication token to request {RequestUri}", request.RequestUri);
        }

        return await base.SendAsync(request, cancellationToken);
    }
}

// In DependencyInjectionExtensions.cs
services.AddHttpClient<ICustomerServiceApiClient, CustomerServiceApiClient>()
    .AddHttpMessageHandler<ServiceAuthenticationHandler>();

services.AddHttpClient<IWalletServiceApiClient, WalletServiceApiClient>()
    .AddHttpMessageHandler<ServiceAuthenticationHandler>();

public static void AddVaultConfiguration(
    this IConfigurationBuilder configurationBuilder, 
    IConfiguration configuration)
{
    var vaultOptions = configuration.GetSection("Vault");
    var enabled = vaultOptions.GetValue<bool>("Enabled");

    if (!enabled)
    {
        return;  // Skip Vault in development if disabled
    }

    var address = vaultOptions.GetValue<string>("Address");
    var token = vaultOptions.GetValue<string>("Token");

    if (string.IsNullOrEmpty(address) || string.IsNullOrEmpty(token))
    {
        return;
    }

    // Add shared secrets
    configurationBuilder.AddVaultConfiguration(
        () => new VaultOptions(address, token, reloadOnChange: true, reloadCheckIntervalSeconds: 600),
        "wallet/shared",
        "secret"
    );

    // Add service-specific secrets
    var assemblyName = Assembly.GetEntryAssembly()?.GetName().Name;
    string? serviceName = null;
    if (assemblyName != null)
    {
        var parts = assemblyName.Split('.');
        if (parts.Length > 1)
        {
            serviceName = parts[1].ToLower();  // e.g., "customerservice"
        }
    }

    if (!string.IsNullOrEmpty(serviceName))
    {
        configurationBuilder.AddVaultConfiguration(
            () => new VaultOptions(address, token, reloadOnChange: true, reloadCheckIntervalSeconds: 600),
            $"wallet/{serviceName}",
            "secret"
        );
    }
}

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/internal/customers")]
[Authorize(Policy = "ServiceToService")]  // Only service clients
[ApiExplorerSettings(IgnoreApi = true)]   // Hidden from Swagger
public class CustomerInternalController : BaseController
{
    [HttpGet("by-identity/{identityId}")]
    public async Task<IActionResult> GetCustomerByIdentity(string identityId)
    {
        // Internal service-to-service call
    }
}

if (builder.Environment.IsDevelopment())
{
    options.AddPolicy("AllowAll", policy =>
    {
        policy.AllowAnyOrigin()
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
}