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: "core-ui"
    com.openexchange.tokenlogin.app-id.announceId: "false"

Notes: - applications is a comma-separated list of application Ids. Simply set or add core-ui here. - 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. The default core-ui is already set.

Example Configuration

core-ui:
  appsuite:
    appId: "core-ui"

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 keys

JWT signing requires an asymmetric key pair:

  • Private key: used by the JWT issuer to sign tokens
  • Public key: exposed via JWKS for token verification

These keys must be provided via a Kubernetes Secret with the following entries:

  • tls.key: private key (PEM format)
  • tls.crt: X.509 certificate containing the public key (PEM format)

The keys are intentionally named tls.* to simplify integration with automation tools such as cert-manager. They are not used as TLS certificates. Only the public key contained in the certificate is used.

The keys are not validated via PKI, and a CA certificate is not required. Trust is established by distributing the public key via the JWKS endpoint. Regular key rotation is strongly recommended.

We recommend using RSA keys with the RS256 algorithm.

Getting keys

For production environments, we strongly recommend using automated solutions such as cert-manager.

For local deployments or testing purposes, a suitable key pair can be generated using OpenSSL:

# generate the private key
openssl genpkey -algorithm RSA -out tls.key -pkeyopt rsa_keygen_bits:2048
# generate a self-signed certificate containing the public key
openssl req -new -x509 -key tls.key -out tls.crt -days 365 -subj "/CN=core-ui"

Once you have a key pair, it must be made available to the application as a Kubernetes Secret. The Helm chart can create this Secret automatically when the key material is provided via values.

core-ui:
  jwks:
    enabled: true
    existingSecret: ""
    publicKey: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    privateKey: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----

When rotating keys, previously published public keys remain available via JWKS until all issued tokens have expired.

Configuration

The name of the secret must be provided via if it differs from the default core-ui-jwks-secret:

core-ui:
  jwks:
    existingSecret: '<secret-name>'

JWT Signing Algorithm

By default, JWTs are signed using RS256. To use a different algorithm, configure:

core-ui:
  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.

Migration Guide for 8.46

With App Suite 8.46, JWT creation has been moved from Switchboard to the Core UI service. As a result, several authentication-related configuration options must be relocated and renamed.

This migration is only relevant for deployments that include AI Service, Switchboard, or the Voice & Video service.

Important: Support for shared secrets used for JWTs has been discontinued with 8.46. Ensure your deployment no longer relies on shared-secret–based token handling.

JWKS / OIDC Configuration

For services such as AI, Switchboard, or Voice & Video, the following configuration must be updated.

The existing jwks section:

core-ui:
  jwks:
    domain: your-deployment.com

must be renamed and replaced with the following oidc configuration:

core-ui:
  oidc:
    issuer: https://your-deployment.com/ui

JWT Configuration Relocation

The following configuration block has been moved from Switchboard to the Core UI service:

core-ui:
  jwks:
    enabled: true
    # the values above are defaults
    # issuer must be explicitly configured (hostname or full url)
    issuer: 'https://your-deployment.com/ui'

  jwt:
    algorithm: 'RS256'
    capabilities: 'ai,calendar,contacts,infostore,jitsi,openai,switchboard,webmail,zoom'
    expiration: '1h'

  appsuite:
    # required for the acquire/redeem token handshake with App Suite Middleware
    # api must point to the App Suite Middleware API
    api: 'https://your-deployment.com/appsuite/api'
    appId: 'core-ui'

Ensure this configuration is removed from Switchboard and added to the Core UI service.

App Suite Middleware Adjustment

In App Suite Middleware, token login must be explicitly enabled for the Core UI service.

Add or update the following configuration:

core-mw:
  secretProperties:
    com.openexchange.tokenlogin.applications: "core-ui"