Voltimax Platform

Appearance

Authentication ​

The Voltimax frontend authenticates users against Keycloak using the OpenID Connect (OIDC) protocol with the Proof Key for Code Exchange (PKCE) extension. This provides secure, standards-compliant authentication for the web application.

Authentication flow ​

The frontend follows a standard OAuth 2.0 authorization code flow with PKCE:

When you visit the application, the Keycloak Vue plugin automatically handles the entire flow. If you're not authenticated, you're redirected to Keycloak's login page. After successful authentication, the plugin stores your access and refresh tokens and manages token renewal automatically.

Configuration ​

The frontend authenticates against the iot-frontend OIDC client configured during Keycloak provisioning. Configuration uses environment variables (VITE_KEYCLOAK_URL, VITE_KEYCLOAK_REALM, VITE_KEYCLOAK_CLIENT_ID), typically set in .env.local for local development.

INFO

The .env.local file should not be committed to git. Use .env.example for template defaults.

Using authentication in components ​

Use the useKeycloak() composable from @voltimax/vue-keycloak to access authentication state. It returns reactive refs for isAuthenticated, username, userId, token, decodedToken, roles, resourceRoles, and the raw keycloak instance. It also exposes isPending, hasFailed, and error for tracking initialization.

typescript
import { useKeycloak } from '@voltimax/vue-keycloak';

const { isAuthenticated, username, token, roles } = useKeycloak();

Role-based UI visibility ​

The frontend can show or hide UI elements based on the user's client roles. Use hasResourceRoles() to check roles assigned on the iot-platform-api client:

typescript
const { hasResourceRoles } = useKeycloak();

// Check for admin role
const isAdmin = computed(() => hasResourceRoles(['platform-admin'], 'iot-platform-api'));

The available client roles (platform-admin, platform-operator, platform-viewer, gateway-device) are defined in Keycloak on the iot-platform-api client. See the Security Overview for role descriptions.

Frontend checks are for UI only

Role checks in the frontend control UI visibility, not access. The actual authorization is enforced server-side by Keycloak acting as the Policy Decision Point (PDP). Even if a user bypasses the frontend checks, the API will reject unauthorized requests. See Security Overview for the full authorization architecture.

Token management ​

Tokens are available via the composable's token and decodedToken refs. Use keycloak.value?.updateToken(minValidity) to trigger a manual refresh. The Keycloak Vue plugin handles automatic renewal.

API request interceptor ​

The frontend automatically adds the access token to all API requests - no manual token handling is needed.

Handling authentication errors ​

The composable's isPending, hasFailed, and error refs track initialization state. Common issues: verify VITE_KEYCLOAK_URL is correct, the realm exists in Keycloak, the client ID matches, and redirect URIs are configured.

Development workflow ​

For local development, the .NET Aspire AppHost automatically starts a Keycloak container. Run dotnet run --project src/Voltimax.Iot.AppHost and Keycloak will be available at http://localhost:8080.

To log out, call keycloak.value?.logout() - this clears local tokens and redirects to Keycloak's logout endpoint.