Admin API

Mounted under /api/admin/. All endpoints require a valid session cookie with an appropriate RBAC permission. Configure permissions via [[rbac.role]] in the configuration file — without a role that grants * or the specific permission, every admin request returns 403 Forbidden.

See Configuration Reference — [rbac] for the full permission list and role setup.

Client Registry

Redirect URI scheme enforcement (RFC 9700 §2.6): All redirect_uris in POST and PUT requests must use https://, or http:// with a loopback host only (localhost, 127.0.0.1, or ::1). Any other http:// URI is rejected with 400 Bad Request.

Client fields reference

kerberos_client_auth constraints enforced by the admin API:

• [ipa] gssapi = true must be configured on the server; otherwise the request is rejected with 400 Bad Request.
• Exactly one of kerberos_principal or kerberos_principal_pattern must be set.
• kerberos_principal must match the format service/host@REALM (contains / and @).
• kerberos_principal_pattern must contain @ and at most three * wildcards.
• kerberos_client_auth is mutually exclusive with client_secret, jwks_uri, and tls_client_certificate.
• kerberos_client_auth is rejected by POST /register (dynamic registration); use the admin API.

Registration Tokens

RFC 7591 §3 initial access tokens (typ: "reg+jwt") that authorize calls to the public POST /register endpoint without a Kerberos service-principal session or the static server.registration_token. See Protocol – Dynamic Client Registration, Path 2.

Signing Keys

Cluster Nodes

Sessions and Refresh Tokens

Federated Accounts

IPA Identity Providers (Auto-discovered)

These endpoints expose the IPA-sourced upstream IdPs that ahdapa discovers automatically from cn=idp,<suffix> LDAP objects. All LDAP-sourced attributes are read-only; only the default_acr and default_amr override fields can be written via the admin API or the IPA Upstream IdPs page in the WebUI.

GET /api/admin/federation/ipa-idps response (array of):

{
  "id":           "ipa-google-workspace",
  "display_name": "Google Workspace",
  "issuer":       "https://accounts.google.com",
  "client_id":    "123…apps.googleusercontent.com",
  "scopes":       ["openid", "email", "profile"],
  "callback_path":"/internal/callback/ipa-google-workspace",
  "default_acr":  null,
  "default_amr":  [],
  "source":       "ipa"
}

PUT /api/admin/federation/ipa-idps/{id} request body:

{
  "default_acr": "urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword",
  "default_amr": ["pwd", "fed"]
}

Send "default_acr": null and "default_amr": [] to clear overrides (fall back to LDAP-sourced values or the built-in unspecified ACR).

Federation Policies

Pattern-based identity mapping for workload federation. Federation policies are stored in the CRDT and replicated to all cluster nodes via gossip. When an incoming ID token’s iss and sub match a policy’s upstream_iss and subject_pattern (glob), the token exchange resolves the subject to the policy’s local_sub rather than requiring a federated_accounts database row.

Request fields:

Response fields (in addition to the request fields above):

Example:

POST /api/admin/federation-policies
Content-Type: application/json

{
  "upstream_iss": "https://token.actions.githubusercontent.com",
  "subject_pattern": "repo:myorg/*",
  "local_sub": "ci-runner",
  "scopes": ["openid", "profile"],
  "priority": 10
}

Users and Groups (read-only)

Scope Management

Scope definitions control which OIDC claims are returned for each OAuth2 scope name. Eight built-in scopes (openid, offline_access, profile, email, phone, address, groups, directory.read) are seeded on first startup and cannot be deleted. Custom scopes can be created and edited freely.

The directory.read scope gates access to the machine-readable identity API (/api/identity/). It carries no OIDC claims of its own — it is an authorization scope, not a claims scope. See Identity API for endpoint details.

Identity HBAC Policies

See Identity HBAC for policy semantics.

HBAC lookup (typeahead) endpoints

Used by the admin WebUI’s HBAC rule editor to resolve human-readable names while building a rule’s user/group/host/service/client member lists. Each accepts a ?q=PREFIX query parameter and returns at most 20 {value, label} objects (searching static users/groups first, then IPA/LDAP, or the CRDT for clients).

HBAC rule fields reference (delegation-related)

The following fields are present on HBAC rules and control RFC 8693 OBO delegation target enforcement. They appear in GET responses and can be modified via the PATCH (PUT) endpoint.

To modify delegation targets via the PATCH endpoint, use:

# Permit a specific backend SPN
curl -s -b session.jar \
  -X PUT -H 'Content-Type: application/json' \
  -d '{"add_delegation_targets": ["host/backend.example.com"]}' \
  https://idp.example.com/api/admin/hbac/<rule-id>

# Remove a previously permitted SPN
curl -s -b session.jar \
  -X PUT -H 'Content-Type: application/json' \
  -d '{"remove_delegation_targets": ["host/old-backend.example.com"]}' \
  https://idp.example.com/api/admin/hbac/<rule-id>

# Enable wildcard (any target_service allowed by this rule)
curl -s -b session.jar \
  -X PUT -H 'Content-Type: application/json' \
  -d '{"delegation_target_category": true}' \
  https://idp.example.com/api/admin/hbac/<rule-id>

HBAC rule fields reference (registry token endpoint)

The following fields are present on HBAC rules and gate GET /registry/token (see Registry Token Endpoint). They appear in GET responses and can be modified via the PATCH (PUT) endpoint.

To modify these fields via the PATCH endpoint, use:

