https://{host}/realms/{realm}/.well-known/openid-configuration

dotnet add package Microsoft.AspNetCore.Authentication.OpenIdConnect

// Program.cs
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
    options.Authority = "https://keycloak.example.com/realms/my-realm";
    options.ClientId = "my-dotnet-app";
    options.ClientSecret = "my-client-secret";
    options.ResponseType = "code";
    options.SaveTokens = true;
});

app.UseAuthentication();
app.UseAuthorization();

.AddOpenIdConnect(options =>
{
    options.Authority = "https://keycloak.example.com/realms/my-realm";
    options.ClientId = "my-dotnet-app";
    options.ClientSecret = "your-secret-here";
    options.ResponseType = "code";
    options.SaveTokens = true;
    options.GetClaimsFromUserInfoEndpoint = true;
    options.RequireHttpsMetadata = true;
    options.MapInboundClaims = false;

    options.Scope.Clear();
    options.Scope.Add("openid");
    options.Scope.Add("profile");
    options.Scope.Add("email");
    options.Scope.Add("roles");

    options.TokenValidationParameters = new TokenValidationParameters
    {
        NameClaimType = "preferred_username",
        RoleClaimType = "realm_access.roles",
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidAudience = "my-dotnet-app",
    };

    options.Events = new OpenIdConnectEvents
    {
        OnTokenValidated = context =>
        {
            // Extract realm roles and add as standard role claims
            var identity = context.Principal?.Identity as ClaimsIdentity;
            var realmAccess = context.Principal?
                .FindFirst("realm_access")?.Value;

            if (realmAccess != null)
            {
                var parsed = JsonDocument.Parse(realmAccess);
                if (parsed.RootElement.TryGetProperty("roles", out var roles))
                {
                    foreach (var role in roles.EnumerateArray())
                    {
                        identity?.AddClaim(new Claim(
                            ClaimTypes.Role,
                            role.GetString()!
                        ));
                    }
                }
            }
            return Task.CompletedTask;
        },
    };
});

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

        // Realm roles
        var realmAccess = principal.FindFirst("realm_access")?.Value;
        if (realmAccess != null)
        {
            var parsed = JsonDocument.Parse(realmAccess);
            if (parsed.RootElement.TryGetProperty("roles", out var roles))
            {
                foreach (var role in roles.EnumerateArray())
                {
                    identity.AddClaim(new Claim(ClaimTypes.Role, role.GetString()!));
                }
            }
        }

        // Client roles
        var resourceAccess = principal.FindFirst("resource_access")?.Value;
        if (resourceAccess != null)
        {
            var parsed = JsonDocument.Parse(resourceAccess);
            if (parsed.RootElement.TryGetProperty("my-dotnet-app", out var client)
                && client.TryGetProperty("roles", out var clientRoles))
            {
                foreach (var role in clientRoles.EnumerateArray())
                {
                    identity.AddClaim(new Claim(ClaimTypes.Role, role.GetString()!));
                }
            }
        }

        return Task.FromResult(principal);
    }
}

// Register in Program.cs
builder.Services.AddTransient<IClaimsTransformation, KeycloakRolesClaimsTransformation>();

// In a controller or endpoint (requires SaveTokens = true)
var accessToken = await HttpContext.GetTokenAsync("access_token");
var refreshToken = await HttpContext.GetTokenAsync("refresh_token");
var idToken = await HttpContext.GetTokenAsync("id_token");

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://keycloak.example.com/realms/my-realm";
        options.Audience = "my-api-client";
    });

app.UseAuthentication();
app.UseAuthorization();

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://keycloak.example.com/realms/my-realm";
        options.Audience = "my-api-client";
        options.RequireHttpsMetadata = true;
        options.MapInboundClaims = false;
        options.SaveToken = true;

        options.TokenValidationParameters = new TokenValidationParameters
        {
            NameClaimType = "preferred_username",
            RoleClaimType = ClaimTypes.Role,
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromSeconds(30),
        };

        options.Events = new JwtBearerEvents
        {
            OnTokenValidated = context =>
            {
                // Transform Keycloak nested roles into flat role claims
                return Task.CompletedTask;
            },
            OnAuthenticationFailed = context =>
            {
                Console.WriteLine($"Auth failed: {context.Exception.Message}");
                return Task.CompletedTask;
            },
        };
    });

