Katalyst.App.Auth 1.2.1

App.Auth

Reusable authentication and authorization services for .NET applications with provider-based wiring.

This package exposes vendor-agnostic service contracts:

• IUserService for user CRUD and paginated listing.
• IRoleService for role CRUD and paginated listing.
• ISessionService for user session listing and revocation/logout.
• IGroupService for group CRUD, group role mappings, and group membership.

The first provider is Keycloak.

Pagination uses App.Core.PagedQuery and App.Core.PagedResult<T> from the Katalyst.App.Core NuGet package (1-based Page / PageSize, with Skip/Take for providers; default page size is 10). Search text for list endpoints is passed as a separate string? search parameter (not on PagedQuery).

Registration

Use AddAppAuth and choose one provider.

using App.Auth;
using App.Auth.DependencyInjection;
using App.Auth.Models;
using App.Core;

builder.Services.AddAppAuth(builder.Configuration, auth =>
{
    auth.UseKeycloak(builder.Configuration.GetSection("Auth:Keycloak"));
});

Example appsettings.json

{
  "Auth": {
    "Keycloak": {
      "BaseUrl": "http://localhost:8080",
      "Realm": "my-realm",
      "ClientId": "my-app-client",
      "ClientSecret": "base64-cipher-text",
      "ManagementClientId": "admin-cli",
      "ManagementUsername": "admin",
      "ManagementPassword": "base64-cipher-text",
      "ManagementAuthRealm": "master"
    }
  }
}

Role scope is passed directly per role operation and defaults to Client:

await roleService.CreateAsync(
    new AuthRole { Name = "auditor", Description = "Auditor role" },
    roleScope: RoleScope.Realm,
    cancellationToken: ct);

IUserService also supports explicit user status operations:

await userService.DisableAsync(userId, ct);
await userService.EnableAsync(userId, ct);

Role membership and mappings are also available:

await roleService.MapRoleToUserAsync(userId, "auditor", RoleScope.Client, ct);
await roleService.UnmapRoleFromUserAsync(userId, "auditor", RoleScope.Client, ct);
var members = await roleService.ListUsersInRoleAsync(
    "auditor",
    new PagedQuery { Page = 1, PageSize = 50 },
    RoleScope.Client,
    ct);

Session operations are also available:

var sessions = await sessionService.ListUserSessionsAsync(
    userId,
    new PagedQuery { Page = 1, PageSize = 50 },
    ct);
await sessionService.LogoutUserAsync(userId, ct);
await sessionService.RevokeUserSessionsAsync(userId, ct);

Group operations are also available:

var group = await groupService.CreateAsync(new AuthGroup { Name = "finance" }, ct);
await groupService.AssignRoleAsync(group.Id!, "auditor", RoleScope.Client, ct);
await groupService.AddUserAsync(group.Id!, userId, ct);

Service capabilities

IUserService

• CreateAsync - create user
• GetByIdAsync - get user by id
• GetByUsernameExactAsync - get user by exact username
• GetByEmailExactAsync - get user by exact email
• UpdateAsync - update user
• DeleteAsync - delete user
• ListAsync - list users with pagination
• SearchAsync - search users by username/email/free text with pagination
• CountAsync - count users (optionally filtered)
• EnableAsync - enable user
• DisableAsync - disable user
• LockAsync - lock user (provider-specific behavior; Keycloak maps this to disable)
• UnlockAsync - unlock/re-enable user sessions and state
• ResetPasswordAsync - set/reset user password (temporary or permanent)
• SetTemporaryPasswordAsync - set temporary password
• RemoveCredentialAsync - remove user credential by credential id
• SetRequiredActionsAsync - set required actions (for example UPDATE_PASSWORD, VERIFY_EMAIL, CONFIGURE_TOTP)
• SendVerifyEmailAsync - send verification email
• SendExecuteActionsEmailAsync - send execute-actions email
• SetEmailVerifiedAsync - set emailVerified flag

IRoleService

