Internal / Gossip API

These endpoints carry inter-node CRDT replication traffic and internal service operations. They are served on the same port as the public OAuth2/OIDC endpoints and protected at the application layer — port-level firewall rules cannot isolate them without also blocking public clients.

Gossip endpoints

Credential exchange (OIDC-to-Kerberos)

This endpoint bridges the OAuth2/OIDC world to Kerberos: a FreeIPA server-side component presents a valid access token and receives an exported credential that can be used to perform Kerberos operations on behalf of the authenticated user.

Security model:

• Localhost restriction: when server.ccache_localhost_only is true (the default), the endpoint rejects requests from non-local source IPs with 403 access_denied. “Local” means loopback addresses or any IP address assigned to a local network interface (enumerated via getifaddrs, cached for 30 seconds). This prevents accidental exposure when the endpoint is reachable over the network.
• Bearer token: the request must carry a valid JWT access token in the Authorization: Bearer header. The token must contain a sub claim in Kerberos principal form (user@REALM), a client_id claim, an aud claim that includes the client_id, and the krb5:ccache scope.
• Proof-of-possession (DPoP / mTLS): when the access token contains a cnf claim (RFC 9449 DPoP jkt or RFC 8705 mTLS x5t#S256), the endpoint validates the corresponding proof. DPoP proofs are verified against the endpoint URL {issuer}/api/internal/ccache with method POST. mTLS certificate thumbprints are extracted from the TLS handshake or a trusted proxy header. Missing or mismatched proofs return 401 invalid_token or 401 invalid_dpop_proof.
• User existence check: before attempting S4U2Self, the endpoint verifies that the sub principal exists in the directory (static users file or FreeIPA LDAP). Unknown users are rejected with 403 access_denied.
• HBAC enforcement (fail-open): when no HBAC rules have been created, ccache requests pass through (the krb5:ccache scope check alone gates access). Once at least one HBAC rule is created, the full evaluation runs: user/group membership, client match, scope grant (must include krb5:ccache), source network CIDR, MFA requirement (via AMR), and required ACR. In FreeIPA co-deployments, when the built-in allow_all HBAC rule is enabled (the default), HBAC evaluation is skipped entirely for this endpoint – matching FreeIPA’s default open policy. See Identity HBAC Policy – FreeIPA allow_all.
• Rate limiting: subject to the same per-IP rate limit as other authentication endpoints (server.auth_rate_limit).
• Audit logging: every ccache issuance and denial is recorded in the audit journal with the event type ccache.issued or ccache.denied respectively, including the denial reason.
• Credential encryption: the exported credential bytes are encrypted with gssproxy’s master key and are only usable on the same machine. The credential cannot be replayed on a different host.

Request

POST /api/internal/ccache
Authorization: Bearer <access-token>

The request body must be empty (the route enforces a zero-byte body limit).

Response

On success, 200 OK with Content-Type: application/octet-stream. The response body is a complete MIT Kerberos ccache v4 file (version tag 0x0504). The credential is obtained via S4U2Self and stored into a temporary FILE: ccache via gss_store_cred_into; the file bytes are read back and returned as the response body. The consumer can write the bytes to disk and use them with KRB5CCNAME=FILE:/path, or load them into a MEMORY: ccache via krb5_cc_resolve + krb5_cc_initialize + krb5_unmarshal_credentials.

The response includes Cache-Control: no-store, Pragma: no-cache, and Content-Disposition: attachment.

Error codes

All error responses include a WWW-Authenticate: Bearer error="<error>" header and a JSON body {"error": "<error>"}.

Prerequisites

1. [gssapi] initiator_principal must be configured so the server can perform S4U2Self constrained delegation.
2. The HTTP service principal must have ok_to_auth_as_delegate set so the KDC issues forwardable S4U2Self tickets (required for S4U2Proxy):

   ipa service-mod HTTP/<hostname> --ok-to-auth-as-delegate=true
   

   Without this flag the KDC rejects the S4U2Proxy step with EVIDENCE_TKT_NOT_FORWARDABLE.
3. gssproxy must be running on the same host (when [gssapi] gssproxy = true).
4. The krb5:ccache scope must be defined via the admin API (PUT /api/admin/scopes/krb5:ccache) and assigned to the calling client.
5. At least one HBAC rule must grant the krb5:ccache scope to the relevant users/groups for the calling client (or FreeIPA’s allow_all rule must be enabled).

Access control

Gossip endpoints are protected by two independent mechanisms at the application layer. A rogue client that can reach the server port gains nothing from these endpoints without the corresponding cryptographic keys.

CMS authentication and encryption (/api/gossip/sync, /api/gossip/wrapping-key)

Every gossip sync payload is a CMS SignedData(EnvelopedData) structure:

• The outer ECDSA P-256 signature is verified against the sender’s pinned gossip signing key stored in the CRDT. A node whose key is not pinned receives 401 Unauthorized regardless of the payload contents.
• The inner ML-KEM-768 encryption is addressed to the receiving node’s public key. The encrypted payload is opaque to any party that does not hold the private key.

For /api/gossip/wrapping-key, the requester’s X-Ahdapa-Node-Id must match a node_id in the admission allowlist (see below); the response is itself an EnvelopedData blob encrypted to the requester’s ML-KEM-768 key, so the cluster wrapping key is never transmitted in the clear.

Node admission allowlist (allowed_node_ids)

The [gossip] section of the configuration controls which node_ids are permitted to exchange CRDT state:

[gossip]
# Static allowlist.  Only node_ids listed here may participate.
allowed_node_ids = ["ipa1.example.com", "ipa2.example.com"]

When ipa_topology = true, the allowlist is extended automatically with all replica hostnames discovered from the IPA replication topology, and updated every ipa_topology_interval_secs seconds. Entries from the static list and the topology-derived list are merged; the union fails closed — a node_id absent from both is denied.

Kerberos authentication (/api/gossip/register-kem)

Self-registration requires a valid Kerberos AP-REQ for the local HTTP service. Only HTTP/<hostname>@<REALM> service principals are accepted; user principals are rejected. When gossip.kerberos_realm is set, cross-realm principals are also rejected. The authenticated hostname is validated against the submitted node_id and against the allowlist before any key material is stored.

See Multi-node Cluster and Gossip Protocol for operational details.