Xeku.Keycloak.WebApi 0.0.0.7

Xeku.Keycloak.WebApi

This module facilitates the integration of Keycloak JWT authentication into DevExpress XAF Web API applications (v22.2+). It supports hybrid authentication, allowing both XAF's native authentication and Keycloak's external authentication to coexist.

Features

• Hybrid Authentication: Seamlessly supports both XAF native JWT and Keycloak JWT tokens.
• Smart Routing: Automatically routes authentication requests to the correct scheme based on the Token Issuer using ForwardDefaultSelector.
• User Mapping: Provides a generic KeycloakAuthenticationProvider to map Keycloak users (via preferred_username) to XAF application users.
• Easy Configuration: Simple appsettings.json configuration.

Installation

1. NuGet Package:

dotnet add package Xeku.Keycloak.WebApi

2. In your Startup.cs or Program.cs:

using Xeku.Keycloak.WebApi;
// ...

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddXafAspNetCoreSecurity(Configuration, options =>
    {
        // ...
    })
    .AddAuthenticationStandard(options =>
    {
        options.IsSupportChangePassword = true;
    })
    // 1. Register Keycloak Authentication Provider (Replace ApplicationUser with your XAF user class)
    .AddAuthenticationProvider<KeycloakAuthenticationProvider<ApplicationUser>>();

    // ...

    // 2. Register Keycloak Web API Services
    services.AddXekuKeycloakWebApi<ApplicationUser>(Configuration);
    // ...
}

Configuration

Add the following section to your appsettings.json:

{
  "Authentication": {
    "Keycloak": {
      "Authority": "http://localhost:8080/realms/your-realm",
      "Audience": "your-client-id",
      "RequireHttpsMetadata": false, // Set to true in production
      "NameClaimType": "preferred_username" // Optional, default is "preferred_username"
    }
  }
}

Important Keycloak Configuration

This module enables Audience Validation (ValidateAudience = true) by default for security. You MUST configure a mapper in Keycloak, otherwise you will encounter 401 Unauthorized errors.

Follow these steps to configure the Audience Mapper:

1. Log in to the Keycloak Admin Console.
2. Go to Clients → Select your Client (e.g., xekuweb).
3. Go to the Client scopes tab.
4. Click on xekuweb-dedicated (usually named <client-id>-dedicated).
5. Click Add mapper → By configuration.
6. Select Audience.
7. In the configuration page:
   • Name: Enter Audience Mapper (or any name).
   • Included Client Audience: Enter your Client ID (e.g., xekuweb).
   • Add to access token: Toggle On.
8. Click Save.

After this configuration, the Access Token issued by Keycloak will include your Client ID in the aud claim, allowing validation to pass.

How It Works

1. Token Validation: The module adds a JWT Bearer handler named "Keycloak".
2. Request Routing: It intercepts the Authorization header. If the token's Issuer matches the configured Keycloak Authority, the request is forwarded to the "Keycloak" handler. Otherwise, it falls back to the default handler (XAF).
3. User Resolution: Once validated, the KeycloakAuthenticationProvider extracts the user name (from preferred_username) and searches for a matching ApplicationUser in the XAF database. If found, the user is logged in.

Cache Integration (Optional)

Inject ICacheService into KeycloakAuthenticationProvider for improved user lookup performance:

// Register with caching
services.AddSingleton<IAuthenticationProvider>(sp =>
    new KeycloakAuthenticationProvider<ApplicationUser>(
        sp.GetRequiredService<IHttpContextAccessor>(),
        options,
        sp.GetRequiredService<ILogger<KeycloakAuthenticationProvider<ApplicationUser>>>(),
        sp.GetRequiredService<ICacheService>()  // Optional cache service
    ));

Requirements

• .NET 6.0 or higher (Targeting .NET 8.0)
• DevExpress XAF 22.2 or higher
• Xeku.Cache (optional, for caching support)