• CreateAsync - create realm/client role
• GetByNameAsync - get role by name
• UpdateAsync - update role
• DeleteAsync - delete role
• ListAsync - list roles with pagination/search
• ListUsersInRoleAsync - list users in role
• MapRoleToUserAsync - assign role to user
• UnmapRoleFromUserAsync - remove role from user
• MapRoleToGroupAsync - assign role to group
• UnmapRoleFromGroupAsync - remove role from group
• MapRoleToServiceAccountAsync - assign role to service account user
• UnmapRoleFromServiceAccountAsync - remove role from service account user

ISessionService

• ListUserSessionsAsync - list user sessions
• LogoutUserAsync - logout user/revoke active sessions
• RevokeUserSessionsAsync - revoke user sessions (provider alias of logout when applicable)

IGroupService

• CreateAsync - create group
• GetByIdAsync - get group by id
• UpdateAsync - update group
• DeleteAsync - delete group
• ListAsync - list groups with pagination/search
• AssignRoleAsync - assign realm/client role to group
• UnassignRoleAsync - unassign realm/client role from group
• AddUserAsync - add user to group
• RemoveUserAsync - remove user from group

Logging

App.Auth uses standard ASP.NET Core logging (ILogger<T>) in provider services. No package-specific logging settings are defined; logging level/output is controlled by your host application's normal logging configuration.

Tests

App.Auth.Tests includes baseline coverage for:

• DI registration and validation behavior for AddAppAuth and Keycloak configuration requirements
• cryptography round-trip for AuthCryptography.Encrypt/Decrypt
• live Keycloak integration tests for IUserService, IRoleService, ISessionService, and IGroupService

Run tests with:

dotnet test WebTemplate/App.Auth.Tests/App.Auth.Tests.csproj

Live integration tests load credentials from WebTemplate/App.Auth.Tests/appsettings.json (no environment variable fallback):

{
  "Integration": {
    "Keycloak": {
      "BaseUrl": "http://localhost:8180",
      "Realm": "cbsua",
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret",
      "ManagementClientId": "admin-cli",
      "ManagementUsername": "your-management-user",
      "ManagementPassword": "your-management-password",
      "ManagementAuthRealm": "master"
    }
  }
}

If required values are empty, integration tests are skipped.

Encrypted secrets in appsettings

Keycloak secrets support encrypted values and are decrypted inside service classes:

• Auth:Keycloak:ClientSecret
• Auth:Keycloak:ManagementClientSecret
• Auth:Keycloak:ManagementPassword

Store encrypted values as raw cipher text produced by your shared key-based Cryptography.Encrypt(...) mechanism. For backward compatibility, plain-text values are also accepted.

Keycloak UI setup for management credentials

ManagementClientId, ManagementUsername, and ManagementPassword are used to request an access token for Keycloak Admin API calls.

1) Configure ManagementClientId

• Open Keycloak Admin Console.
• Switch to the realm configured in ManagementAuthRealm (commonly master).
• Go to Clients and verify the client exists:
  • default: admin-cli
  • or your own confidential admin client

If you use the default client, keep:

"ManagementClientId": "admin-cli"

2) Configure ManagementUsername and ManagementPassword

• In the same ManagementAuthRealm, go to Users.
• Create (or select) an admin/service user.
• Set credentials in Credentials and disable Temporary.

Use those values in appsettings:

"ManagementUsername": "admin-user",
"ManagementPassword": "encrypted-or-plain-password"

3) Grant required permissions

The admin user must be allowed to manage users/roles in the target realm (Auth:Keycloak:Realm).

In the admin user Role mapping, assign appropriate admin roles (names vary by Keycloak version), typically equivalents of:

• manage-users, view-users, query-users
• manage-realm, view-realm
• query-clients, manage-clients (for client-role operations)

4) Realm alignment checks

• ManagementAuthRealm: where management client/user is defined (often master)
• Realm: where users/roles are created and managed
• ClientId: target application client for client-role operations