// Require authentication
[Authorize]
public class SecureController : ControllerBase { }

// Require specific role
[Authorize(Roles = "admin")]
public IActionResult AdminOnly() => Ok();

// Policy-based authorization
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("CanEditPosts", policy =>
        policy.RequireRole("editor", "admin"));

    options.AddPolicy("PremiumUser", policy =>
        policy.RequireClaim("subscription", "premium"));
});

[Authorize(Policy = "CanEditPosts")]
public IActionResult EditPost() => Ok();

Step 1: Redirect user to Keycloak
GET https://keycloak.example.com/realms/my-realm/protocol/openid-connect/auth
    ?client_id=my-dotnet-app
    &redirect_uri=https://myapp.com/signin-oidc
    &response_type=code
    &scope=openid profile email
    &state=random-csrf-token
    &nonce=random-nonce
    &code_challenge=BASE64URL(SHA256(code_verifier))
    &code_challenge_method=S256

Step 2: User logs in, Keycloak redirects back
GET https://myapp.com/signin-oidc?code=AUTH_CODE&state=random-csrf-token

Step 3: Server exchanges code for tokens
POST https://keycloak.example.com/realms/my-realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://myapp.com/signin-oidc
&client_id=my-dotnet-app
&client_secret=your-secret
&code_verifier=ORIGINAL_RANDOM_STRING

var client = new HttpClient();
var content = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "authorization_code",
    ["code"] = authCode,
    ["redirect_uri"] = "https://myapp.com/signin-oidc",
    ["client_id"] = "my-dotnet-app",
    ["client_secret"] = "your-secret",
    ["code_verifier"] = codeVerifier,
});

var response = await client.PostAsync(
    "https://keycloak.example.com/realms/my-realm/protocol/openid-connect/token",
    content);
var json = await response.Content.ReadFromJsonAsync<JsonDocument>();
var accessToken = json.RootElement.GetProperty("access_token").GetString();
var refreshToken = json.RootElement.GetProperty("refresh_token").GetString();
var idToken = json.RootElement.GetProperty("id_token").GetString();

POST https://keycloak.example.com/realms/my-realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=my-service
&client_secret=service-secret
&scope=openid

var content = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_id"] = "my-service",
    ["client_secret"] = "service-secret",
    ["scope"] = "openid",
});

var response = await httpClient.PostAsync(tokenEndpoint, content);
var token = (await response.Content.ReadFromJsonAsync<JsonDocument>())
    .RootElement.GetProperty("access_token").GetString();

// Use it
var apiClient = new HttpClient();
apiClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

POST https://keycloak.example.com/realms/my-realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN_HERE
&client_id=my-dotnet-app
&client_secret=your-secret

POST https://keycloak.example.com/realms/my-realm/protocol/openid-connect/token/introspect
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN_HERE
&client_id=my-dotnet-app
&client_secret=your-secret

POST https://keycloak.example.com/realms/my-realm/protocol/openid-connect/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN_HERE
&token_type_hint=refresh_token
&client_id=my-dotnet-app
&client_secret=your-secret

// Using a service account with admin roles
var content = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_id"] = "admin-cli",
    ["client_secret"] = "admin-secret",
});

var response = await httpClient.PostAsync(
    "https://keycloak.example.com/realms/master/protocol/openid-connect/token",
    content);
var token = (await response.Content.ReadFromJsonAsync<JsonDocument>())
    .RootElement.GetProperty("access_token").GetString();

httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", adminToken);

var user = new
{
    username = "newuser",
    email = "[email protected]",
    firstName = "New",
    lastName = "User",
    enabled = true,
    emailVerified = true,
    credentials = new[]
    {
        new
        {
            type = "password",
            value = "initial-password",
            temporary = true
        }
    }
};

var response = await httpClient.PostAsJsonAsync(
    "https://keycloak.example.com/admin/realms/my-realm/users",
    user);

// New user ID is in the Location header
var userId = response.Headers.Location?.Segments.Last();

dotnet add package Keycloak.AuthServices.Sdk

// Program.cs
builder.Services.AddKeycloakAdminHttpClient(builder.Configuration);

