Registering an OAuth2 Client

Before a client application can request tokens from ahdapa it must be registered. ahdapa provides three registration paths:

• Static clients file — a TOML file declared via [clients] file = ... in ahdapa.toml. Clients are seeded into the CRDT at startup, gossiped to peers, and protected from API modification. Suitable for pre-provisioned infrastructure clients (e.g. SSSD machine templates, CI pipelines). See Configuration §[clients] for the file format.
• Admin API (POST /api/admin/clients) — operator-controlled registration with full access to every client field.
• Dynamic Client Registration (POST /register, RFC 7591) — automated or self-service registration for applications that manage their own credentials.

All client state lives in the database and is replicated across cluster nodes via CRDT gossip regardless of how the client was registered.

Admin API registration

The admin API gives an operator full control over every client field, including fields that dynamic registration does not expose (Kerberos authentication, grant-type restrictions, mTLS certificate binding, and pairwise subject types).

The admin API requires an authenticated admin session. See Authentication Methods and the RBAC configuration in Configuration for how to grant the clients:write permission.

Create a client

curl -s -X POST https://idp.example.com/api/admin/clients \
  -b session.jar \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Web App",
    "redirect_uris": ["https://app.example.com/callback"],
    "scopes": ["openid", "profile", "email", "offline_access"],
    "token_endpoint_auth_method": "client_secret_basic",
    "client_secret": "change-me-to-a-random-secret"
  }'

Registering a known application (Grafana, GitLab, Zabbix, …) from scratch means remembering which scopes, grant types, and NameID settings it needs. A profile presets those: append ?profile=<id> and the profile’s values fill every field the request body omits — the body always wins, and per-instance fields such as client_name and redirect_uris still come from the request.

curl -s -X POST 'https://idp.example.com/api/admin/clients?profile=grafana' \
  -b session.jar \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Grafana (prod)",
    "redirect_uris": ["https://grafana.example.com/login/generic_oauth"],
    "client_secret": "change-me-to-a-random-secret"
  }'

The admin WebUI’s client and SP create forms show the same list as a “Create from template” picker. GET /api/admin/profiles (profiles:read permission) lists what is available; built-in profiles ship with the binary and [profiles] dirs adds your own — see Configuration Reference — [profiles].

OAuth2 profile signing compatibility

Every built-in OAuth2 preset explicitly sets id_token_signed_response_alg = "RS256". In ahdapa this selects the signing algorithm for both ID tokens and access tokens, including refreshes. The server may continue using ML-DSA-* for other clients; these samples must not inherit an AKP/post-quantum default that their token verifiers cannot process. RSA is a conservative shared baseline, not a claim that all these applications only support RSA.

Upstream configuration and verifier sources were reviewed on 2026-10-30:

The five authorization-code presets also allow offline_access, matching their refresh_token grant. The RP must explicitly request that scope to receive a refresh token: add it to Grafana’s scopes, GitLab’s OmniAuth scope list, Keycloak’s broker Default Scopes, or Nextcloud’s provider scopes when enabling refresh. The device-only daemon preset does not enable the refresh-token grant.

All authorization-code RPs must use S256 PKCE with ahdapa. Settings on the RP itself are not applied by the IdP profile. Never disable signature verification or TLS verification to work around algorithm incompatibility.

An explicit create-request value overrides the preset, for example "id_token_signed_response_alg": "ES256" for a known-capable Grafana installation. Set this only after checking the RP and any resource server that validates its access tokens. Missing node-local keys are provisioned on first use for registrations created or received after startup; no restart is needed to start issuing RSA tokens.

JWKS compatibility is separate from token-signature compatibility. The public /jwks endpoint still contains keys for other algorithms and clients. Some RP/library versions reject an entire mixed JWKS when they encounter an unknown AKP key type, even if the selected token uses RSA. Check the deployed verifier’s handling of unknown keys; these presets do not filter the JWKS or guarantee end-to-end integration with every version.

Profiles only affect new registrations. Updating the shipped files does not retrofit existing clients: edit their id_token_signed_response_alg through the admin API/UI, and use the same profile files on every node.

