Entra ID: only a client secret is supported; add client certificate (private_key_jwt) #996

Closed
opened 2026-10-24 16:13:47 +00:00 by Cordy · 2 comments
Owner

Found in the #985 research (research-985-4 §5).

Microsoft limits client secrets to 24 months or less, recommends under 12 months, and says secrets should not be used in production; certificates (or federated credentials) are the recommended credential. On expiry every sign-in fails with AADSTS7000222. VERIFIED (Microsoft identity platform docs).

Cairn supports only a client secret (oidclib.go:33, 172). Add private_key_jwt client authentication (RFC 7523) with a certificate/key from a file (_FILE pattern), hot-reloaded like tls.certDir. Keycloak supports it too ("Signed JWT").

Also for the facts block: Cairn cannot read an Entra secret's expiry without Graph; the hint should say so.

Found in the #985 research (research-985-4 §5). Microsoft limits client secrets to 24 months or less, recommends under 12 months, and says secrets should **not be used in production**; certificates (or federated credentials) are the recommended credential. On expiry every sign-in fails with AADSTS7000222. VERIFIED (Microsoft identity platform docs). Cairn supports only a client secret (`oidclib.go:33, 172`). Add `private_key_jwt` client authentication (RFC 7523) with a certificate/key from a file (`_FILE` pattern), hot-reloaded like `tls.certDir`. Keycloak supports it too ("Signed JWT"). Also for the facts block: Cairn cannot read an Entra secret's expiry without Graph; the hint should say so.
Author
Owner

Research and decision (2026-10-28)

Research: research-identity-996-1001-1034.md (RFC 7523, rfc7523bis-11, FAPI 2.0, RFC 9700, Entra certificate-credentials docs + MSAL Go source, Keycloak Signed JWT source, Zitadel, Okta).

Decisions (Nikola): sign-in client only; the two Keycloak admin clients keep their secret (backlog). No Entra tenant yet: ship tested against Keycloak, Entra follows Microsoft's documented format; the live Entra test with setup steps goes to #1005.

Design:

  • auth.oidcClientCertDir / CAIRN_OIDC_CLIENT_CERT_DIR: tls.key (+ tls.crt, required for Entra), PEM only (no encrypted PEM, no PFX), re-read like tls.certDir (keep last good pair, refuse start on a broken/mismatched/expired pair). Secret and certificate both set: refuse start.
  • Assertion per token request: iss=sub=client id, single aud, fresh 128-bit jti, iat=nbf=now, exp now+60 s, typ JWT, x5t#S256 when a certificate is present, optional kid (auth.oidcClientKeyId, Zitadel).
  • alg auto: PS256 for Entra, RS256 for other RSA keys, ES256 for P-256; aud auto: token endpoint for Entra, issuer otherwise; both overridable. Sent with AuthStyleInParams (never Basic + assertion).
  • WARN if discovery doesn't list private_key_jwt; expiry WARN with the tlstrust thresholds; metric cairn_oidc_client_cert_expiry_days; never log key or assertion.
  • Facts block: method, certificate subject, SHA-256 thumbprint, valid until; the Entra secret hint says only Microsoft Graph (Application.Read.All) shows a secret's expiry and Cairn doesn't use Graph.
## Research and decision (2026-10-28) Research: research-identity-996-1001-1034.md (RFC 7523, rfc7523bis-11, FAPI 2.0, RFC 9700, Entra certificate-credentials docs + MSAL Go source, Keycloak Signed JWT source, Zitadel, Okta). Decisions (Nikola): **sign-in client only**; the two Keycloak admin clients keep their secret (backlog). No Entra tenant yet: ship tested against Keycloak, Entra follows Microsoft's documented format; the live Entra test with setup steps goes to #1005. Design: - `auth.oidcClientCertDir` / `CAIRN_OIDC_CLIENT_CERT_DIR`: `tls.key` (+ `tls.crt`, required for Entra), PEM only (no encrypted PEM, no PFX), re-read like `tls.certDir` (keep last good pair, refuse start on a broken/mismatched/expired pair). Secret and certificate both set: refuse start. - Assertion per token request: `iss`=`sub`=client id, single `aud`, fresh 128-bit `jti`, `iat`=`nbf`=now, `exp` now+60 s, `typ` JWT, `x5t#S256` when a certificate is present, optional `kid` (`auth.oidcClientKeyId`, Zitadel). - `alg` auto: PS256 for Entra, RS256 for other RSA keys, ES256 for P-256; `aud` auto: token endpoint for Entra, issuer otherwise; both overridable. Sent with AuthStyleInParams (never Basic + assertion). - WARN if discovery doesn't list `private_key_jwt`; expiry WARN with the tlstrust thresholds; metric `cairn_oidc_client_cert_expiry_days`; never log key or assertion. - Facts block: method, certificate subject, SHA-256 thumbprint, valid until; the Entra secret hint says only Microsoft Graph (Application.Read.All) shows a secret's expiry and Cairn doesn't use Graph.
Author
Owner

Shipped in v0.6.367 (PR #1037), both dogfoods bumped.

  • auth.oidcClientCertDir / CAIRN_OIDC_CLIENT_CERT_DIR (+ auth.oidcClientKeyId, auth.oidcClientAssertionAlg, auth.oidcClientAssertionAudience): private_key_jwt for the sign-in client, re-read every minute, last good pair kept, start refused on a bad pair or with a secret also set.
  • Entra recognised by the issuer's or token endpoint's host (incl. US gov, China, sts.windows.net, ciamlogin.com): PS256 + x5t#S256, aud = token endpoint, RSA ≥ 2048 and tls.crt required.
  • Expiry WARN, metric cairn_oidc_client_cert_expiry_days, AADSTS code in the failure reason, clock-skew note; facts block shows method, subject, SHA-256 thumbprint, valid until; the Entra secret hint explains Graph.
  • Docs: directory-entra-id.md "Client certificate instead of a secret" (incl. upload the renewed certificate before rotating), deployment.md (Keycloak Signed JWT, Zitadel, Kubernetes).

Tested against a fake IdP. Live checks moved to #1005: Keycloak on the dogfood (N) and the Entra test with setup steps (O). Keycloak admin clients: backlog.

Shipped in v0.6.367 (PR #1037), both dogfoods bumped. - `auth.oidcClientCertDir` / `CAIRN_OIDC_CLIENT_CERT_DIR` (+ `auth.oidcClientKeyId`, `auth.oidcClientAssertionAlg`, `auth.oidcClientAssertionAudience`): private_key_jwt for the sign-in client, re-read every minute, last good pair kept, start refused on a bad pair or with a secret also set. - Entra recognised by the issuer's or token endpoint's host (incl. US gov, China, sts.windows.net, ciamlogin.com): PS256 + `x5t#S256`, aud = token endpoint, RSA ≥ 2048 and `tls.crt` required. - Expiry WARN, metric `cairn_oidc_client_cert_expiry_days`, AADSTS code in the failure reason, clock-skew note; facts block shows method, subject, SHA-256 thumbprint, valid until; the Entra secret hint explains Graph. - Docs: directory-entra-id.md "Client certificate instead of a secret" (incl. upload the renewed certificate before rotating), deployment.md (Keycloak Signed JWT, Zitadel, Kubernetes). Tested against a fake IdP. Live checks moved to #1005: Keycloak on the dogfood (N) and the Entra test with setup steps (O). Keycloak admin clients: backlog.
Cordy closed this issue 2026-10-28 12:43:29 +00:00
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#996
No description provided.