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"
  }'

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.