Protocol Endpoints

All endpoints are served from the root of the configured server.issuer URL. Unauthenticated requests to protected endpoints return 401 Unauthorized.

These are the endpoints consumed by OAuth2/OIDC clients, browsers, and end users. For admin-only endpoints see Admin API; for inter-node endpoints see Internal / Gossip API.

OIDC / OAuth2 Discovery

These endpoints are mounted under /.well-known/.

Core OAuth2 / OIDC

Dynamic Client Registration (POST /register)

The POST /register endpoint (RFC 7591) supports two independent authorization paths. A request that satisfies either path is accepted; one that satisfies neither receives 404 Not Found.

Path 1 — Pre-shared initial access token

POST /register
Authorization: Bearer <registration_token>
Content-Type: application/json

Requires server.registration_token to be set in the configuration. When that key is absent this path is unavailable. The token is compared in constant time.

Path 2 — Kerberos service-principal session

A session cookie whose sub claim is a service principal from the server’s own Kerberos realm authorizes registration without any pre-shared secret. The sub must match <service>/<host>@<realm> — that is, the local part (before @) must contain a / character. User principals (alice@REALM) are explicitly excluded. Cross-realm principals (realm does not match server.realm) are also excluded.

The session is obtained via SPNEGO at POST /authorize with no OAuth2 parameters, which returns 400 + Set-Cookie (rather than a redirect, which would cause curl to drop the cookie):

# 1. Load the service principal's TGT
kinit -k -t /etc/http.keytab HTTP/client.ipa.test@IPA.TEST

# 2. Authenticate via SPNEGO; the 400 is expected — the session cookie is set.
curl -s -o /dev/null -w "%{http_code}\n" \
  --negotiate -u: \
  -c /tmp/session.jar \
  https://m1.ipa.test/idp/authorize
# → 400

# 3. Register the OAuth2 client using the saved session cookie.
curl -s \
  -b /tmp/session.jar \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "redirect_uris": ["https://client.ipa.test/callback"],
    "client_name": "client.ipa.test",
    "scope": "openid profile email",
    "token_endpoint_auth_method": "client_secret_basic"
  }' \
  https://m1.ipa.test/idp/register | python3 -m json.tool

The 400 from step 2 is intentional: /authorize received no client_id or other OAuth2 parameters, so there is no flow to start. The error body is {"error":"invalid_request","error_description":"client_id required"}. Despite the error status, the Set-Cookie header is present and curl saves the cookie. The status does not indicate a SPNEGO failure.

Redirect URI scheme enforcement

All redirect_uris supplied in the registration body must use https:// or, for native applications on loopback only, http:// with a loopback host (localhost, 127.0.0.1, or ::1). Any other http:// URI causes the registration to fail with invalid_redirect_uri (RFC 9700 §2.6). This constraint is enforced for both authorization paths above.

kerberos_client_auth is not available via dynamic registration

Specifying "token_endpoint_auth_method": "kerberos_client_auth" in the registration body returns 400 Bad Request with "error": "invalid_client_metadata" regardless of which authorization path is used. Kerberos clients must be registered through the admin API (POST /api/admin/clients). See Kerberos client authentication.

Response

A successful registration returns 201 Created with a JSON body:

