Security Overview
The Voltimax IoT Platform uses Keycloak Authorization Services for identity management and fine-grained access control. Keycloak acts as both the Identity Provider (IdP) and the Policy Decision Point (PDP), meaning all authorization decisions are evaluated server-side by Keycloak rather than being encoded in application logic.
Architecture
Request flow:
- The frontend (or any client) authenticates via OIDC and obtains a JWT access token
- The Platform API receives the token and, for each protected endpoint, asks Keycloak to evaluate whether the token holder has the required resource + scope permission
- Keycloak evaluates its configured policies and returns an allow/deny decision
- The API enforces the decision
Key Concepts
| Concept | Description |
|---|---|
| Resource | A domain entity that can be protected (e.g., gateways, assets, metrics) |
| Scope | An action that can be performed on a resource (read, write, delete) |
| Policy | A rule evaluated by Keycloak to determine access (e.g., "user has role platform-admin") |
| Permission | Links a resource + scope to one or more policies - the actual access grant |
| Role | A client role assigned to users that policies reference |
Components
MigrationService (Provisioning)
The MigrationService is the single source of truth for the Keycloak configuration. It runs on startup and uses the Keycloak Admin API to provision:
- Realm and OIDC clients
- Client roles (
platform-admin,platform-operator,platform-viewer,gateway-device) - Authorization settings - resources, scopes, policies, and permissions
All configuration is defined in code in KeycloakRealmConfiguration and imported atomically via the Admin API's import endpoint. See Provisioning for details.
Platform API (Enforcement)
The API uses the Keycloak.AuthServices.Authorization NuGet package to integrate with Keycloak's Authorization Services. Endpoints declare their required permissions using RequirePermission(), which delegates authorization evaluation to Keycloak. See API Protection for details.
Keycloak (Decision Making)
Keycloak evaluates authorization requests against its configured resources, scopes, policies, and permissions. It uses the UMA (User-Managed Access) protocol under the hood, with the API client acting as the resource server.
Roles
Four client roles are defined on the iot-platform-api client: platform-admin, platform-operator, platform-viewer, and gateway-device. Roles are assigned to users (or service accounts) in Keycloak, and role-based policies map these roles to permissions.
The current role definitions and their permission mappings can be found in KeycloakRealmConfiguration or inspected in the Keycloak admin console. See Authorization Model for how the model works.
Technology
The implementation uses the Keycloak.AuthServices .NET library by Nikiforov, which provides:
Keycloak.AuthServices.Authentication- OIDC/JWT integration for ASP.NET CoreKeycloak.AuthServices.Authorization-RequireProtectedResource()for policy enforcementKeycloak.AuthServices.Sdk.Kiota- Kiota-based Admin API client for provisioning
Next Steps
- Authorization Model - resources, scopes, policies, and permissions in detail
- API Protection - how endpoints declare and enforce permissions
- Provisioning - how the MigrationService configures Keycloak
- Frontend Authentication - how the Vue SPA handles login and role-based UI