Skip to main content

Console Configuration

The User Tasks Bridge Console is a Next.js application that provides a user interface for managing and completing User Tasks. This page explains how to configure the Console for production deployment.

Environment Variables​

The Console uses environment variables for configuration. In production, these should be set through your deployment platform's environment variable configuration (e.g., Kubernetes secrets, AWS Parameter Store, or your CI/CD pipeline). The following variables must be configured:

Authentication Configuration​

The Console uses Auth.js (formerly NextAuth.js) for authentication with your Identity Provider.

AUTH_SECRET​

A secret key used to encrypt cookies and tokens. This is required for production deployments.

  • Type: string
  • Required: Yes
  • How to generate: Run npx auth secret in your terminal
  • Security: Store this value securely using your platform's secrets management service
AUTH_SECRET=your-generated-secret-here
warning

Never commit your AUTH_SECRET to version control. Keep it secure and use environment variables or a secrets management service in production.

AUTH_KEYCLOAK_ID​

The client ID registered in your Keycloak realm for the Console application.

  • Type: string
  • Required: Yes
  • Example: user-tasks-bridge-client
AUTH_KEYCLOAK_ID=user-tasks-bridge-client

This client ID must match the client ID configured in your Keycloak realm. The client should be configured as a confidential client for production with the following settings:

  • Valid Redirect URIs: Should include your Console's callback URL (e.g., https://console.yourcompany.com/api/auth/callback/keycloak)
  • Web Origins: Should include your Console's origin (e.g., https://console.yourcompany.com)
  • Standard Flow Enabled: Yes
  • Access Type: Confidential (for production)

AUTH_KEYCLOAK_SECRET​

The client secret for your Keycloak client. Required for production deployments using confidential clients.

  • Type: string
  • Required: Yes (for production with confidential clients)
  • Security: Store this value securely using your platform's secrets management service
  • Example: your-client-secret-here
AUTH_KEYCLOAK_SECRET=your-client-secret-here
warning

For production deployments, always use a confidential client type in Keycloak, which requires this secret. Public clients are not recommended for production.

AUTH_KEYCLOAK_ISSUER​

The issuer URL of your Keycloak realm. This is the base URL where your Keycloak server is hosted, including the realm name.

  • Type: string (URL)
  • Required: Yes
  • Format: https://<keycloak-host>/realms/<realm-name>
  • Security: Must use HTTPS in production
  • Example: https://keycloak.yourcompany.com/realms/your-realm
AUTH_KEYCLOAK_ISSUER=https://keycloak.yourcompany.com/realms/your-realm
warning

Always use HTTPS for the issuer URL in production. HTTP is not secure and should never be used in production deployments.

User Tasks Bridge Configuration​

These variables configure how the Console connects to the User Tasks Bridge Backend.

LHUT_API_URL​

The base URL where your User Tasks Bridge Backend is hosted.

  • Type: string (URL)
  • Required: Yes
  • Security: Must use HTTPS in production
  • Example: https://utb.yourcompany.com
LHUT_API_URL=https://utb.yourcompany.com

The Console will make API requests to this URL. Ensure this URL is accessible from where the Console is deployed and that proper network security policies are in place.

LHUT_AUTHORITIES​

JSON paths that indicate where roles are located within the JWT token claims. These paths are used to determine user permissions (admin vs regular user).

  • Type: string (comma-separated JSON paths)
  • Required: Yes
  • Format: Comma-separated JSON path expressions
  • Example: $.realm_access.roles,$.resource_access.*.roles
LHUT_AUTHORITIES=$.realm_access.roles,$.resource_access.*.roles

These JSON paths should match the authorities configuration in your User Tasks Bridge Backend's oidc-properties.yml file. Common patterns include:

  • $.realm_access.roles - Roles at the realm level in Keycloak
  • $.resource_access.*.roles - Roles for specific resources/clients
  • $.groups - If using group-based authorization
  • $.authorities - If your IdP uses a custom authorities claim

Optional: Metrics Configuration​

The Console can optionally expose Prometheus metrics for monitoring.

LHUT_METRICS_PORT​

The port on which to expose metrics endpoints.

  • Type: number
  • Required: No
  • Default: 9464
  • Example: 9464
LHUT_METRICS_PORT=9464

LHUT_METRICS_DISABLED​

Whether to disable metrics collection and exposure.

  • Type: boolean
  • Required: No
  • Default: false
  • Example: false or true
LHUT_METRICS_DISABLED=false

Set to true to disable metrics if you don't need them.