Skip to content

On-Premise Authentication to Forge Applications

  • Status: Accepted
  • Deciders: brishe, emmjoh, shasca
  • Date: 2026-02-27

Context and Problem Statement

Legacy on-premise applications need a secure, maintainable method to authenticate against Forge-hosted Experience APIs. These applications authenticate their human users via on-premises Active Directory, which is federated with the Entra ID tenant that all Forge applications use. However, the on-premise codebases have deep ties to Active Directory and cannot be easily refactored to participate in Entra ID or Okta OAuth flows (e.g., PKCE or authorization code). We need a machine-to-machine authentication strategy that works within these constraints, is consistent with platform security standards, and minimizes operational burden on development teams.

Considered Options

  • API Key for Experience API — auto-generate a per-application API key, store it in Environment API/Crypto and KeyVault; on-premise systems retrieve it via Environment API/Crypto
  • Create an Entra ID application registration for the on-premise app and use client credentials to authenticate to Forge
  • No access — migrate the on-premise application to Forge before granting API access

Decision Outcome

Chosen option: "API Key for Experience API", because it provides a lightweight, low-friction path for legacy applications that cannot be immediately migrated, while keeping secret management centralized and auditable through the platform's existing Environment API/Crypto and Azure KeyVault infrastructure.

The API key is auto-generated by the platform, pushed to Environment API/Crypto and KeyVault. On-premise systems retrieve the key at runtime via Environment API/Crypto — an integration point they already have — rather than needing direct KeyVault access. This avoids manual secret distribution and ensures rotation can be automated in future.

Consequences

  • Good, because legacy applications can authenticate without requiring a full migration to Forge.
  • Good, because secret lifecycle (generation, storage, rotation) is handled by platform tooling rather than manually by teams.
  • Good, because on-premise systems already integrate with Environment API/Crypto, so no new retrieval mechanism is required.
  • Good, because KeyVault access is already governed by existing RBAC policies, so no new security surface is introduced.
  • Bad, because API keys are less expressive than OAuth tokens (no claims, no scopes) and require additional middleware to enforce fine-grained authorization.
  • Bad, because on-premise applications depend on Environment API/Crypto being available at runtime to retrieve the key; an outage in that service would prevent authentication.
  • Bad, because on-premise user identity is not propagated to Forge APIs — audit trails reflect the application key rather than an individual user, since the application authenticates as itself rather than on behalf of a federated AD principal.