Successful response — 201 Created:

{
  "client_id": "3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b",
  "client_name": "My Web App",
  "redirect_uris": ["https://app.example.com/callback"],
  "scopes": ["openid", "profile", "email", "offline_access"],
  "token_endpoint_auth_method": "client_secret_basic",
  "source": "dynamic"
}

The client_id is a UUID generated by the server. Store it alongside the client_secret you supplied (the server does not echo secrets on subsequent GET calls).

Request body fields

Supported token endpoint authentication methods

Update a client

PUT /api/admin/clients/{client_id} replaces the registration with the supplied body. The same field constraints apply. Fields that are omitted revert to their defaults; the exception is client_secret and tls_client_certificate_thumbprint, which are preserved from the existing record when the update body omits them.

curl -s -X PUT https://idp.example.com/api/admin/clients/3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b \
  -b session.jar \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Web App (v2)",
    "redirect_uris": [
      "https://app.example.com/callback",
      "https://app.example.com/callback2"
    ],
    "scopes": ["openid", "profile", "email", "offline_access"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'

Response: 200 OK with the full updated client object.

Delete a client

curl -s -X DELETE https://idp.example.com/api/admin/clients/3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b \
  -b session.jar

Response: 204 No Content. The client is tombstoned in the CRDT and propagated to all cluster nodes. Any existing tokens for this client remain valid until they expire (access tokens are self-contained JWTs); revoke outstanding refresh token families separately via DELETE /api/admin/refresh-families/{family_id} if needed.

List and inspect clients

# List all clients
curl -s https://idp.example.com/api/admin/clients -b session.jar

# Get a specific client
curl -s https://idp.example.com/api/admin/clients/3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b \
  -b session.jar

Dynamic Client Registration (RFC 7591)

POST /register allows a client to register itself without operator involvement. It is available via two authorization paths:

Path 1 — Pre-shared initial access token

Set server.registration_token in ahdapa.toml:

[server]
registration_token = "a-random-high-entropy-token"

Then register:

curl -s -X POST https://idp.example.com/register \
  -H "Authorization: Bearer a-random-high-entropy-token" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": ["https://app.example.com/callback"],
    "client_name": "Self-registered App",
    "token_endpoint_auth_method": "client_secret_basic",
    "scope": "openid profile email"
  }'

Path 2 — Kerberos service-principal session

A session cookie whose sub is a service principal in the server’s own Kerberos realm (format service/host@REALM) may register without a pre-shared token. See Authentication Methods for how to obtain such a session via SPNEGO at /authorize.

DCR request body

DCR response — 201 Created

{
  "client_id": "9b2e4f1a-3c7d-4a0e-b8f2-1d5a6c7e8f9g",
  "client_name": "Self-registered App",
  "redirect_uris": ["https://app.example.com/callback"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "openid profile email",
  "client_secret": "server-generated-secret-here",
  "registration_client_uri": "https://idp.example.com/api/admin/clients/9b2e4f1a-3c7d-4a0e-b8f2-1d5a6c7e8f9g"
}

The registration_client_uri points to the admin API resource for this client. Subsequent management (updates, deletion) requires admin RBAC permissions via the admin session — RFC 7592 management tokens are not issued.

Registration for Kerberos clients

kerberos_client_auth clients must be registered via the admin API. Dynamic registration rejects them with invalid_client_metadata. See Authentication Methods for the full workflow including HBAC enforcement and SSSD deployment patterns.

curl -s -X POST https://idp.example.com/api/admin/clients \
  -b session.jar \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "SSSD template client",
    "token_endpoint_auth_method": "kerberos_client_auth",
    "kerberos_principal_pattern": "host/*@EXAMPLE.COM",
    "kerberos_hbac_service": "sssd-idp",
    "scopes": ["openid"]
  }'

The * wildcard in kerberos_principal_pattern matches any hostname in the realm. Each matched machine presents its own Kerberos AP-REQ at the token endpoint; the server verifies it against the pattern and, if kerberos_hbac_service is set, against the replicated HBAC rule set.