Skip to content

FAPI 2.0 & mutual TLS

Conformance

Conformance self-run: FAPI 2.0 conformance-suite run. Upgrading an existing installation: see the breaking changes.

A realm has a security profile: Standard (the default) or FAPI 2.0. With FAPI 2.0, every client of the realm follows the FAPI 2.0 Security Profile (Final) at the same time. The rules are checked whenever a client is used, whatever the client stored: a client that does not meet them stops working, and nothing falls back to a weaker setting.

FAPI 2.0 mode is not a certification. HelixIAM has not been certified by the OpenID Foundation for FAPI 2.0; the OpenID Foundation's FAPI 2.0 test plans pass in a self-run.

Turning it on

  • Console: Realm settings → Security. Choose FAPI 2.0 and save. The page lists the clients of the realm that would stop working, with the reason, and asks for confirmation if there are any.
  • Admin API: PUT /admin/realms/{realm}/settings/security-profile with {"securityProfile": "FAPI2"} (or "STANDARD"). Needs realm-admin. GET on the same path returns the profile and the clients that would stop working (nonCompliantClients, each with reasons: publicClient, clientSecret, noKeys, implicit).
  • Realm export/import: the export's keyCustody.securityProfile carries the profile (and keyCustody.requireSignedRequestObject, below); an import applies it before the clients, so they are checked against it.
  • Signed requests (FAPI 2.0 Message Signing): in a FAPI 2.0 realm, Require signed request objects (console) or "requireSignedRequestObject": true in the same PUT makes every client of the realm send its authorization requests as signed request objects at PAR (see Message Signing). A single client can require it too (client setting Require signed request objects). In a Standard realm the switch is refused (fieldErrorCodes.requireSignedRequestObject: onlyFapi2); switching the realm back to Standard turns it off.

A refused write answers 400 with fieldErrors.securityProfile and a code in fieldErrorCodes: required, unknown, or masterRealm. The master realm cannot use FAPI 2.0: the admin console signs in to it as a public client.

The setting is stored with the realm's key-custody settings (realm_custody_settings.security_profile, migration V197) and every replica picks up a change at commit.

What a FAPI 2.0 realm enforces