// appsettings.json
{
  "Keycloak": {
    "realm": "my-realm",
    "auth-server-url": "https://keycloak.example.com/",
    "resource": "admin-cli",
    "credentials": {
      "secret": "admin-secret"
    }
  }
}

// In a service
public class UserService
{
    private readonly IKeycloakUserClient _userClient;

    public UserService(IKeycloakUserClient userClient)
        => _userClient = userClient;

    public async Task<IEnumerable<UserRepresentation>> GetUsers()
        => await _userClient.GetUsers("my-realm");

    public async Task CreateUser(string username, string email)
        => await _userClient.CreateUser("my-realm", new UserRepresentation
        {
            Username = username,
            Email = email,
            Enabled = true,
        });
}

// Program.cs — same OpenID Connect setup as MVC
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
    options.Authority = "https://keycloak.example.com/realms/my-realm";
    options.ClientId = "blazor-server-app";
    options.ClientSecret = "secret";
    options.ResponseType = "code";
    options.SaveTokens = true;
    options.MapInboundClaims = false;
});

<AuthorizeView>
    <Authorized>
        <p>Hello, @context.User.Identity?.Name</p>
    </Authorized>
    <NotAuthorized>
        <p>Please log in.</p>
    </NotAuthorized>
</AuthorizeView>

@* Require a role *@
<AuthorizeView Roles="admin">
    <Authorized>
        <p>Admin content here.</p>
    </Authorized>
</AuthorizeView>

// 1. Token provider service
public class TokenProvider
{
    public string AccessToken { get; set; } = "";
    public string RefreshToken { get; set; } = "";
}

// 2. Register as scoped
builder.Services.AddScoped<TokenProvider>();

// 3. Populate in _Host.cshtml (during initial HTTP request)
@inject TokenProvider TokenProvider
@{
    TokenProvider.AccessToken = await HttpContext.GetTokenAsync("access_token") ?? "";
    TokenProvider.RefreshToken = await HttpContext.GetTokenAsync("refresh_token") ?? "";
}

// 4. Inject in any component
@inject TokenProvider TokenProvider
// Use TokenProvider.AccessToken to call APIs

dotnet add package Microsoft.AspNetCore.Components.WebAssembly.Authentication

// Program.cs (Blazor WASM)
builder.Services.AddOidcAuthentication(options =>
{
    options.ProviderOptions.Authority =
        "https://keycloak.example.com/realms/my-realm";
    options.ProviderOptions.ClientId = "blazor-wasm-app";
    options.ProviderOptions.ResponseType = "code";

    options.ProviderOptions.DefaultScopes.Add("openid");
    options.ProviderOptions.DefaultScopes.Add("profile");
    options.ProviderOptions.DefaultScopes.Add("email");

    options.ProviderOptions.PostLogoutRedirectUri = "https://myapp.com/";
    options.ProviderOptions.RedirectUri =
        "https://myapp.com/authentication/login-callback";
});

<AuthorizeView>
    <Authorized>
        <span>Hello, @context.User.Identity?.Name</span>
        <button @onclick="Logout">Log out</button>
    </Authorized>
    <NotAuthorized>
        <a href="authentication/login">Log in</a>
    </NotAuthorized>
</AuthorizeView>

@code {
    private async Task Logout()
    {
        await SignOutManager.SetSignOutState();
        Navigation.NavigateTo("authentication/logout");
    }
}

using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;

public class ManualTokenValidator
{
    private readonly HttpClient _httpClient = new();
    private readonly string _authority;

    public ManualTokenValidator(string authority) => _authority = authority;

    public async Task<ClaimsPrincipal?> ValidateToken(string token)
    {
        // Fetch JWKS
        var jwksJson = await _httpClient.GetStringAsync(
            $"{_authority}/protocol/openid-connect/certs");
        var jwks = new JsonWebKeySet(jwksJson);

        var handler = new JwtSecurityTokenHandler();
        var parameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = _authority,
            ValidateAudience = true,
            ValidAudience = "my-client",
            ValidateLifetime = true,
            IssuerSigningKeys = jwks.GetSigningKeys(),
            ClockSkew = TimeSpan.FromSeconds(30),
        };

