Skip to main content
Version: 0.6

Konstruct 0.6.10

Released: August 2026

Highlights​

  • Exchange a Microsoft Entra token for a Konstruct session token — a new endpoint trades an Entra access token for an ordinary Konstruct token with roles and organizations already resolved, so an external portal can hand its users straight into Konstruct
  • Helm and YAML catalog sources can track a Git tag — completes the tag support added in 0.6.9, which covered IaC sources only
  • Fixed: a project's custom Terraform module URL is honored — remote_workload_url is no longer discarded, and environment files are now detokenized alongside cluster files
Breaking configuration change

ENTRA_REQUIRED_SCOPE has been removed, and ENTRA_AUDIENCE now takes a comma-separated list. See Upgrade notes before upgrading if you use Entra authentication.

Exchange a Microsoft Entra token for a Konstruct session token​

0.6.2 let an external service call the Konstruct API with a Microsoft Entra access token directly. That works, but every request pays for it: Entra verification and a group lookup on each call, and no way to hand a browser a real Konstruct session.

0.6.10 adds a token exchange. Present an Entra token once, get a Konstruct session token back:

POST /api/v1/auth/entra/exchange
Authorization: Bearer <entra-access-token>

Konstruct verifies the Entra token, resolves the caller's groups to Konstruct roles and organizations, and returns a session token with that mapping already baked in:

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3212,
  "expires_at": "2026-08-04T23:14:07Z",
  "sub": "…",
  "email": "user@example.com",
  "roles": ["developer"],
  "organizations": ["platform"],
  "org_roles": { "platform": "developer" }
}

Callers present that token on later requests like any other session token — it takes the ordinary authentication path, with no Entra verification and no group lookup per request.

The session cookie is set too. The response carries the same session cookie, domain, and flags that the login and SSO-callback paths set. A browser that performs the exchange can navigate straight to Konstruct already signed in. A server-side caller can ignore the cookie and read the token from the response body.

Expiry​

The issued token expires at exactly the same instant as the Entra token that authorized it. It can never extend access beyond the credential it was derived from — when the Entra token expires, so does the Konstruct session.

Responses​

StatusMeaning
200Token exchanged; body carries the session token and the resolved roles
401The Entra token is missing, malformed, not for the configured tenant, or has no exp claim
501Entra authentication is not configured on this server

The endpoint is unauthenticated in Konstruct terms — the caller has no Konstruct token yet — and authenticates entirely with the Entra token on the Authorization header.

Helm and YAML catalog sources can track a Git tag​

0.6.9 let an IaC catalog item reference a Git tag such as v0.1 as its module source. Helm and YAML catalog items still resolved their chart repository reference as a branch only, so a tag failed to clone.

Both now resolve either. Konstruct tries the reference as a branch first, then as a tag, so a release-style ref like v0.1 works the same way across every catalog source type. Leaving the reference empty still clones the repository's default branch.

Fixed: a project's custom Terraform module URL is honored​

A project can override the Terraform module used to build its workload cluster by setting remote_workload_url on the Project spec. That override was being discarded during templating, so the project fell back to the default module regardless of what you set.

Two related problems are fixed:

  • The override now wins. remote_workload_url is applied to the generated manifests as configured.
  • Environment files are detokenized too. Cluster files and environment registry files now go through the same single templating pass, so a token substituted in one is substituted in the other. Previously the two paths could disagree, leaving raw <WORKLOAD_…> placeholders in environment files.

Custom template fields on the project continue to apply on top, unchanged.

Upgrade notes​

Entra configuration has changed​

If you have Microsoft Entra authentication enabled, update konstruct-api's environment before upgrading:

VariableChange
ENTRA_AUDIENCENow a comma-separated allow-list of accepted aud values, so the exchange can accept sessions from several client apps. A single value keeps working unchanged.
ENTRA_REQUIRED_SCOPERemoved. The scope check no longer runs. If you set this variable, delete it.

ENTRA_AUDIENCE remains required to enable the feature. An empty value disables Entra authentication entirely — it never means "accept any audience". Accepting any audience would leave the tenant (tid) as the only boundary, so a token a user granted to an unrelated app in the same tenant would authenticate here too.

ENTRA_TENANT_ID and ENTRA_ISSUER are unchanged.

Upgrade the chart​

Update the targetRevision in your platform team's Konstruct Argo CD Application manifest to 0.6.10:

spec:
  source:
    chart: konstruct
    repoURL: oci://europe-west2-docker.pkg.dev/civo-com/charts
    targetRevision: 0.6.10

Commit and push — Argo CD syncs the new version automatically. No manual migration steps are required.

What's next?​