Rule Behaviour Spec
Confidential clients, private_key_jwt or mutual TLS private_key_jwt, tls_client_auth or self_signed_tls_client_auth (RFC 8705 §2). Saving a public client or one with a client secret is refused (400, fieldErrorCodes.publicClient: fapi2PublicClient or fieldErrorCodes.tokenEndpointAuthMethod: fapi2AuthMethod; also in Dynamic Client Registration and the realm import). A client stored before the switch cannot authenticate (invalid_client). §5.3.2.1
Client assertion aud The issuer identifier only, as a single string. A token, PAR or other endpoint URL, or an array, is refused. §5.3.2.1-8
Pushed authorization requests (PAR) A plain /oauth2/authorize request is refused with invalid_request (redirected to a registered redirect URI only). A pushed request needs redirect_uri. The request_uri lives 300 s (expires_in); after that it is removed and answered invalid_request_uri at the pushed request's redirect URI. §5.3.2.2, RFC 9126
PKCE S256 required, for confidential clients too. A missing or wrong code_verifier is refused. §5.3.2.2
Response type code only. The implicit and hybrid flows are refused, at use and when a client is saved (implicitFapi2). §5.3.2.2
Authorization code Lives at most 60 s, single use, bound to its client. §5.3.2.1
Sender-constrained tokens Every access token is sender-constrained, by DPoP or by mutual TLS, chosen per client. DPoP (default): bound to the client's DPoP key (cnf.jkt, token_type: DPoP); a token request without a proof is refused with invalid_dpop_proof; userinfo takes the token with its proof (Authorization: DPoP) and refuses it as Bearer. Mutual TLS (client setting certificate-bound access tokens): bound to the client certificate (cnf.x5t#S256); a token request without a certificate is refused with invalid_request; userinfo takes the token only with that same certificate. Never an unbound Bearer token. §5.3.2.1, §5.3.3, RFC 9449, RFC 8705 §3
Other token endpoints The agent delegation endpoint (/agent/delegation/token) issues a FAPI 2.0 client sender-constrained tokens only: without a DPoP proof (or the certificate of a certificate-bound client) it is refused with invalid_dpop_proof (invalid_request for the certificate). Workload identity federation (/workload-identity/token, the workload authenticates with its issuer-signed JWT) issues sender-constrained tokens only, by DPoP or mutual TLS per workload credential (Token binding, senderConstraint dpop or mtls): with a DPoP proof (PS256 or ES256, checked like the token endpoint's) the token is bound to its key (cnf.jkt, token_type: DPoP); a mutual-TLS credential's token is bound to the request's client certificate (cnf.x5t#S256). Without a proof it is refused with invalid_dpop_proof (invalid_request without the certificate of a mutual-TLS credential), never answered with a Bearer token; a credential stored before the realm switched needs a DPoP proof. Saving a credential with none is refused (admin API field error senderConstraint, code fapi2SenderConstraint; console; realm import). §5.3.2.1-6, §5.3.3, RFC 9449, RFC 8705 §3
dpop_jkt A DPoP proof sent with the pushed request binds the code to its key; a dpop_jkt that names another key is refused at PAR; the code is redeemed only with a proof of that key. RFC 9449 §10
Refresh tokens Not rotated (the same refresh token keeps working). With mutual TLS the refresh needs the client certificate of the access token (another certificate: invalid_grant). With DPoP the refresh needs a DPoP proof, and the new access token is bound to that proof's key: the refresh token of a confidential client is not bound to a DPoP key, since the client authenticates (RFC 9449 §5). §5.3.2.1, RFC 9449 §5
Algorithms The realm signs ID tokens, access tokens and other JWTs with PS256, ES256 or EdDSA: RS256 is signed as PS256 with the same RSA key, and there is no RS256 fallback. Client assertions and request objects are accepted with PS256, ES256 or EdDSA (RSA keys of 2048 bits or more); DPoP proofs with PS256 or ES256 at every endpoint that takes one (PAR, token, userinfo, workload identity, agent delegation), as dpop_signing_alg_values_supported advertises: §5.4.1 permits EdDSA but does not require an authorization server to accept it, and the authorization server library's DPoP proof verification covers RSA and EC keys only. none is never accepted. §5.4.1
Clock skew A JWT whose iat or nbf is up to 10 s in the future is accepted; more than 60 s is refused (client assertions, DPoP proofs, request objects). §5.3.2.1
Redirects Redirects to the client's redirect URIs (responses and errors) are 303 See Other, never 307. §5.3.2.2
Discovery Advertises exactly the above: require_pushed_authorization_requests: true, private_key_jwt, and when a client certificate can reach the server (a forwarded-certificate header or the server's own TLS client authentication) self_signed_tls_client_auth (plus tls_client_auth when trust anchors are configured) and tls_client_certificate_bound_access_tokens: true, PS256/ES256/EdDSA (also for request_object_signing_alg_values_supported and authorization_signing_alg_values_supported), dpop_signing_alg_values_supported PS256/ES256, code_challenge_methods_supported S256, response_types_supported code, and require_signed_request_object: true when the realm requires signed requests. RFC 8414, RFC 9126 §5, RFC 8705 §3.3, RFC 9101 §10.5

Message Signing (JAR and JARM)

FAPI 2.0 Message Signing (§5.3.1, §5.4.1) adds signed authorization requests and signed authorization responses. Both work in every realm; in a FAPI 2.0 realm the rules below are strict.

Signed request objects at PAR (JAR, RFC 9101 with RFC 9126 §3). The client sends client_id, its client authentication and request (the signed request object) to the PAR endpoint. The pushed request is then exactly the request object's parameters plus the client authentication: redirect_uri, state, nonce, scope, response_mode and every other parameter come from inside the object, and other form parameters are ignored. The client_id and iss inside must be the client's, and a request object that carries request_uri or request is refused. In a FAPI 2.0 realm the request object must:

  • be signed with PS256, ES256 or EdDSA (RS256 and none are refused) by a key of the client;
  • have aud equal to, or containing, the issuer;
  • have exp and nbf, with nbf at most 60 minutes in the past and exp at most 60 minutes after nbf; an nbf or iat up to 10 s in the future is accepted (clock skew), an expired object is refused;
  • have typ oauth-authz-req+jwt or JWT (or none).

A request object that fails a check is answered 400 invalid_request_object. When the client or its realm requires signed request objects, a pushed request without one is 400 invalid_request. The state and nonce of the response and the ID token are the ones inside the object; a state sent next to the request_uri at the authorization endpoint is ignored.

Signed authorization responses (JARM). A client asks for one with response_mode jwt, query.jwt, fragment.jwt or form_post.jwt (in its request object, its pushed request or a plain request), or registers a JARM response mode (client setting JARM response mode), in which case it always gets JARM. The response, success or error (also a cancelled sign-in, an expired request_uri or a refused plain request), is one JWT in the response parameter, with iss (the issuer), aud (the client), exp (2 minutes), iat and the response parameters (code, state or error, error_description). It is signed with the realm's ID-token key, with the client's authorization_signed_response_alg when it registered one (client setting Response signing algorithm; PS256, ES256 or EdDSA, and RS256 outside a FAPI 2.0 realm), else the realm's default (PS256, ES256 or EdDSA in a FAPI 2.0 realm). The registered algorithm must be one the realm has an active key for (in key custody: an active ID-token key that signs it); the admin API, Dynamic Client Registration and the realm import refuse it otherwise (admin API: 400, fieldErrorCodes.authorizationSignedResponseAlg = noActiveKey; registration: invalid_client_metadata). A response that cannot be signed as asked (the key was deactivated later) is a server error, never an unsigned response or one signed with another algorithm. Discovery lists the four JARM modes in response_modes_supported and the algorithms in authorization_signing_alg_values_supported. Encrypted responses (authorization_encrypted_response_alg) are not supported.

In every realm

Some of the work behind FAPI 2.0 applies to all realms because the specs require it:

  • Every authorization response carries iss (RFC 9207), in the query, the fragment or the form_post form; a JARM response carries it inside its JWT. Both discovery documents say authorization_response_iss_parameter_supported: true.
  • Client assertions and request objects are accepted with RS256, PS256, ES256 or EdDSA (before: RS256 only). Outside a FAPI 2.0 realm the token endpoint URL stays an accepted assertion audience (OpenID Connect Core §9).
  • An access token requested with a DPoP proof is bound to its key and typed DPoP, and userinfo accepts DPoP.
  • A request_uri inside a pushed authorization request is refused (RFC 9126 §2.1), and an expired request_uri is answered invalid_request_uri (RFC 9126 §2.2).
  • A request to the token, PAR, revocation or introspection endpoint without any client authentication (no assertion, a missing or unknown client_assertion_type) is 401 with the JSON error invalid_client (RFC 6749 §5.2), never a redirect to the sign-in page or an empty body.
  • The sign-in page has a Cancel while an authorization request is pending: the client gets error=access_denied with its state at its redirect URI (OpenID Connect Core §3.1.2.6). A pushed request is then used up.
  • A DPoP proof's htu is compared without query and fragment, after the RFC 3986 normalization (case of scheme and host, default port, dot segments, percent-encoding), at userinfo and wherever else a proof is checked (RFC 9449 §4.3).
  • A signed request object at the PAR endpoint and JARM by response_mode: see Message Signing.
  • A client with certificate-bound access tokens (RFC 8705) gets a token only with its certificate; without one the request is refused (invalid_request). Before, an unbound token was issued.
  • A certificate-bound token is accepted at userinfo and at the admin API only with the certificate it is bound to; a DPoP-bound token is never accepted as a Bearer token. Access tokens are never taken from the query string.
  • tls_client_auth and self_signed_tls_client_auth are available to every client (see below).

Mutual-TLS client authentication (RFC 8705 §2)

A client's token endpoint auth method can be:

  • tls_client_auth: a certificate issued by a CA among the realm's trust anchors (below), not revoked, with the subject the client registered: exactly one of the subject DN (subject_dn, compared as an X.500 name) or one subject alternative name, san_dns, san_uri, san_ip or san_email. Admin API and console: tlsClientAuthAttribute and tlsClientAuthValue; Dynamic Client Registration: tls_client_auth_subject_dn, tls_client_auth_san_dns, tls_client_auth_san_uri, tls_client_auth_san_ip or tls_client_auth_san_email (migration V198). The chain is checked with PKIX, validity dates included, and then for revocation (see "Revocation of client certificates"). Without usable trust anchors for the realm the method is not advertised in that realm's discovery and refuses every certificate.
  • self_signed_tls_client_auth: the certificate is the first x5c certificate of a key in the client's JWK Set by value (jwks), and within its validity dates. A JWKS URL is not used for this method. There is no CA, so there is nothing to ask about revocation: the client (or an administrator) revokes such a certificate by removing it from the client's JWK Set, which takes effect at the next request.

The client sends client_id and presents its certificate; nothing else. Certificate-bound access tokens are a separate client setting (x509CertificateBoundAccessTokens, RFC 8705 tls_client_certificate_bound_access_tokens), so an mTLS client can still use DPoP as its sender constraint. A wrong, untrusted or missing certificate is invalid_client.

TLS and mutual TLS (FAPI 2.0)

HelixIAM serves plain HTTP behind a TLS-terminating proxy or ingress. The transport rules of FAPI 2.0 (§5.2.2) are therefore set at that proxy, and HelixIAM relies on it for the parts below.

TLS policy. The proxy must offer TLS 1.2 and TLS 1.3 only (no TLS 1.0 or 1.1), and for TLS 1.2 only the cipher suites BCP 195 recommends (RFC 9325 §4.2):

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

No DHE, CBC or static-RSA suites. TLS 1.3 with its standard suites (AES-GCM, CHACHA20-POLY1305) is fine, and a client that offers TLS 1.3 must get it (OpenSSL-based proxies do this by default). Every response carries Strict-Transport-Security: max-age=31536000; includeSubDomains. HelixIAM also sends that header on requests that arrived over HTTPS; a proxy that adds its own should drop the upstream copy so there is only one.

Client certificates. For tls_client_auth, self_signed_tls_client_auth and certificate-bound access tokens (RFC 8705), the proxy asks for a client certificate but does not require it and does not verify it: HelixIAM does. The proxy forwards the certificate as URL-encoded PEM in the header helix.fapi.client-cert-header (HELIX_FAPI_CLIENT_CERT_HEADER; empty by default, which reads no forwarded certificate at all; for example X-Client-Cert), and it must overwrite that header on every request, so a client can never send its own copy. A certificate is public: a header a client could set proves nothing.

HelixIAM honours the header only when the TCP peer is listed in helix.fapi.client-cert-trusted-proxies (HELIX_FAPI_CLIENT_CERT_TRUSTED_PROXIES): the proxies that request and forward client certificates. This list is separate from helix.security.trusted-proxies (HELIX_TRUSTED_PROXIES, for X-Forwarded-*) on purpose: a hop that is trusted for the forwarded host and scheme but does not terminate client TLS, such as the admin console's nginx, must never be able to present a certificate. Do not list such hops. From any other peer, or with the list empty, the header is ignored and an mTLS client fails closed: it cannot authenticate with its certificate, and no certificate-bound token is issued or accepted for it. Without the header and that list (and without server.ssl.client-auth want or need on the server itself) no certificate can reach HelixIAM, so discovery advertises no mutual-TLS method and no tls_client_certificate_bound_access_tokens, in every realm (RFC 8414 §2: only what the endpoint supports).

HelixIAM checks the certificate as follows:

  • tls_client_auth: the certificate must chain to one of the realm's trust anchors (below), be meant for TLS client authentication (a key usage, when present, includes digitalSignature; an extended key usage, when present, includes clientAuth or anyExtendedKeyUsage, so a TLS server certificate of the same CA is refused), match the subject the client registered, and not be revoked. The proxy forwards the leaf certificate only, so the trust anchor is the CA that issued the client certificates (an intermediate, if that is what issues them).
  • self_signed_tls_client_auth: the certificate must be the x5c certificate of a key in the client's JWK Set by value (exact match).
  • Certificate-bound tokens: the SHA-256 thumbprint of the certificate is put in the token (cnf.x5t#S256), and the same certificate must be presented with the token.

nginx example. TLS 1.2/1.3 with the BCP 195 suites, HSTS, an optional unverified client certificate, and the certificate forwarded in X-Client-Cert:

server {
  listen 443 ssl;
  server_name idp.example.com;
  ssl_certificate     /etc/nginx/tls/fullchain.pem;
  ssl_certificate_key /etc/nginx/tls/privkey.pem;

  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
  ssl_prefer_server_ciphers off;
  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

  # Ask for a client certificate; HelixIAM verifies it.
  ssl_verify_client optional_no_ca;

  location / {
    proxy_pass http://helixiam:8080;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-Port 443;
    # Replaces any X-Client-Cert the client sent; without a client certificate the header is not sent at all.
    proxy_set_header X-Client-Cert $ssl_client_escaped_cert;
    proxy_hide_header Strict-Transport-Security;
  }
}

proxy_set_header with a header name replaces the incoming header of that name, and nginx does not pass a header whose value is empty, so a client-sent X-Client-Cert never reaches HelixIAM. Keep all proxy_set_header lines in the same block: a block that sets any of its own does not inherit those of the enclosing block. Then list the proxy's address in HELIX_TRUSTED_PROXIES and in HELIX_FAPI_CLIENT_CERT_TRUSTED_PROXIES.

Every other proxy that can reach HelixIAM must remove a client-sent copy of the header too. The admin console's nginx (the helix-dashboard image) clears the well-known client-certificate headers and HELIX_FAPI_CLIENT_CERT_HEADER in every location it proxies; the Helm chart passes it that name.

For Kubernetes with ingress-nginx, the Helm chart sets the mTLS annotations (ingress.mtls.enabled, forwarded header ssl-client-cert), and the TLS policy goes in the controller's ConfigMap: see the chart README (helm show readme), "TLS policy and mutual TLS (FAPI 2.0)".

Trust anchors per realm

Each realm has its own trust anchors for tls_client_auth: the CA certificates its clients' certificates must chain to. A realm's anchors are used for that realm's clients only; a certificate from one realm's CA never authenticates a client of another realm, whatever subject it carries. Console: Realm settings → Security → Mutual TLS. Admin API (reads need manage-realm, every write realm-admin, audited as MTLS_SETTINGS_UPDATE, MTLS_TRUST_ANCHOR_ADD, MTLS_TRUST_ANCHOR_REMOVE):

GET    /admin/realms/{realm}/settings/mtls
PUT    /admin/realms/{realm}/settings/mtls                    {"revocationChecking": "HARD_FAIL", "serverTrustAnchors": "FALLBACK"}
POST   /admin/realms/{realm}/settings/mtls/trust-anchors      {"certificate": "-----BEGIN CERTIFICATE-----\n..."}
DELETE /admin/realms/{realm}/settings/mtls/trust-anchors/{id}

A trust anchor is one PEM CA certificate per request, at most 16 KB: basicConstraints cA=TRUE, keyCertSign when it has a key usage, within its validity period, an RSA key of 2048 bits or more, an EC key on P-256, P-384 or P-521, or Ed25519/Ed448, not signed with MD5 or SHA-1, and no private key in the PEM. A realm holds at most 20, each once. An anchor that has expired since it was added stays listed but is not used (PKIX does not check an anchor's own dates, so HelixIAM does). An anchor's own nameConstraints and pathLenConstraint hold for every client certificate below it, as for the certificates in the chain (RFC 5280 §6.1.1(d); the JDK's PKIX validator ignores them on an anchor, so HelixIAM applies them): a name-constrained intermediate uploaded as a realm's anchor accepts only certificates inside its name space, and no longer chain than its path length allows. The realm export carries the anchors (public certificates) and the two settings in its mtls section; an import checks every anchor before it writes anything and then sets exactly the anchors the document lists (migration V200).

The server-wide trust anchors, helix.fapi.mtls.trust-anchors (HELIX_FAPI_MTLS_TRUST_ANCHORS, the path of a PEM file of CA certificates; a path that cannot be read stops the server at startup), apply to a realm as its serverTrustAnchors setting says:

serverTrustAnchors The realm's clients chain to
FALLBACK (default) the realm's own anchors; the server-wide ones only while the realm has none of its own
INCLUDE the realm's own anchors and the server-wide ones
EXCLUDE the realm's own anchors only; without any, the realm offers no tls_client_auth

FALLBACK keeps a single-tenant deployment working with the server-wide file alone, and makes a realm that adds a CA of its own stop trusting the shared CAs, so nobody has to remember to switch them off. Whether the server-wide anchors fall back is decided on the anchors the realm has, not on the usable ones: a realm whose own CA expired gets no anchors, never the server's. A realm's discovery advertises tls_client_auth only while it has a usable anchor (and a client certificate can reach the server). Where tenants share a server-wide CA (FALLBACK with no own anchors, or INCLUDE), a client of one realm can register a subject that a certificate issued for another realm's client carries: give each tenant a CA of its own.

Revocation of client certificates

For tls_client_auth HelixIAM checks the client certificate and every intermediate below the trust anchor for revocation, each against its own issuer: OCSP (RFC 6960) at the responder its Authority Information Access names, then the CRLs (RFC 5280) its CRL Distribution Points name. The OCSP and CRL client is the one the EUDI wallet uses for issuer certificates (CertificateRevocationClient, see EUDI wallet):

  • Nothing is fetched until the chain validated to one of the realm's anchors and the certificate matched the client's registered subject, so a certificate that cannot authenticate the client anyway never causes a fetch.
  • Every URL passes the outbound guard: http and https only (never ldap:), no loopback, private, link-local or metadata address unless the operator allowlisted the host (HELIX_EGRESS_ALLOWED_PRIVATE_HOSTS, for an internal CA's OCSP responder or CRL host), a connection to the address the guard validated (no DNS rebinding), redirects not followed, connect 3 s, 5 s per fetch, 5 s for the whole chain on the token path. OCSP answers are at most 64 KB, CRLs at most 10 MB. The fetches use the login slots for admin-configured targets (helix.outbound.fetch.login-admin.*), at most 8 per realm at a time.
  • An OCSP request carries a fresh nonce (RFC 8954). The response must be signed by the CA or by a responder the CA delegated (id-kp-OCSPSigning), must name the certificate, and thisUpdate/nextUpdate must hold; a response with another nonce never proves a good status. A CRL must be signed by the issuing CA (cRLSign), be current (thisUpdate/nextUpdate, 15 minutes clock skew), be a complete CRL for that distribution point (no delta, indirect or partial CRLs). The JDK validates what HelixIAM fetched and never fetches anything itself.
  • Answers are cached until their nextUpdate (at most 24 h; an OCSP answer without nextUpdate is not cached), bounded in entries and bytes.

The realm's revocationChecking setting decides what happens (same model as the wallet's issuer revocation):

revocationChecking Status cannot be determined (no OCSP/CRL, unreachable, timeout, bad answer) Revoked
HARD_FAIL (default) invalid_client ("cannot be determined") invalid_client
SOFT_FAIL accepted; a warning with realm, client, serial and subject is logged invalid_client
OFF not checked, nothing fetched accepted

HARD_FAIL means a CA used for tls_client_auth must publish OCSP or a CRL that HelixIAM can reach: a client certificate without an AIA OCSP URL or a CRL distribution point is refused. Choosing OFF needs an explicit confirmation ("acknowledgeRevocationOff": true in the same PUT, a checkbox in the console); a realm import that sets OFF is its own confirmation. A revoked certificate is invalid_client and the audit event CLIENT_CERTIFICATE_REVOKED (category AUTHN, outcome DENIED) names the realm, the client, and the revoked certificate's serial, issuer and subject.

Revocation is checked whenever the client authenticates with tls_client_auth: at the token, PAR, introspection, revocation and other endpoints that authenticate the client, so a refresh with a revoked certificate fails. A certificate-bound access token (RFC 8705 §3) is bound to the certificate's thumbprint; a resource server or the userinfo endpoint checks that binding, not the certificate's revocation, so a token issued before the revocation stays usable until it expires. Keep access tokens short-lived. The trust anchor's own revocation is not checked: an anchor is trusted by configuration, so remove it to stop trusting it.

A separate mTLS host. Some deployments ask for client certificates on a separate host only, so browsers on the main host never see a certificate prompt. Set helix.fapi.mtls-base-url (HELIX_FAPI_MTLS_BASE_URL) to that origin, for example https://mtls.idp.example.com (scheme and host only, no path). Discovery then publishes mtls_endpoint_aliases (RFC 8705 §5): the token, PAR, userinfo, introspection, revocation, device authorization and registration endpoints on that origin, with the same paths.

The issuer is derived from the host of the request. So the proxy of the mTLS host must send X-Forwarded-Host with the main (issuer) host, X-Forwarded-Port with its port and X-Forwarded-Proto: https; tokens issued through the aliases then carry the normal issuer. In the example above, for a second server block with server_name mtls.idp.example.com, that means proxy_set_header X-Forwarded-Host idp.example.com; instead of $http_host, and the main host's block can then leave out ssl_verify_client. The mTLS host's proxy must also be in HELIX_TRUSTED_PROXIES and HELIX_FAPI_CLIENT_CERT_TRUSTED_PROXIES.

Not supported yet

  • DPoP server nonces (RFC 9449 §8, use_dpop_nonce): optional for a FAPI 2.0 authorization server; HelixIAM does not ask for one. Replay is prevented by the cluster-wide jti cache and the 60-second iat window.
  • Encrypted request objects and responses (JWE request objects, authorization_encrypted_response_*).
  • Signed introspection responses (RFC 9701).
  • TLS policy inside HelixIAM. HelixIAM serves plain HTTP; TLS 1.2+ with the BCP 195 suites is set at the proxy or ingress (above). HelixIAM does not check the TLS version the proxy negotiated.
  • Revocation of a certificate-bound access token's certificate at the resource: the binding is checked, the certificate's revocation only when the client authenticates (above).
  • LDAP CRL distribution points and OCSP over anything but http/https: such a source counts as not allowed ("endpoint not allowed"; refused under HARD_FAIL).
  • Dynamic Client Registration takes the RFC 8705 metadata, require_signed_request_object (RFC 9101) and authorization_signed_response_alg (JARM), but not a JARM response mode: that stays an administrator's setting (a registered client asks for JARM with response_mode). An RFC 7592 update may raise certificate-bound tokens, signed request objects and the client authentication method, never lower them (invalid_client_metadata): only an administrator does.