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.

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).

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 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>

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 event schema

Each event object contains:

Event types

Template client sub: When a kerberos_client_auth client uses kerberos_principal_pattern (template mode), the sub 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.