# Permit pull/push on any repository matching myorg/*
curl -s -b session.jar \
  -X PUT -H 'Content-Type: application/json' \
  -d '{"add_registry_repositories": ["myorg/*"], "add_registry_actions": ["pull", "push"]}' \
  https://idp.example.com/api/admin/hbac/<rule-id>

SAML2 Service Providers

These endpoints manage SAML2 Service Provider registrations. SPs registered here can send AuthnRequest messages to the /saml2/sso endpoint and receive SAML assertions. See SAML2 Federation for the setup guide.

SP create request fields

SP update request fields

All fields are optional. Omitted fields are preserved from the existing registration.

SP response fields

SAML2 Upstream Identity Providers

These endpoints manage upstream SAML2 IdP registrations for the SP role. Each upstream IdP enables a /saml2/auth/{local_id} login flow. See SAML2 Federation for the setup guide.

Metadata import

Both POST /api/admin/saml2/sp/import-metadata and POST /api/admin/saml2/idp/import-metadata accept the same request shape and parse a standard SAML2 <EntityDescriptor> (or <EntitiesDescriptor>) document to populate the SP/IdP fields automatically, instead of specifying acs_urls, sso_url, certificate_pem, etc. by hand.

For the SP import, the selected entity must contain an SPSSODescriptor with at least one AssertionConsumerService; the signing certificate (if any) is taken from the KeyDescriptor with use="signing", and the encryption certificate from use="encryption". For the IdP import, the selected entity must contain an IDPSSODescriptor with at least one SingleSignOnService; the HTTP-Redirect binding is preferred when multiple are present, falling back to the first listed. All signing KeyDescriptor certificates are imported (supports key rollover).

Upstream IdP create request fields

Upstream IdP update request fields

All fields are optional. Omitted fields are preserved from the existing registration.

Upstream IdP response fields

Certificate info

Both SP and upstream IdP responses include parsed certificate details when certificates are registered. Each certificate object contains:

SPIFFE Workload Entries

These endpoints are active only when [spiffe] trust_domain is set. They manage the workload registration entries that the Workload API uses to attest callers and issue SVIDs. See SPIFFE Integration for the full setup guide.

Selector lookup endpoints

These endpoints are used by the admin WebUI SelectorBuilder to resolve human-readable names to numeric IDs. They accept a ?q=PREFIX query parameter and return at most 20 results, searching static users first and then IPA/LDAP.

Example responses:

GET /api/admin/spiffe/lookup/users?q=alice:

[{"value": "alice", "label": "Alice Admin", "uid_number": 10001}]

GET /api/admin/spiffe/lookup/groups?q=web:

[{"value": "web-servers", "label": "web-servers", "gid_number": 8001}]

GET /api/admin/spiffe/lookup/hostgroups?q=web:

[{"value": "web-servers", "label": "web-servers"}]

Workload entry fields

The id field (UUID string) is assigned by the server on POST and returned in the response body. Supply it in the path for GET, PUT, and DELETE requests.

Selector type reference

Selector JSON examples:

{"type": "Uid",           "value": 1000}
{"type": "Gid",           "value": 1000}
{"type": "SupplementalGid","value": 5000}
{"type": "Path",          "value": "/usr/bin/myapp"}
{"type": "Hostname",      "value": "web01.example.org"}
{"type": "Hostgroup",     "value": "web-servers"}
{"type": "ImaHash",       "value": "sha256:deadbeef..."}
{"type": "NodeId",        "value": "node1.example.org"}

When passed in the selectors array of a create/update request, each object must be JSON-encoded as a string:

{
  "spiffe_id": "spiffe://example.org/workload/myapp",
  "selectors": [
    "{\"type\":\"Uid\",\"value\":1000}",
    "{\"type\":\"Path\",\"value\":\"/usr/bin/myapp\"}"
  ]
}

The admin WebUI SelectorBuilder handles this encoding automatically.

SPIFFE status response

GET /api/admin/spiffe/status returns:

Audit Log

Audit events are stored in a systemd journal namespace (ahdapa) via native Unix datagram protocol, with JSONL file and in-memory daemon fallbacks. The admin API queries this journal (or the configured [audit] log_file) and returns structured results.

Query parameters

Response shape

{
  "events": [
    {
      "occurred_at": "2026-06-08T12:34:56Z",
      "event_type": "login.success",
      "subject": "alice@EXAMPLE.COM",
      "principal": null,
      "outcome": "success",
      "detail": null
    }
  ],
  "total_since_startup": 42,
  "limit": 100,
  "offset": 0
}

Audit event fields

Event types

Template client subject: When a kerberos_client_auth client uses kerberos_principal_pattern (template mode), the subject in the audit event is the actual authenticated machine principal (e.g. host/node1.example.com@EXAMPLE.COM), not the template client_id. This makes individual machines distinguishable in audit records even though they share a single client registration.

Admin WebUI behaviour: In the audit log page, subjects that contain / (service principals such as host/node1.example.com@REALM) are rendered as plain text. Subjects without / (regular users) are rendered as clickable links to the user detail page.

Production querying

In addition to the admin API, audit events can be queried directly from the systemd journal using journalctl:

journalctl --namespace=ahdapa --output=json SYSLOG_IDENTIFIER=ahdapa-audit

Journal fields: AHDAPA_EVENT_TYPE, AHDAPA_OUTCOME, AHDAPA_SUBJECT, AHDAPA_PRINCIPAL, AHDAPA_DETAIL, with SYSLOG_IDENTIFIER=ahdapa-audit and PRIORITY (6 = info/success, 4 = warning/failure).