Identity and authentication

This page covers how CDC authenticates callers, how it models authorisation, and how it fits into an organisation’s existing identity governance. It is written for an evaluator assessing the identity architecture; the broader stance is in the security posture, and secret handling is in the secrets posture.

Standards-based, one identity model for every caller

CDC authenticates over OpenID Connect / OAuth 2.0. Interactive single-page-app users, machine (client-credentials) clients, and webhook callers all present a bearer token that the hosts validate as plain resource servers: they check the token’s issuer against the identity provider’s published configuration and require a dedicated API audience. Interactive login uses Authorization Code with PKCE against a vendor-neutral OIDC client.

A caller that cannot do an OAuth exchange, such as Power BI, Excel or an older integration, can send an API key of a machine client instead (see below). The hosts have one default authentication scheme that selects per request: a key goes to the key handler, everything else to token validation. The key handler turns the key into a real token of its machine client and validates it the same way, so both paths produce the same identity, and nothing after authentication can tell a key caller from a token caller.

One consequence worth noting in an evaluation: because the identity provider is on the validation path, it is an availability dependency for the management API, consistent with the platform’s deliberate fail-closed stance. CDC would rather refuse access than serve it without a validated identity.

Authorisation: a flat, group-granted scope model

Authorisation uses a flat {area}:{read|write} scope vocabulary: one read and one write scope per functional area (processes, models, plugins, instances, governance, identity, and so on) plus a few fixed-purpose scopes. Endpoints declare their area once; read verbs require the area’s read scope and mutating verbs require its write scope.

Two design choices matter for an evaluator:

• Users hold scopes only through groups. There are no direct user-to-scope grants. Access is designed at the group level and users inherit it through membership, so “who can do what” is reasoned about through a small number of groups rather than a per-user permission sprawl. Machine clients receive scopes through their service accounts.
• The core vocabulary is closed and assign-only. The built-in {area}:{action} scopes cannot be minted from the UI: they are a fixed, tamper- proof catalogue that can only be granted, never invented. Author-defined scopes that protect a customer’s own published APIs are a separate, self-service category (api:{name}:invoke by convention), so exposing an API is self-service while the platform’s own authorisation vocabulary stays fixed.

A caller with a valid token but missing the required scope is refused with a distinct authorisation error; a caller with no token hits the default-deny fallback. The distinction lets an operator tell “authenticated but not permitted” apart from “not authenticated.”

The single-page app additionally hides surfaces the signed-in user lacks the scope for, but this is UX only. The backend enforces every scope regardless, so a hand-crafted request to a hidden surface is still refused. Nothing about the security of the platform depends on the UI.

The public integration surface: auth as data

The public API surface (customer-authored API operations and webhook endpoints) is governed by per-route data, not a single static policy. Each entry point carries its own authentication configuration:

• Authenticated (the default). An authenticated caller is required, with a bearer token or an API key, and the caller’s scopes must include every scope the route lists. A newly created API or webhook starts in this state, and an entry point that stored no authentication configuration is treated the same way.
• Open. Anyone able to reach the URL can trigger the flow. This is a legal but explicit author choice that raises a loud warning: it is never a default and never the result of an omission.

A route whose configuration names an authentication type the platform does not know is refused, never opened. A future strategy can therefore never open an endpoint by accident.

Whichever applies, the authenticated caller flows into the instance’s captured principal, so a process triggered through the public surface still records exactly who (or which machine client) invoked it.

Fitting into existing identity governance

CDC does not require an organisation to run a parallel identity silo.