{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_name": "client.ipa.test",
  "redirect_uris": ["https://client.ipa.test/callback"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "openid profile email",
  "client_secret": "A3tR…base64url-encoded-32-random-bytes…",
  "registration_client_uri": "https://m1.ipa.test/api/admin/clients/550e8400-e29b-41d4-a716-446655440000"
}

client_secret is server-generated when not supplied in the request body; save it — it is not stored in recoverable form and cannot be retrieved later. registration_client_uri points to the admin API entry for the newly created client. The client is immediately visible at GET /api/admin/clients/{client_id} and is replicated to other cluster nodes via gossip.

Login UI

Browser-facing endpoints used during interactive login flows.

Passkey (WebAuthn)

Requires an active session cookie unless noted. Passkey endpoints are only functional when passkey_rp_id is set in [ipa].

Session / WebUI Auth API

Used by the management WebUI. All endpoints require a valid session cookie unless noted.

User Self-Service

Mounted under /api/me/. All endpoints require a valid session cookie. Operations are scoped to the authenticated user — no privilege escalation is possible.

OTP tokens

Federation callbacks

Endpoints used during upstream IdP authentication flows.

SPIFFE Trust Bundle

This endpoint is active only when [spiffe] trust_domain is set in the configuration.

Response format

{
  "keys": [
    {
      "use": "x509-svid",
      "kid": "ca",
      "kty": "EC",
      "crv": "P-256",
      "x": "…",
      "y": "…",
      "x5c": ["<base64-DER-cert>"]
    },
    {
      "use": "jwt-svid",
      "kid": "…",
      "kty": "EC",
      "crv": "P-256",
      "x": "…",
      "y": "…"
    }
  ],
  "spiffe_sequence": 1,
  "spiffe_refresh_hint": 300
}

spiffe_sequence is a monotonically increasing counter incremented on each CA reload or key rotation. Consumers can use it to detect bundle updates without comparing key material. spiffe_refresh_hint (seconds) is the value of [spiffe] bundle_refresh_hint in the configuration.

When SPIFFE is not configured ([spiffe] trust_domain absent), the endpoint returns 404 Not Found. When SPIFFE is configured but the CA has not yet finished initialising, the endpoint returns 503 Service Unavailable.

SPIFFE JWT-SVID Exchange

This endpoint completes the bidirectional OAuth2 ↔ SPIFFE bridge. It requires [spiffe] trust_domain to be set.

Request

POST /spiffe/jwt-svid
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "audience": ["https://target-service.example.org"],
  "hostname": "web01.example.org",
  "ima_hash": "sha256:deadbeef..."
}

Attestation flow when hostname is provided:

1. The server performs an LDAP lookup to find which IPA host groups the declared hostname belongs to (this step is server-controlled and cannot be bypassed by the caller).
2. A remote AttestationContext is built with UID=u32::MAX, GID=u32::MAX (sentinel values), the declared hostname, the LDAP-resolved host groups, and the parsed ima_hash (if provided).
3. All live registration entries are evaluated; each matching entry produces one JWT-SVID with that entry’s SPIFFE ID.
4. If no entries match, the handler falls back to the client’s registered spiffe_id (single SVID).
5. If neither path yields a SPIFFE ID, 403 Forbidden is returned.

When hostname is absent: a single JWT-SVID is issued using the spiffe_id registered on the OAuth2 client. Returns 403 if the client has no spiffe_id.

Response

{
  "svids": [
    {
      "spiffe_id": "spiffe://example.org/workload/myapp",
      "svid": "<compact-jwt>",
      "hint": ""
    }
  ],
  "bundle": "<trust-bundle-jwks-json>"
}

svids is an array — one element per matched SPIFFE ID. In the simple (no hostname) path it always contains exactly one element. In the remote attestation path it may contain multiple elements when several registration entries match.

bundle is the raw JWK Set JSON from /.well-known/spiffe-bundle, included so callers can verify the SVID without a separate round-trip.

Error codes

SPIFFE Proxy SVID Issuance

This endpoint is the machine-to-machine counterpart of POST /spiffe/jwt-svid. It is designed exclusively for the ahdapa-spiffe-proxy daemon running on IPA-enrolled non-Ahdapa hosts. End-user workloads must not call this endpoint directly. It requires [spiffe] trust_domain to be set.

Authorization

Two checks are applied after token validation:

1. The OAuth2 client whose token is presented must have token_endpoint_auth_method = "kerberos_client_auth". Any other authentication method returns 403 Forbidden.
2. The Kerberos principal stored on the client must have a service component (the part before the first /) that appears in [spiffe] accepted_proxies on the server. When the default ["host", "HTTP"] is in effect, standard IPA host principals (host/myhost@REALM) and HTTP service principals (HTTP/myhost@REALM) are accepted.

Request

