Auth Helper configuration

DIAL Auth Helper (epam/ai-dial-auth-helper) is a Spring Boot service that implements OpenID-compatible endpoints for identity provider integration. It rewrites the standard OpenID Connect well-known configuration to route user info requests through its own enrichment endpoint, which supplements user data with job title and profile picture from the identity provider.

Auth Helper has been tested with Microsoft Graph API. It requires Keycloak to inject idp and idpAlias claims into the access token.

Configuration method

Auth Helper is configured via application.yaml (bundled in the container image) or environment variables following Spring Boot relaxed binding conventions. For example, the YAML setting oauth2.providerUri maps to the environment variable OAUTH2_PROVIDERURI.

Settings reference

YAML setting	Env var	Default	Required	Description
server.hostUrl	SERVER_HOSTURL	http://localhost:4088	Yes	Public URL of the Auth Helper service. Used for userinfo_endpoint substitution in the well-known configuration response. Must include protocol and port.
server.port	SERVER_PORT	4088	No	HTTP port for the application.
oauth2.providerUri	OAUTH2_PROVIDERURI	http://localhost:8080/realms/your_realm	Yes	OpenID Connect provider URL. Used to fetch the well-known configuration and token verification URLs.
oauth2.clientId	OAUTH2_CLIENTID	chatbot-ui	Yes	Client ID registered in the identity provider.
oauth2.clientSecret	OAUTH2_CLIENTSECRET	your_client_secret	Yes	Client secret for the registered client.
oauth2.jwksUriPath	OAUTH2_JWKSURIPATH	jwks_uri	No	Path to the jwks_uri node in the OpenID Connect well-known configuration. Override when the identity provider uses a non-standard field name.
scheduled.poolSize	SCHEDULED_POOLSIZE	2	No	Thread pool size for scheduled tasks (e.g., periodic token refresh).

API endpoints

Auth Helper exposes two public endpoints:

Endpoint	Method	Description
/.well-known/openid-configuration	GET	Returns the identity provider's OpenID Connect configuration with the userinfo_endpoint rewritten to point to Auth Helper.
/api/v1/user/user-info	GET	Fetches user information from the identity provider and enriches it with additional claims (job title, profile picture). Requires a valid access token in the Authorization header.

Keycloak prerequisites

Auth Helper requires Keycloak to include identity provider metadata in access tokens. The idp and idpAlias claims must be mapped in the Keycloak client configuration. These claims allow Auth Helper to determine which upstream identity provider issued the token and route the user info request accordingly.

Docker Compose example

Auth Helper is not included in the standard Docker Compose setups in the AI DIAL repository. A typical deployment configuration:

auth-helper:
  image: epam/ai-dial-auth-helper:0.4.0
  platform: linux/amd64
  environment:
    SERVER_HOSTURL: "http://auth-helper:4088"
    OAUTH2_PROVIDERURI: "http://keycloak:8180/realms/dial"
    OAUTH2_CLIENTID: "dial-chat"
    OAUTH2_CLIENTSECRET: "${AUTH_KEYCLOAK_SECRET}"
  ports:
    - "4088:4088"
  depends_on:
    - keycloak

When Auth Helper is deployed, DIAL Chat points its auth configuration to the Auth Helper's well-known endpoint instead of directly to Keycloak:

chat:
  environment:
    AUTH_KEYCLOAK_HOST: "http://auth-helper:4088/"

Further reading

• realm-config.json — Keycloak realm configuration
• DIAL Chat configuration — auth provider environment variables
• Identity Providers — identity provider settings in settings.json