Authentication deprecated

JWT-based authentication

JSON Web Tokens (JWTs) are used to authenticate requests between App Suite–based clients and newer services such as the AI Service.

Historically, App Suite Middleware only provides cookie-based sessions for browser clients. To enable service-to-service authentication, the acquireToken / redeemToken mechanism is used to bridge from an existing App Suite session to JWT-based authentication, issued by the Core UI service.

This approach allows new services to authenticate requests without depending on App Suite session state or cookies.

Authentication Flow (High-Level)

  1. A user authenticates with App Suite Middleware and has an active cookie-based session.
  2. The App Suite UI calls acquireToken to obtain a one-time token from App Suite Middleware.
  3. The one-time token is handed over to the Core UI service.
  4. The Core UI service calls redeemToken to establish a short-lived session with App Suite Middleware.
  5. This session is used to retrieve user data and evaluate capabilities and permissions.
  6. The Core UI service issues a signed JWT and returns it to the App Suite UI.
  7. Downstream services (e.g. the AI service) validate incoming requests by verifying the JWT signature using the JSON Web Key Set (JWKS).

Configuration Overview

To enable JWT-based authentication, configuration is required in the following components:

  • App Suite Middleware – Enables and restricts acquire/redeem token usage.
  • Core UI service – Identifies itself using the same application ID and exposes a JWKS endpoint.

App Suite Middleware Configuration

JWT issuance relies on the token login API, which must be enabled and configured.

Required settings

  • com.openexchange.tokenlogin Enables token-based login. Default: true
  • com.openexchange.tokenlogin.applications Defines the allowed application IDs that may request JWTs.

Example Configuration

core-mw:
  secretProperties:
    com.openexchange.tokenlogin.applications: "your-api-id"
    com.openexchange.tokenlogin.app-id.announceId: "false"

Notes: - your-api-id must be a stable and unique identifier. - The same application ID must be reused consistently across services.

Core UI Service Configuration

The Core UI service must be configured with the same application ID that is registered in App Suite Middleware.

Example Configuration

appsuite:
  apiSecret: "app-id"

JSON Web Key Set (JWKS)

To allow downstream services to validate JWT signatures, the Core UI service exposes a JSON Web Key Set (JWKS) endpoint. The JWKS publishes the public keys corresponding to the private keys used by the Core UI service to sign JWTs.

Required Certificates

The JWKS is backed by certificates provided via a Kubernetes secret. The secret must contain the following keys:

  • ca.crt: CA certificate (PEM format)
  • tls.crt: X.509 certificate (PEM format)
  • tls.key: Private key (PEM format)

Configuration

The name of the secret must be provided via: yaml overrides: jwksSecret: '<secret-name>'

JWT Signing Algorithm

By default, JWTs are signed using RS256.

To use a different algorithm, configure: yaml jwt: algorithm: '<algorithm>'

The value must be compatible with the algorithms supported by the jose library.

Operational Notes

  • Ensure that all services relying on JWT authentication can reach the JWKS endpoint.
  • Certificate rotation requires updating the JWKS secret and redeploying the service exposing it.
  • Mismatched application IDs are a common source of authentication failures.