POST /spiffe/issue-svid
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "uid": 1000,
  "gid": 1000,
  "supplemental_gids": [10, 100],
  "exe_path": "/usr/bin/myapp",
  "hostname": "client.example.org",
  "ima_hash": "sha256:deadbeef...",
  "audiences": ["service://target.example.org"],
  "x509_spki_b64": "<base64-SPKI-DER>"
}

Attestation behaviour:

Unlike POST /spiffe/jwt-svid, this endpoint does not restrict Uid, Gid, SupplementalGid, or Path selectors. The proxy reads actual workload credentials from its local socket (SO_PEERCRED, /proc/<pid>/exe, /proc/<pid>/status) and forwards them. Ahdapa trusts these values because the client is pre-authorized by accepted_proxies.

IPA host group membership for Hostname and Hostgroup selectors is still resolved by Ahdapa via LDAP and cannot be forged by the caller.

If no registration entry matches the supplied workload identity, 403 is returned. There is no fallback to a client spiffe_id — this endpoint requires at least one matching entry.

Response

{
  "jwt_svids": [
    {
      "spiffe_id": "spiffe://example.org/workload/myapp",
      "svid": "<compact-jwt>",
      "hint": ""
    }
  ],
  "x509_svids": [
    {
      "spiffe_id": "spiffe://example.org/workload/myapp",
      "cert_chain_b64": "<base64-DER-leaf-then-CA>",
      "hint": ""
    }
  ],
  "bundle": "<trust-bundle-jwks-json>",
  "x509_ca_cert_b64": "<base64-DER-CA-cert>"
}

Error codes

ACME Token Authority

This endpoint implements the RFC 9447 Token Authority (TA) protocol for ACME tkauth-01 challenges. It is active only when [gssapi] is configured and a valid GSSAPI credential is available. The endpoint URL is advertised in the AS/OIDC discovery documents as token_authority_endpoint.

Kerberos identity binding. The constraint values carried in the authority token are derived from the authenticated Kerberos principal, not from telephony identifiers. This is a Kerberos-specific issuance path. The EnhancedJWTClaimConstraints (RFC 9118) structure always carries:

• mustInclude: ["sub"] — the ACME server MUST reject any PASSporT that omits the sub claim entirely.
• permittedValues — always contains at minimum:
  • sub bound to the authenticated Kerberos principal name (e.g. alice@IPA.TEST)
  • iss bound to the server’s issuer URL

For host and service principals (those with a / in the local part, e.g. host/client.ipa.test@IPA.TEST or ldap/client.ipa.test@IPA.TEST), the server additionally performs an IPA LDAP lookup to find all hosts and services managed by the authenticated principal (managedBy attribute). When any managed FQDNs are found, a dns entry is added to permittedValues, constraining which hostnames may appear in the PASSporT’s dns claim. The principal’s own hostname is always included in the dns list (justified by IPA’s default ACI that grants every principal write access to its own userCertificate attribute).

For user principals (e.g. alice@IPA.TEST, no / in the local part) no dns entry is added — the token is an identity-only binding.

An ACME server validating the token can use these constraints to confirm both the identity of the principal and the issuing authority, and to restrict which DNS identifiers the PASSporT may assert.

Request

POST /at/account/{id}/token
Authorization: Negotiate <base64-SPNEGO-token>
Content-Type: application/json

{
  "atc": {
    "tktype": "JWTClaimConstraints",
    "tkvalue": "<client-proposed-base64url-DER>",
    "fingerprint": "<ACME-account-key-fingerprint>",
    "ca": false
  }
}

Response

On success, 200 OK with:

{
  "token": "<compact-JWT>"
}

The JWT payload contains:

The JWT is signed with the server’s active JWT signing key (same key used for OAuth2 access tokens, algorithm from [server] jwt_signing_algorithm).

Error codes

Machine-readable Identity API

Mounted under /api/identity/. These endpoints expose user and group identity data to machine clients (primarily SSSD). All endpoints require an access token with the directory.read scope in the Authorization: Bearer header. See Identity API for the full reference and SSSD integration details.

Static assets