• Broker to a corporate directory. CDC can broker sign-in to Microsoft Entra ID (and comparable OIDC providers): the user signs in against the corporate directory and returns with a normal CDC token: same audience, same scope claim, same audit capture as a local login. The corporate directory remains the authority for who exists and what they belong to.
• Directory groups drive CDC access. Group membership in the corporate directory can be mapped to CDC groups, re-evaluated on every sign-in, so that joining or leaving a directory group grants or revokes CDC access at the next login with no administrator touching CDC. A first-time brokered user can be given a sensible default group, or land with zero access under strict deny-by-default: the customer’s choice.
• Governed self-administration. For customers who want CDC to manage identities directly, it offers an Access area that administers users, groups, clients, and scopes against the identity provider write-through, with the provider remaining the single source of truth (CDC keeps no mirror of identities, only an append-only audit log of who changed what). Safety guards prevent self-inflicted lockout: a mutation that would remove the last administrator, or strip the caller’s own admin access, is refused server-side, and the platform’s own service clients are protected from modification.

Machine access and least privilege

Machine callers are real OAuth confidential clients with service accounts and granted scopes. Client secrets are revealed or regenerated on demand under the write scope and are never persisted in configuration. The platform’s own internal service accounts are held to least privilege: the account used for a read-only identity-provider check holds only read roles and has no write path, kept strictly separate from the higher-privilege account used for write-through administration, whose secret is resolved live from the secret store at call time so that rotation is immediate.

API keys: a credential of a machine client, not an identity

Some callers cannot run a client-credentials exchange. For them an administrator issues an API key for an existing machine client. The key is a credential of that client, not a second identity: a request that carries it authenticates as the client, with the same scopes, groups and location that a token for the client gives. The identity provider stays the only source of identities, scopes and groups; the key registry holds none of them.

• Format and storage. A key is cdc_ followed by 32 random bytes, so a secret scanner can find a leaked key. CDC stores only a SHA-256 hash of it. The value is shown once, at issue, and is never stored or logged, so a leaked registry table gives no access.
• Three credential forms. A caller sends the key as the password of a Basic credential (the username is ignored and never captured), as a bearer value with the cdc_ prefix, or in an X-API-Key header. A key in the query string is never accepted, so keys do not end up in access logs.
• Resolution. The control plane looks the key up by its hash, checks that it is neither revoked nor expired, and obtains a real access token for the machine client from the identity provider. The token is cached until shortly before it expires. Disabling or deleting a client in CDC drops its cached token and tells every execution node to drop its keys, so they stop at once. A client disabled directly in the identity provider stops its keys only when the cached token expires, which is five minutes with the identity provider’s default.
• Execution nodes fail closed. An execution node asks the control plane over the message bus and caches the answer: a resolved key until its token or the key expires, an unknown key for 60 seconds, so a flood of bad keys does not reach the control plane. If the control plane does not answer within 5 seconds, the request is refused with 401. An outage never opens access.
• Revocation within seconds. A revoke is final. The control plane broadcasts it, and every execution node drops the key from its cache, including an answer it is still waiting for when the broadcast arrives. If the broadcast is lost, the key stops working at the latest when its cached token expires, which is five minutes with the identity provider’s default.
• Governed and audited. Issue and revoke need the identity write scope, and listing keys needs the read scope. A platform-owned client can hold no key. Deleting a client revokes all its keys and keeps their records. Every issue and revoke is in the identity audit log, without the key value, and every process run started with a key records the key’s id on its captured principal, so an auditor can see which key started it.
• Per environment. An access export carries no keys, and an import creates none. Each environment issues its own.

What to take into an evaluation

• Standards-based OIDC/OAuth; one validation model for users, machines, and webhooks; a dedicated audience required.
• Authorisation is a flat, closed, group-granted scope vocabulary: access is designed through groups, and the core vocabulary cannot be tampered with.
• The public surface is secure-by-default; “open” is always an explicit, warned choice.
• Sign-in can be brokered to a corporate directory with directory-group-driven access, so identity governance stays where it already lives.
• Machine clients are first-class OAuth clients under least privilege; every administrative change is audited.
• Callers that cannot do OAuth use an API key that authenticates as a named machine client: hashed at rest, shown once, revocable within seconds, and refused when the control plane cannot vouch for it.