        try
        {
            return handler.ValidateToken(token, parameters, out _);
        }
        catch (SecurityTokenException)
        {
            return null;
        }
    }
}

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidAudience = "my-api",
        };

        options.Events = new JwtBearerEvents
        {
            OnMessageReceived = async context =>
            {
                var tenant = context.Request.Headers["X-Tenant"].FirstOrDefault();
                if (string.IsNullOrEmpty(tenant))
                {
                    context.Fail("No tenant specified");
                    return;
                }

                var authority = $"https://keycloak.example.com/realms/{tenant}";
                context.Options.TokenValidationParameters.ValidIssuer = authority;

                // Fetch and cache JWKS per tenant
            }
        };
    });

// Front-channel logout (redirect-based)
public IActionResult Logout()
{
    return SignOut(
        new AuthenticationProperties { RedirectUri = "/" },
        CookieAuthenticationDefaults.AuthenticationScheme,
        OpenIdConnectDefaults.AuthenticationScheme
    );
}
// The middleware builds:
// GET /realms/{realm}/protocol/openid-connect/logout
//   ?id_token_hint=ID_TOKEN
//   &post_logout_redirect_uri=https://myapp.com/signout-callback-oidc

// Back-channel logout (server-to-server)
// Keycloak POSTs to your app when a session ends elsewhere
app.MapPost("/backchannel-logout", async (HttpContext context) =>
{
    var form = await context.Request.ReadFormAsync();
    var logoutToken = form["logout_token"].ToString();
    // Validate the logout_token JWT
    // Extract "sid" claim, invalidate matching local session
    return Results.Ok();
});
// Register in Keycloak: Backchannel Logout URL = https://myapp.com/backchannel-logout

var content = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "urn:ietf:params:oauth:grant-type:token-exchange",
    ["subject_token"] = originalAccessToken,
    ["subject_token_type"] = "urn:ietf:params:oauth:token-type:access_token",
    ["requested_token_type"] = "urn:ietf:params:oauth:token-type:access_token",
    ["client_id"] = "service-a",
    ["client_secret"] = "service-a-secret",
    ["audience"] = "service-b",
});

var response = await httpClient.PostAsync(tokenEndpoint, content);

public class AppClaimsTransformation : IClaimsTransformation
{
    private readonly IUserRepository _users;

    public AppClaimsTransformation(IUserRepository users) => _users = users;

    public async Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        var identity = (ClaimsIdentity)principal.Identity!;
        var keycloakId = principal.FindFirst("sub")?.Value;
        if (keycloakId == null) return principal;

        // Load app-specific data
        var appUser = await _users.GetByExternalId(keycloakId);
        if (appUser != null)
        {
            identity.AddClaim(new Claim("app_user_id", appUser.Id.ToString()));
            identity.AddClaim(new Claim("subscription_tier", appUser.Tier));
            foreach (var perm in appUser.Permissions)
                identity.AddClaim(new Claim("permission", perm));
        }

        // Flatten nested realm roles
        var realmAccess = principal.FindFirst("realm_access")?.Value;
        if (realmAccess != null)
        {
            using var doc = JsonDocument.Parse(realmAccess);
            if (doc.RootElement.TryGetProperty("roles", out var roles))
                foreach (var role in roles.EnumerateArray())
                    identity.AddClaim(new Claim(ClaimTypes.Role, role.GetString()!));
        }

        return principal;
    }
}

builder.Services.AddTransient<IClaimsTransformation, AppClaimsTransformation>();

// SignalR sends tokens via query string for WebSocket connections
options.Events = new JwtBearerEvents
{
    OnMessageReceived = context =>
    {
        var accessToken = context.Request.Query["access_token"];
        var path = context.HttpContext.Request.Path;

        if (!string.IsNullOrEmpty(accessToken)
            && path.StartsWithSegments("/hubs"))
        {
            context.Token = accessToken;
        }
        return Task.CompletedTask;
    }
};

[Authorize]
public class ChatHub : Hub
{
    public override Task OnConnectedAsync()
    {
        var user = Context.User?.FindFirst("preferred_username")?.Value;
        return base.OnConnectedAsync();
    }
}

# docker-compose.yml
version: '3.8'
services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start-dev
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"