Introduction

Ahdapa is an OAuth 2.0 and OpenID Connect authorization server built for FreeIPA Kerberos environments. It bridges your existing Kerberos identity infrastructure to the OAuth 2.0 / OIDC ecosystem used by modern applications — issuing cryptographically signed JWT tokens to users and services that are already authenticated via Kerberos, with no separate user database and no external identity broker required.

It is the token-issuance counterpart to Akāmu, the ACME certificate authority: where Akāmu issues X.509 certificates, Ahdapa issues OAuth 2.0 bearer tokens.

Key capabilities

• Zero-click SSO for Kerberos domain members via SPNEGO. Clients that are not on the domain can authenticate with a password form, a passkey (WebAuthn), or a federated external IdP.

• Full OAuth 2.0 and OpenID Connect coverage — authorization code + PKCE, client credentials, device flow, token exchange, refresh tokens, DPoP, PAR, mutual-TLS client authentication, and Kerberos machine client authentication (kerberos_client_auth). See Standards for the complete RFC list.

• Machine-readable directory API (/api/identity/) for SSSD and other system-level clients. Bearer-token-gated user and group lookups with a two-phase search protocol compatible with SSSD’s ahdapa_lookup(). Enrolled machines obtain tokens via kerberos_client_auth (no per-machine secret) and use them to resolve users and group memberships on demand.

• Built-in horizontal scaling via a gossip protocol — no external coordinator or shared database required. Signing keys, client registry, and session revocations replicate automatically across all nodes.

• Post-quantum ready — JWT signing with ML-DSA (FIPS 204 / Dilithium); gossip traffic encrypted with ML-KEM-768 (FIPS 203 / Kyber). Classical EC and EdDSA algorithms are supported alongside PQC for mixed-client environments.

• FreeIPA-native — discovers external IdP registrations and per-user authentication constraints directly from FreeIPA LDAP at startup, without duplicating IdP configuration into a local file.

• Access control policies (HBAC) modelled on FreeIPA HBAC rules: define which users may obtain tokens for which clients, from which source networks, with what required authentication strength.

• SPIFFE Workload API — ahdapa can act as a trust domain authority and Workload API server for SPIFFE. When [spiffe] trust_domain is set, ahdapa issues X.509-SVIDs and JWT-SVIDs to local workloads via a Unix domain socket gRPC server, publishes the trust bundle at /.well-known/spiffe-bundle, and bridges SPIFFE identity to OAuth2 by recognising workloads that present their X.509-SVID in an mTLS connection.

• ACME Token Authority (RFC 9447) — when [gssapi] is configured, ahdapa acts as an RFC 9447 Token Authority for ACME tkauth-01 challenges. Clients authenticated via Kerberos SPNEGO obtain a signed authority token JWT whose atc.tkvalue carries base64url-encoded EnhancedJWTClaimConstraints (RFC 9118) with mustInclude: ["sub"] and permittedValues binding sub to the Kerberos principal name and iss to the server’s issuer URL. For host and service principals, the server additionally looks up IPA-managed FQDNs via LDAP and adds a dns entry to permittedValues; user principals receive an identity-only token with no dns constraint. This is a Kerberos-identity binding — not the telephony tnauthlist profile. The endpoint is advertised in the AS discovery document as token_authority_endpoint.

What Ahdapa is not

• Not a reverse proxy or API gateway. Ahdapa can terminate TLS natively (see [tls] configuration) or run behind a TLS-terminating load balancer (nginx, HAProxy, Caddy).

• Not a Kerberos KDC or FreeIPA administration interface. It reads from FreeIPA LDAP and acquires service tickets; it does not create or manage Kerberos principals or directory entries.

• Not a general-purpose ACME certificate authority. Use Akāmu for X.509 certificate issuance within the same Kerberos realm.

• Not a user identity store. Users are authenticated against Kerberos, PAM, or FreeIPA LDAP. Ahdapa does not maintain its own user registry.

Standards coverage

Ahdapa implements OAuth 2.0 (RFC 6749), OpenID Connect Core 1.0, and 20+ related specifications including DPoP, PAR, mTLS client authentication, token exchange, device flow, and the RFC 9447 ACME Token Authority protocol. See Standards for the complete list with implementation scope and known limitations.

Where to go next

Installation

Prerequisites

• Rust toolchain 1.80 or later (install via rustup)
• OpenSSL 3.x development headers (required by native-ossl and synta-certificate)
• MIT Kerberos development libraries (required by ahdapa-gssapi)
• OpenLDAP client development libraries (required by ahdapa-ldap)

Fedora / RHEL

sudo dnf install openssl-devel krb5-devel openldap-devel

To build with PAM support (--features pam), also install:

sudo dnf install pam-devel

The varlink userdb backend (--features varlink) requires no additional system packages; its dependencies are pure-Rust.

Debian / Ubuntu

sudo apt install libssl-dev libkrb5-dev libldap-dev

To build with PAM support (--features pam), also install:

sudo apt install libpam0g-dev

The varlink userdb backend (--features varlink) requires no additional system packages; its dependencies are pure-Rust.

Checking out the source

git clone <ahdapa-repo> ahdapa

All synta dependencies are fetched from crates.io automatically.

Building from source

The repository is a Cargo workspace. Its members include the ahdapa server binary, the ahdapactl admin CLI, and five library crates (ahdapa-gssapi, ahdapa-jose, ahdapa-ldap, ahdapa-varlink, ahdapa-pam).

cd ahdapa
cargo build --release

The server binary is placed at target/release/ahdapa. The admin CLI is placed at target/release/ahdapactl.

To build only the server or only the CLI:

cargo build --bin ahdapa --release
cargo build --bin ahdapactl --release

To enable the optional PAM and varlink authentication backends (recommended for production deployments on systemd-based hosts):

cargo build --bin ahdapa --release --features pam,varlink

Both features are enabled by default in the RPM package.

Building the WebUI

The WebUI is a separate build step. It requires Node.js 20 or later and npm.

cd webui
npm install
npm run build

The built assets are placed at webui/dist/. Point webui.static_dir in the config to this directory.

Verifying the build

./target/release/ahdapa --help

The binary accepts the configuration file path as an optional positional argument, falling back to the AHDAPA_CONFIG environment variable, and finally to /etc/ahdapa/ahdapa.toml. Pass --check to validate the config without starting the server.

Installing

sudo install -m 0755 target/release/ahdapa /usr/local/bin/ahdapa
sudo install -d /etc/ahdapa /var/lib/ahdapa
sudo install -m 0644 webui/dist -r /usr/share/ahdapa/webui

systemd service

Production-grade unit files are provided in contrib/systemd/ in the repository (and installed by the RPM package). Copy them to create a manual installation:

sudo install -m 0644 contrib/systemd/ahdapa.service \
    /etc/systemd/system/ahdapa.service
sudo install -m 0644 contrib/systemd/ahdapa.socket \
    /etc/systemd/system/ahdapa.socket

ahdapa.service passes the configuration file path as a positional argument and includes a full set of hardening directives. ahdapa.socket enables socket activation — see Systemd socket activation for details on when to use it.

A minimal service unit for reference:

[Unit]
Description=Ahdapa OAuth2/OIDC identity provider
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ahdapa
Group=ahdapa
WorkingDirectory=/var/lib/ahdapa
ExecStart=/usr/local/bin/ahdapa /etc/ahdapa/ahdapa.toml
Restart=on-failure
RestartSec=5s
Environment=RUST_LOG=info

NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
StateDirectory=ahdapa
ConfigurationDirectory=ahdapa
LogsDirectory=ahdapa

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now ahdapa

First Run

1. Create directories

sudo mkdir -p /etc/ahdapa /var/lib/ahdapa
sudo chown ahdapa:ahdapa /etc/ahdapa /var/lib/ahdapa
sudo chmod 0750 /etc/ahdapa /var/lib/ahdapa

2. Write a minimal configuration file

Create /etc/ahdapa/ahdapa.toml:

[server]
issuer = "https://idp.example.com"
realm  = "EXAMPLE.COM"

[db]
url = "sqlite:///var/lib/ahdapa/ahdapa.db"

[gssapi]
service = "HTTP"
keytab  = "/etc/ahdapa/ahdapa.keytab"

[ipa]
uri = "ldaps://ipa.example.com"

[webui]
static_dir = "/usr/share/ahdapa/webui"

Replace idp.example.com, EXAMPLE.COM, and the IPA hostname with your actual values.

3. Register the service principal in FreeIPA

ipa service-add HTTP/idp.example.com@EXAMPLE.COM
ipa-getkeytab -s ipa.example.com -p HTTP/idp.example.com@EXAMPLE.COM \
    -k /etc/ahdapa/ahdapa.keytab

4. Start the server

ahdapa /etc/ahdapa/ahdapa.toml

Or via systemd:

sudo systemctl start ahdapa

On first run, the server:

1. Opens (or creates) the database and runs migrations.
2. Generates a fresh JWT signing key pair using the configured algorithm (default: ES256 / ECDSA P-256) and stores it in the cluster state database.
3. Generates a 32-byte AES-256-GCM cluster wrapping key and stores it in the cluster state database.
4. Acquires the GSSAPI server credential from the keytab.
5. Binds on the address from server.listen in the config file (default 0.0.0.0:8080), overridden by AHDAPA_LISTEN if set.

You will see log output like:

INFO ahdapa: Ahdapa starting issuer=https://idp.example.com
INFO ahdapa: GSSAPI server credential acquired
INFO ahdapa: listening addr=0.0.0.0:8080

5. Verify the discovery document

curl https://idp.example.com/.well-known/openid-configuration | jq .

The response is a static JSON document cached for 24 hours. All endpoint URLs will use the configured issuer.

6. Configure RBAC and register an OAuth2 client

All admin API endpoints require RBAC to be configured. Without a [[rbac.role]] / [[rbac.group_role]] section the server returns 403 for every admin request — access is denied to everyone.

Add the following to your config.toml and map it to a group that your admin user belongs to (via the static users file or FreeIPA LDAP memberOf):

[[rbac.role]]
name        = "admin"
permissions = ["*"]

[[rbac.group_role]]
group = "admins"
role  = "admin"

See Configuration Reference — [rbac] for the full permission list and group resolution details.

Once RBAC is configured, use the admin API (requires an authenticated session — log in via the WebUI first):

# Obtain a session cookie by logging in via the browser at:
#   https://idp.example.com/ui/auth/login

# Then register a client:
curl -X POST https://idp.example.com/api/admin/clients \
  -H 'Content-Type: application/json' \
  --cookie 'session=<your-session-cookie>' \
  -d '{
    "client_name": "My Application",
    "redirect_uris": ["https://myapp.example.com/callback"],
    "scopes": ["openid", "profile", "email"],
    "token_endpoint_auth_method": "client_secret_basic",
    "client_secret": "changeme"
  }'

The response contains the generated client_id.

Changing the listen address

Set server.listen in the config file to bind on a non-default address:

[server]
issuer  = "https://idp.example.com"
realm   = "EXAMPLE.COM"
listen  = "127.0.0.1:9090"

For a Unix domain socket (useful when a local reverse proxy or application talks to ahdapa over the same host):

[server]
listen = "unix:/run/ahdapa/ahdapa.sock"

ahdapa removes a stale socket file from a previous run on startup. Note that TLS ([tls] enabled = true) cannot be combined with a Unix socket listener.

The AHDAPA_LISTEN environment variable overrides server.listen without editing the config file, which is convenient for systemd drop-in overrides or container deployments:

AHDAPA_LISTEN=127.0.0.1:9090 ahdapa

Systemd socket activation

ahdapa supports systemd socket activation. When the ahdapa.socket unit is enabled, systemd pre-creates the socket and passes it to ahdapa as an inherited file descriptor. ahdapa detects the passed socket automatically and uses it instead of binding its own.

Enable the socket unit alongside the service:

sudo systemctl enable --now ahdapa.socket
sudo systemctl start ahdapa.service

With socket activation, systemd can start ahdapa on-demand when the first connection arrives, and connections made while ahdapa is restarting are queued by the kernel rather than refused.

The socket address in ahdapa.socket (ListenStream=) must match server.listen in the config file, since ahdapa logs the configured address even when using the inherited socket. The server.listen and AHDAPA_LISTEN values are ignored when a socket is passed by systemd.

Authentication Methods

ahdapa supports several authentication methods for interactive user login. The login page at /ui/auth/login applies them in a fixed priority order: federated identity first, then passkey, then password (static → PAM → LDAP). Only the first matching method is used.

1. Federated identity (upstream IdP redirect)

Ahdapa can delegate authentication to an external OIDC or OAuth2 provider. When a federated IdP is configured, the login page redirects the user there automatically based on their username.

See Federation for setup, FreeIPA auto-discovery, and ACR/AMR override configuration.

2. Passkey (WebAuthn)

After the federated-identity check, if WebAuthn is available in the browser, the login page automatically probes POST /api/auth/passkey/begin for the entered username.

If the user has passkeys enrolled, the browser invokes the platform authenticator (Touch ID, Windows Hello, security key, or phone passkey). On success, a session is issued without the user typing a password. If the user dismisses the authenticator prompt or has no passkeys enrolled, the login page falls through to the password form.

Required configuration:

[ipa]
passkey_rp_id = "idp.example.com"   # must match the domain of the server

passkey_rp_id must be set in [ipa] even when FreeIPA/LDAP is not otherwise used for authentication. Without it, passkey endpoints return 501 Not Implemented and passkey login is silently skipped.

Multi-origin support:

When [server] issuer_aliases is configured (or when IPA auto-derives node aliases from [gssapi] initiator_principal), passkey assertions and registrations are accepted from all configured origins, not just the canonical issuer origin. This means a user can authenticate to https://ipa1.ipa.test/idp with a passkey that was registered against https://ipa-ca.ipa.test/idp, as long as both origins are in the accepted set. The accepted origins are: issuer + all issuer_aliases + auto-derived IPA aliases (node FQDN and ipa-ca.<realm>). No additional configuration is needed for standard IPA deployments.

Passkey self-service enrollment:

Authenticated users can register and delete their own passkeys at /ui/user/profile. The page lists enrolled passkeys by name and registration date and provides a “Register new passkey” button that drives the full WebAuthn attestation flow in the browser.

For FreeIPA/LDAP users, passkey credentials are written to the ipapasskey attribute on the user’s FreeIPA entry using Kerberos S4U2Self impersonation. This makes them visible to any other FreeIPA-aware service (e.g., sssd). For non-IPA users, passkeys are stored in ahdapa’s local database.

3. Password

If neither federated identity nor passkey authentication succeeds, the login page shows a password field. Passwords are verified in order:

1. Static users — username and password are checked against the [[users]] entries in the configuration file.
2. PAM (optional, requires --features pam and a [pam] config section) — credentials are passed to the configured PAM service (typically /etc/pam.d/ahdapa). Covers SSSD, winbindd, systemd-homed, and any other PAM-integrated backend.
3. LDAP simple bind — a bind is attempted against the configured LDAP server as uid=<username> within the discovered domain suffix.

The first backend that returns a definitive answer (authenticated or rejected) wins. PAM and LDAP simple bind are only tried if the previous steps found no match.

Expired passwords (PAM only):

When PAM reports PAM_NEW_AUTHTOK_REQD, the user is redirected to /login/change-password to set a new password before their session is created.

Required configuration (LDAP password):

[ipa]
uri = "ldaps://ipa.example.com"

Required configuration (PAM):

[pam]
service      = "ahdapa"   # /etc/pam.d/ahdapa
timeout_secs = 30

4. OTP (TOTP / HOTP)

Users with OTP tokens enrolled in FreeIPA can authenticate using their password combined with a one-time code. The OTP login stage is reached from the password stage: a link “Sign in with password + OTP code instead” appears below the password form.

The OTP stage shows two separate fields:

• Password — the user’s regular FreeIPA password.
• OTP code — the current 6- (or 8-) digit code from the enrolled token, entered separately on screen.

The server concatenates password + otp_code into a single bind credential, opens an anonymous LDAP connection, and calls a simple bind with the OTP_REQUIRED_OID client control (2.16.840.1.113730.3.8.10.7). FreeIPA’s ipa-pwd-extop SLAPI plugin validates the combined credential at bind time — ahdapa never reads the raw OTP secret (ipatokenOTPkey). The control also tells ipa-pwd-extop to reject the bind if no valid OTP code is appended, even if the password alone is correct.

Invalid credentials (LDAP code 49) produce a “Wrong username, password, or OTP code” error. All other LDAP errors are treated as server errors.

Required configuration:

[ipa]
uri = "ldaps://ipa.example.com"

OTP tokens must be enrolled in FreeIPA for the user. They can be enrolled using the FreeIPA CLI (ipa otptoken-add) or via the self-service profile page at /ui/me (see OTP token self-service below).

OTP token self-service

Authenticated users can list, add, and delete their own OTP tokens at /ui/me (the profile page), under the “OTP tokens” section. No administrator action is required.

• List — shows all enrolled tokens with label, type (TOTP/HOTP), algorithm, digits, period, and status.
• Add — creates a new TOTP token. The otpauth:// URI is displayed once as a QR code (inline SVG) and as a copyable text string. Close the dialog only after the token has been scanned — the dialog cannot be dismissed any other way, and the secret is not stored by ahdapa.
• Delete — removes a token by its unique ID. Only tokens owned by the current user can be deleted.

The self-service endpoints require a valid session cookie. The sub from the session identifies the acting user; no privilege escalation is possible.

5. SPNEGO / Kerberos (browser-level)

For domain-joined browsers (Firefox, Chrome on Linux with Kerberos credentials), SPNEGO negotiation happens at the HTTP layer on two routes:

• GET /ui/auth/login — The login page handler inspects Authorization: Negotiate before serving the SPA HTML. On success it sets a session cookie (ACR urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos, AMR kerberos) and redirects to return_to. On Continue (multi-round GSSAPI exchange) it returns 401. When no valid Negotiate token is present it falls through to the SPA HTML so password login still works.

• GET/POST /authorize — The authorization endpoint also runs SPNEGO before validating query-string parameters. This enables a single-round-trip OAuth2 flow for curl-style command-line clients:

  • Authorization: Negotiate present + valid OAuth2 params → authenticates, creates a session, and continues the OAuth2 authorization flow in the same request (no redirect-then-retry). The session cookie is appended to the consent redirect response.
  • Authorization: Negotiate present + no OAuth2 params → authenticates, creates a session, returns 400 {"error":"invalid_request","error_description":"client_id required"} with Set-Cookie (no redirect, so curl keeps the cookie for subsequent requests).
  • No Negotiate header → existing session-cookie flow unchanged.
  • Continue → 401 challenge.

This dual-endpoint design is transparent: users visiting the login page are forwarded to their destination automatically if their browser holds a valid Kerberos ticket and the server accepts Negotiate. Command-line clients (curl, httpie) can obtain a session cookie from /authorize without being redirected to the login page.

Service-principal self-registration of OAuth2 clients:

Kerberos service principals (principals whose local part contains /, such as HTTP/client.ipa.test@IPA.TEST) can use the SPNEGO session obtained from /authorize to self-register an OAuth2 client at POST /register without requiring a pre-shared server.registration_token. User principals (no / in the local part, e.g. alice@IPA.TEST) and cross-realm principals are excluded from this path. See Dynamic Client Registration for the full curl workflow and response format.

Required configuration:

[server]
realm = "EXAMPLE.COM"

[gssapi]
service = "HTTP"
keytab  = "/etc/ahdapa/ahdapa.keytab"

Or, using gssproxy instead of a keytab:

[gssapi]
service  = "HTTP"
gssproxy = true

If [gssapi] is absent or the keytab is unreadable at startup, SPNEGO is disabled and a warning is logged. Password and passkey authentication continue to work.

Kerberos client authentication (kerberos_client_auth)

This section covers machine-to-machine OAuth2 client authentication using Kerberos. It is distinct from user-facing SPNEGO (section 5 above): rather than a user proving their identity to obtain a session, a machine proves the identity of the OAuth2 client itself at the token endpoint, replacing a client_secret.

This feature is designed for large-scale SSSD id_provider = idp deployments where every FreeIPA-enrolled machine already holds a Kerberos keytab (host/hostname@REALM) and rotating a shared client_secret across thousands of machines is operationally undesirable.

Prerequisites

• [ipa] gssapi = true must be set in the server configuration.
• [gssapi] keytab or [gssapi] gssproxy = true must be configured so the server can accept SPNEGO tokens.
• The client must be registered via the admin API (not dynamic registration — see below).

Two registration modes

Single-machine client — binds one client ID to one specific host principal:

{
  "client_name": "node1.example.com SSSD client",
  "token_endpoint_auth_method": "kerberos_client_auth",
  "kerberos_principal": "host/node1.example.com@EXAMPLE.COM",
  "scopes": ["openid"]
}

Template client — one client ID covers all machines whose principal matches a glob:

{
  "client_name": "SSSD template client",
  "token_endpoint_auth_method": "kerberos_client_auth",
  "kerberos_principal_pattern": "host/*@EXAMPLE.COM",
  "scopes": ["openid"]
}

The * wildcard in kerberos_principal_pattern matches any sequence of characters except @. At most three wildcards are permitted per pattern.

Exactly one of kerberos_principal or kerberos_principal_pattern must be set. kerberos_client_auth is mutually exclusive with client_secret, jwks_uri, and tls_client_certificate.

HBAC access control (kerberos_hbac_service)

An optional kerberos_hbac_service field names a FreeIPA HBAC service. When set, the server evaluates the replicated IPA HBAC rule set for the authenticated machine principal before issuing a token:

{
  "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"]
}

Create the corresponding HBAC service and rules in FreeIPA:

ipa hbacsvc-add sssd-idp --desc "SSSD IdP token endpoint access"
ipa hbacrule-add sssd-idp-allowed --desc "Allow enrolled hosts to get IdP tokens"
ipa hbacrule-add-service sssd-idp-allowed --hbacsvcs=sssd-idp
ipa hbacrule-add-host sssd-idp-allowed --hosts=node1.example.com --hosts=node2.example.com

Known limitation: Rules that match machines by hostgroup membership currently evaluate as deny — individual hostname-based rules work correctly. Use individual host entries in the HBAC rule until hostgroup resolution for machine principals is implemented.

When kerberos_hbac_service is configured and the HBAC rule set is empty (no rules have been mirrored yet), the server denies all tokens (fail-closed) rather than granting open access.

Token flow

The machine presents its Kerberos AP-REQ token in the standard HTTP Negotiate header. kerberos_client_auth is accepted on both the token endpoint (/token) and the device authorization endpoint (/device_authorization), enabling Kerberos-authenticated clients to use either the client credentials flow or the device authorization flow.

Client credentials (machine-only token):

POST /token
Authorization: Negotiate <base64-encoded-AP-REQ>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<template_client_id>&scope=openid

Device authorization (machine authenticates the client, user authorises via browser):

POST /device_authorization
Authorization: Negotiate <base64-encoded-AP-REQ>
Content-Type: application/x-www-form-urlencoded

client_id=<template_client_id>&scope=openid+offline_access

The client must have urn:ietf:params:oauth:grant-type:device_code in its grant_types to use the device authorization endpoint.

The server calls try_spnego() to verify the token and extract the authenticated principal. Multi-round GSSAPI exchanges are not supported on these endpoints — the AP-REQ must complete authentication in a single round trip (which is the normal case for host/ service principals).

Token sub for template clients

For single-principal clients, the sub of issued access tokens is the registered client_id.

For template clients (those with kerberos_principal_pattern), the sub is the actual authenticated machine principal (e.g. host/node1.example.com@EXAMPLE.COM) rather than the template client_id. This makes individual machines distinguishable in audit logs and token introspection responses even though they share a single client registration.

Discovery advertisement

kerberos_client_auth is listed in token_endpoint_auth_methods_supported in both /.well-known/oauth-authorization-server and /.well-known/openid-configuration only when [ipa] gssapi = true. When GSSAPI is disabled, the method is absent from discovery so that clients do not attempt to use it.

Dynamic registration exclusion

POST /register rejects "token_endpoint_auth_method": "kerberos_client_auth" with invalid_client_metadata. Kerberos clients must be registered through the admin API (POST /api/admin/clients) by an administrator.

SSSD deployment model

The template client pattern enables a zero-secret SSSD deployment. Every enrolled machine uses the same sssd.conf — no per-machine client secret needs to be generated, distributed, or rotated:

# /etc/sssd/sssd.conf — identical on every enrolled machine
[domain/example.com]
id_provider = idp
idp_client_id = <template_client_id>
# No idp_client_secret — SSSD uses the machine's Kerberos keytab directly

The template client must include directory.read in its allowed scopes so that SSSD can call the identity API (/api/identity/users, /api/identity/groups) after obtaining a token. SSSD uses a two-phase lookup: Phase 1 searches by username or group name; Phase 2 resolves group memberships or group members using the id from Phase 1. See Identity API for the full endpoint reference.

FreeIPA admin workflow for a new deployment:

1. Register one template client via the admin API with kerberos_principal_pattern = "host/*@EXAMPLE.COM", scopes: ["openid", "directory.read"], and optionally kerberos_hbac_service = "sssd-idp".
2. In IPA, create HBAC service sssd-idp and create HBAC rules scoped to the relevant hosts or hostgroups.
3. Deploy sssd.conf with the single idp_client_id across all enrolled machines. No secrets to distribute or rotate.

FreeIPA ipauserauthtype enforcement

When [ipa] gssapi = true, ahdapa reads each user’s ipauserauthtype LDAP attribute during the password (api_auth), OTP, and passkey token flows and applies it as a method gate before proceeding with authentication. The per-user attribute overrides the global default fetched from cn=ipaconfig,cn=etc,<suffix>. An empty effective set means no restriction.

The recognised values are: password, otp, pkinit, hardened, idp, and passkey.

Effect on token flows:

• If idp is in the effective set, the flow immediately returns a 401 with:

  {
    "error": "federated_login_required",
    "error_description": "This account must authenticate via an external identity provider.",
    "redirect_to": "/auth/external/ipa-google-workspace"
  }
  

  The redirect_to field names the upstream IdP derived from the user’s ipaidpconfiglink attribute. The client or browser should redirect the user to that path to complete authentication via the external IdP.

• If the attempted method is absent from a non-empty effective set (and idp is not set), the flow returns:

  {
    "error": "invalid_credentials",
    "error_description": "Authentication method not allowed by user policy."
  }
  

The gate is a soft check: if the user entry cannot be fetched from LDAP or the IPA API, the flow proceeds as if there is no restriction (fail-open). The SPNEGO / Kerberos flow is not gated — Kerberos authentication is always permitted when the server has a valid keytab.

The global default auth types are loaded at startup and refreshed every 300 seconds alongside IPA IdP discovery.

Identity HBAC policy enforcement

After a user session is established, Ahdapa evaluates all live Identity HBAC policies before issuing a token. See Identity HBAC Policy for rule structure, axis semantics, and the admin API.

Session lifetime

A successful login by any method issues a session cookie. The session is valid for the duration configured in [tokens]:

The session cookie is HttpOnly, Secure, and SameSite=Lax. It is used by the admin WebUI and by the consent/device-verification flows.

Rate limiting

Authentication attempts (password, SPNEGO, passkey) are rate-limited per source IP. The default limit is 20 attempts per five-minute rolling window, configurable via server.auth_rate_limit in [server].

Requests exceeding the limit receive 429 Too Many Requests.

Authentication context claims (acr and amr)

Every token ahdapa issues for a user session carries two standard claims that describe how the user authenticated:

• acr — Authentication Context Class Reference (SAML 2.0 Authentication Context classes, as referenced by OIDC Core §2).
• amr — Authentication Method Reference (RFC 8176 value strings).

MobileOneFactorContract (SAML AC §3.4) covers authentication with a registered, hardware-bound credential — the appropriate class for FIDO2/WebAuthn passkeys. hwk (RFC 8176 §2) indicates a hardware-protected key.

Machine-to-machine grant types (client_credentials, token_exchange, jwt_bearer, device_code) do not set acr or amr; there is no interactive user session to characterise.

All four user-facing ACR values are advertised in the OIDC discovery document under acr_values_supported. Relying parties that require a minimum assurance level can include acr_values=... in their authorization request; ahdapa will reject the request with access_denied if the authenticated session does not satisfy the requested class.

The values are preserved across token refresh: the acr and amr from the original login session are carried into every renewed access token and ID token until the refresh token family expires.

Federation

Ahdapa can delegate authentication to an external OIDC or OAuth2 identity provider (upstream IdP). When a user’s identity is managed by an upstream IdP — a corporate SSO, a cloud provider, or a FreeIPA-registered external directory — Ahdapa redirects the browser there, receives the callback, maps the returned claims to a local identity, and issues its own OAuth2/OIDC tokens.

The result is a seamless single sign-on flow: end users authenticate at the provider they already use, and applications receive standard Ahdapa tokens.

How the federated login flow works

When an [[federation.upstream_idps]] entry is configured (or auto-discovered from FreeIPA), the login page checks the entered username against GET /api/auth/federated-hint. If the response contains an upstream_id, the browser is immediately redirected to that provider’s authorization endpoint — no local password form is shown.

The hint endpoint resolves an upstream IdP via two steps:

1. Fast path — looks up the username in the federated_accounts database table (accounts that have previously completed a federated login or were linked by an administrator).
2. Slow path (IPA only) — when no entry is found and [ipa] gssapi = true, performs an IPA LDAP lookup using the service principal credential (not S4U2Self, because the user has not authenticated yet and cannot read their own ipaidpconfiglink attribute). If ipauserauthtype=idp is set on the IPA user, the endpoint returns {"upstream_id":"ipa-<slug>"} so that first-time IPA IdP users are correctly redirected without needing a prior federated_accounts record.

When configured, a “Sign in with …” button also appears on the login page for users who want to choose their provider explicitly rather than typing an email-matched username.

Manual configuration

Add one [[federation.upstream_idps]] block per upstream IdP in ahdapa.toml:

[[federation.upstream_idps]]
id            = "corp-sso"
issuer        = "https://sso.partner.example.com"
client_id     = "ahdapa"
callback_path = "/internal/callback/corp-sso"
# client_secret = "…"   # omit for public clients (PKCE-only)

The callback_path value must be registered as a redirect URI at the upstream provider. Use the stable cluster hostname (e.g. ipa-ca.<domain>) rather than a per-node FQDN so the URI stays valid across node failures.

Cluster deployments and load balancers: Using a stable cluster hostname for the callback URI is recommended but not strictly required for correctness. Even if the upstream IdP sends the callback to a cluster node that did not start the flow, the handler will forward the browser to the correct originating node via a 302 redirect — see Cross-node callback routing below.

See Configuration Reference — [[federation.upstream_idps]] for the full list of fields including account linkage, scope mapping, and authentication method.

FreeIPA auto-discovery

When [ipa] gssapi = true (the default for IPA co-deployment), Ahdapa automatically reads all ipaIdP LDAP objects from cn=idp,<suffix> at startup and refreshes them every 300 seconds. Each discovered IdP becomes an upstream IdP registration without any TOML entry:

• id: the CN lowercased with spaces replaced by -, prefixed with ipa- (e.g. "Google Workspace" → "ipa-google-workspace").
• callback_path: /internal/callback/ipa-{slug} — register this URL as a redirect URI at the upstream provider. Use the stable ipa-ca.<domain> hostname: https://ipa-ca.ipa.test/idp/internal/callback/ipa-<idp-cn>
• Authentication method: client_secret_post when ipaIdpClientSecret is present, otherwise none (public client, PKCE-only).
• The IdP’s issuer is automatically added to the trusted issuers list for JWT validation.

If a static [[federation.upstream_idps]] entry has the same id as an IPA-sourced entry, the static entry takes precedence.

Federated user resolution — no local database row required

When a user whose ipaidpconfiglink points to an IPA-managed IdP completes the federated login flow, Ahdapa resolves the local uid directly via LDAP using the filter:

(&(objectClass=ipaIdpUser)(ipaIdpConfigLink=<dn>)(ipaIdpSub=<external-subject>))

No federated_accounts database row is needed for these users — the link between the IPA uid and the external identity is stored in the IPA directory (ipaIdpConfigLink + ipaIdpSub on the user entry). Only users whose IdP is not registered in FreeIPA require a federated_accounts row created at first login.

LDAP indexes (recommended)

The filter above triggers a full scan of cn=accounts,<suffix> unless equality indexes exist on ipaIdpConfigLink and ipaIdpSub. Add them once on the primary IPA server:

# Replace IPA-EXAMPLE-COM with your realm (dots → dashes).
dsconf slapd-IPA-EXAMPLE-COM backend index add \
    --attr ipaIdpConfigLink --index-type eq userRoot
dsconf slapd-IPA-EXAMPLE-COM backend index add \
    --attr ipaIdpSub --index-type eq userRoot
dsconf slapd-IPA-EXAMPLE-COM backend index reindex \
    --attr ipaIdpConfigLink --attr ipaIdpSub --wait userRoot

The Ansible playbook playbooks/ipa_permissions.yml creates these indexes automatically.

IPA upstream IdP ACR/AMR overrides

IPA-sourced IdPs often do not return acr or amr claims in their userinfo response. To stamp meaningful authentication context into tokens issued after an IPA-managed upstream IdP flow, set per-IdP defaults via the admin panel.

These overrides are stored in the CRDT and gossiped to all cluster nodes, so they survive restarts and take effect on every node without changing the TOML file.

Admin UI

The IPA Upstream IdPs page in the admin panel (/ui/admin/federation/ipa-idps) lists all IdPs currently discovered from cn=idp,<suffix>. Each entry shows the LDAP-sourced fields (issuer, client ID, scopes, callback path) as read-only and exposes two writable fields:

Requires federation:read to view, federation:write to edit.

Admin API

See Admin API — IPA Identity Providers for the full endpoint listing and request/response examples.

Trusted issuers

IPA-sourced IdP issuers are automatically trusted for JWT validation. For manually configured IdPs, list their issuers explicitly:

[federation]
trusted_issuers = [
    "https://sso.partner.example.com",
]

Federation state security

Each time a user is redirected to an upstream IdP, Ahdapa generates a structured state token that is round-tripped through the browser:

base64url(issuer) . base64url(rand32) . base64url(HMAC-SHA256(refresh_key, "ahdapa-fed-state-v1:" || issuer || "." || rand_b64))

The three dot-separated components are:

The refresh key is derived from the cluster wrapping key via HKDF (info = "ahdapa-refresh-v1") and is therefore identical on all cluster nodes that share a wrapping key.

When the upstream IdP returns the user to /internal/callback/{id}, the handler verifies the MAC in constant time (using subtle::ConstantTimeEq) before touching the database. A tampered or forged state value is rejected before any redirect or database lookup occurs, preventing open-redirect attacks.

upstream_id CSRF guard: After the MAC is verified and the state row is retrieved from the database, the callback handler confirms that the upstream_id recorded in the database row matches the upstream_id from the URL path. A mismatch (which would indicate tampering with the callback URL) causes the handler to restart the auth flow rather than proceed with the mismatched configuration.

Rolling-upgrade tolerance: state tokens from an older node that did not include the MAC (legacy single-component format, no dots) are detected and handled as an unknown state — the handler restarts the auth flow rather than returning an error, allowing zero-downtime upgrades.

Cross-node callback routing

In a cluster behind a load balancer, the upstream IdP may send the callback to a different node than the one that started the flow. The pending auth state (nonce, PKCE verifier, original request parameters) is stored in the originating node’s local database and is not gossiped.

When the callback handler cannot find the state in its local database, it extracts the originating node’s issuer URL from the verified MAC state token and checks it against the configured gossip.peers and dynamically discovered IPA topology peers. If the issuer belongs to a known cluster member, the handler issues a 302 redirect to forward the browser to the correct node. The originating node completes the normal DB lookup and finishes the flow.

sequenceDiagram
    participant B as Browser
    participant LB as Load Balancer
    participant NA as Node A (started flow)
    participant NB as Node B (received callback)

    B->>LB: GET /internal/callback/corp-sso?code=…&state=…
    LB->>NB: forward
    NB->>NB: verify state MAC — OK
    NB->>NB: DB lookup — not found (flow started on Node A)
    NB->>NB: extract issuer from state → Node A URL
    NB->>NB: check issuer ∈ gossip.peers — known peer
    NB-->>B: 302 → Node A /internal/callback/corp-sso?code=…&state=…
    B->>NA: GET /internal/callback/corp-sso?code=…&state=…
    NA->>NA: verify state MAC — OK
    NA->>NA: DB lookup — found
    NA->>NA: exchange code, create session
    NA-->>B: 302 → resume URL + Set-Cookie: session=…

Security: the forwarding step only occurs after the HMAC is verified. Only known cluster members (listed in gossip.peers or discovered via ipa_topology) are forwarding targets. An unknown or forged issuer in the state token is rejected, and the flow is restarted rather than forwarded.

This mechanism requires no CRDT gossip of pending auth state and adds only one browser round-trip of latency. The upstream IdP callback URI does not need to be node-specific, and using a stable cluster hostname for callback_path remains the recommended practice.

SSRF protection for external URLs

Any administrator-supplied URL that Ahdapa will fetch from — federation callback base URLs, upstream IdP issuer/discovery URLs, OAuth2 client jwks_uri, and SPIFFE bundle endpoint URLs — is validated before storage or use. URLs that could cause server-side request forgery (SSRF) are rejected with 400 Bad Request. The following address ranges are blocked:

Public HTTPS URLs that do not resolve to any of the above are accepted.

OIDC Federation 1.0

Ahdapa publishes a spec-compliant Entity Statement at /.well-known/openid-federation. Incoming federated assertions are validated against the trusted_issuers list only. Full trust-chain resolution (intermediaries, metadata_policy merging) is not yet implemented.

See Standards for the known-limitations entry.

Multi-node Cluster

A single ahdapa instance is sufficient for most deployments. Run multiple nodes when you need horizontal redundancy — any node can serve all OAuth2 and OIDC endpoints, and gossip keeps their state in sync automatically.

How the cluster works

Each node holds its full cluster state in memory and in its local database. Every gossip.interval_secs seconds (default 5 s) a node contacts each peer listed under gossip.peers. By default the node sends only the CRDT entries that changed since the last successful exchange with that peer (a delta), rather than the full state. On first contact, or after any error, it falls back to a full-state push. The peer merges the received state and replies (also as a delta or full state) with its own. One round-trip brings both nodes to the same state. See Gossip Protocol for full protocol details.

The cluster wrapping key is the AEAD key for session cookies and auth codes. All nodes must share the same wrapping key for session cookies to be interchangeable across nodes. The wrapping key itself is stored node-locally (not gossiped); only a UUID identifier is gossiped so that nodes can detect key rotation. Gossip messages are authenticated and encrypted using CMS (see Gossip encryption below).

Distributed modes

The [cluster] configuration section controls how tightly the cluster coordinates token issuance. Four modes are available, ordered from least to most coordination:

JTI cache: Each auth code contains a unique JWT ID (JTI). When an auth code is exchanged for tokens, the JTI is recorded in an in-memory cache on the receiving node so that a second exchange attempt is rejected. This prevents a stolen auth code from being replayed — but only on the node that holds the cache entry.

Modes are strictly ordered: each higher mode is a superset of the features below it. The default (off) is correct for single-node deployments and benchmarks. For high-availability clusters, eventual is the recommended starting point.

off — no cross-node coordination

Auth codes are single-use enforced by a node-local JTI cache. They can only be exchanged on the node that issued them. Session revocation is node-local only: a logout on node A does not propagate to node B. Suitable for single-node deployments.

eventual — CRDT session revocation

Session revocations (logout, back-channel logout) are written into the revoked_sessions LwwMap in the CRDT and propagate to all peers via gossip within one gossip interval (default 5 s). Any cluster node rejects cookies whose iat is before the stored revoked_at for that subject.

Auth codes may be exchanged on any cluster node with a replay window of approximately one gossip interval. This is acceptable for most HA deployments where occasional replay is tolerable.

Propagation latency: revocation is not instantaneous. A logout issued on one node reaches all peers within one gossip interval (default 5 s). Use forwarding or strict mode if a shorter window is required for auth codes; session cookie revocation remains gossip-propagated in all modes.

forwarding — zero-window auth code exchange

Adds auth code forwarding on top of eventual. When a node receives an auth code exchange request for a code it did not issue, it uses the internal endpoint POST /api/internal/token/auth-code to forward the request to the origin node. The origin node performs single-use enforcement, eliminating the gossip-interval replay window.

Forwarding supports hub-spoke topologies via a 1-hop relay: if node A and node B are not directly peered (e.g. in a hub-spoke topology), A sends the request to a relay C that has both A and B as RecipientInfos in the CMS envelope. C forwards the original encrypted body to B. The X-Ahdapa-Final-Dest header carries the ultimate destination. A hop-count guard returns 508 Loop Detected when the hop count reaches 2, preventing forwarding loops.

strict — quorum pre-approval

Adds k-of-n quorum pre-approval on top of forwarding. Before signing any access token, the issuer broadcasts a VoteRequest to all live peers via POST /api/internal/quorum/vote and waits for k approvals within quorum_timeout_ms milliseconds. A minority partition cannot unilaterally issue tokens.

The effective quorum size k is controlled by cluster.quorum_k:

• 0 (default): majority — floor(live_peer_count / 2) + 1
• positive integer: exact count required

When quorum cannot be reached and cluster.quorum_fallback = true, a warning is logged and the token is issued anyway. When quorum_fallback = false (default), the token request is rejected with an error.

Internal node-to-node endpoints

Both forwarding and strict modes use the following internal endpoints. These endpoints return 404 Not Found when distributed_mode = off or eventual.

Both endpoints authenticate the request body using the sender’s gossip signing key (ECDSA P-256). Nodes whose signing key is not yet registered in the CRDT are rejected with 401 Unauthorized.

Like /api/gossip/sync, these endpoints authenticate the request body using the sender’s pinned gossip signing key and reject unsigned or unknown senders with 401 Unauthorized.

Node configuration

Each node needs its own config file. The sections that differ between nodes are [gossip].peers (which lists the other nodes) and whatever address-specific settings your deployment uses ([server].issuer, TLS paths, etc.).

For FreeIPA-integrated deployments, you can replace the static peer list with automatic topology-based discovery — see IPA topology discovery.

Minimum gossip stanza (static peers)

# node1.toml
[gossip]
peers         = ["https://node2.example.com:8080", "https://node3.example.com:8080"]
interval_secs = 5

# node2.toml
[gossip]
peers         = ["https://node1.example.com:8080", "https://node3.example.com:8080"]
interval_secs = 5

# node3.toml
[gossip]
peers         = ["https://node1.example.com:8080", "https://node2.example.com:8080"]
interval_secs = 5

Set a stable identity for each node. The preferred method is the [server] node_id configuration key; ahdapa also falls back to the HOSTNAME environment variable, then to the system hostname, then to a random UUID (which changes on every restart and should be avoided in clustered deployments):

# node1.toml
[server]
node_id = "node1.example.com"

Full-mesh vs hub-and-spoke

ahdapa gossip is full-mesh by default: every node lists every other node as a peer. Full-mesh uses N×(N−1) pushes per interval. In steady state each push carries only the delta of entries that changed since the last successful sync with that peer; a full-state push (the worst case for bandwidth) occurs only on first contact or after an error.

These figures are theoretical maximums (every gossip round pushes a full state). In practice, two optimisations suppress traffic in converged clusters:

1. Generation-skip: if the local CRDT has not changed since the last successful sync with a peer (CRDT_GENERATION unchanged), the push is skipped entirely.
2. Delta exchange: when a push does occur, only entries newer than the peer’s last known generation are included.

A live token-issuing cluster observed 93% of rounds skipped (7 actual pushes / 108 attempts in a 35 s window). When pushes do occur, deltas are typically a small fraction of the full state. Pushes happen only when a client is created/deleted, a key is rotated, or a node joins/leaves. Steady-state bandwidth in a converged cluster is near zero.

Worst-case (full-state) bandwidth at the default 5-second interval with a 3-node baseline push size of ~7.5 KB (empirically observed; includes CMS envelope overhead):

Per-push size growth:

• Each additional cluster node: +~1,530 B (ML-KEM-768 public key dominates)
• Each registered OAuth2 client: +~150 B per push body (compact CBOR, 2-char field names)
• Each active session (refresh family): +~60 B — expired families are purged every gossip round, so growth is bounded by max_refresh_token_age

Recommendation: Use full-mesh for up to 5 nodes. Switch to hub-and-spoke for 7+ nodes, or earlier if you have thousands of active sessions.

Hub-and-spoke configuration example (node1 is the hub):

# hub: node1.toml — peers with all spokes
[gossip]
peers = ["https://node2.example.com:8080", "https://node3.example.com:8080",
         "https://node4.example.com:8080", "https://node5.example.com:8080"]

# spoke: node2.toml — peers with hub only
[gossip]
peers = ["https://node1.example.com:8080"]

With hub-and-spoke, state propagates from spoke to spoke in 2 gossip rounds (spoke → hub → spoke) rather than 1, adding at most 2 × interval_secs of additional latency.

Provisioning a fresh cluster

IPA-integrated deployments: If you are deploying ahdapa on a FreeIPA cluster, the Ansible playbooks in contrib/demo/ipa/ansible/ handle node provisioning, wrapping-key synchronisation, and IPA privilege grants automatically. Run ansible-playbook -i inventory.ini contrib/demo/ipa/ansible/site.yml and skip the manual steps below. See FreeIPA Co-deployment for details.

Using the admin CLI: The ahdapactl cluster bootstrap command automates steps 2–5 below. Run it with the list of node URLs and it handles login, key generation, key distribution, and re-authentication in a single invocation:

ahdapactl cluster bootstrap \
  https://node1.example.com:8080 \
  https://node2.example.com:8080 \
  https://node3.example.com:8080

After the command completes, verify gossip convergence with step 6 below. See Admin CLI for full ahdapactl reference.

When nodes start with empty databases each generates its own random 32-byte wrapping key. Nodes with different wrapping keys cannot exchange session cookies. The bootstrap procedure aligns all nodes to a shared key without copying database files or restarting anything.

Step 1 — start all nodes

Start every node before attempting key synchronisation. Wait until each node’s health endpoint responds:

curl -sf https://node1.example.com:8080/api/auth/info >/dev/null && echo ready

Step 2 — generate a shared wrapping key

Generate 32 cryptographically random bytes and base64url-encode them (no padding). python3 is available on any Linux system without extra dependencies:

CLUSTER_KEY=$(python3 -c "
import secrets, base64
print(base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b'=').decode())
")

Keep this value in a shell variable for the remainder of the provisioning session. Do not write it to disk or log it — it is the root secret for the cluster.

Step 3 — log in to every node before rotating any key

Session cookies are AEAD-sealed with each node’s current wrapping key. Rotating the key immediately invalidates all cookies issued under the previous key. Log in to all nodes before pushing the new key to any of them:

# Obtain one session cookie per node.
curl -c /tmp/n1.cookie -sf -X POST https://node1.example.com:8080/api/auth/login \
     -H 'Content-Type: application/json' \
     -d '{"username":"admin","password":"..."}'

curl -c /tmp/n2.cookie -sf -X POST https://node2.example.com:8080/api/auth/login \
     -H 'Content-Type: application/json' \
     -d '{"username":"admin","password":"..."}'

curl -c /tmp/n3.cookie -sf -X POST https://node3.example.com:8080/api/auth/login \
     -H 'Content-Type: application/json' \
     -d '{"username":"admin","password":"..."}'

Step 4 — push the shared key to every node

Use each node’s own pre-rotation cookie. The PUT /api/admin/keys/cluster endpoint requires keys:rotate permission and takes effect immediately — no restart needed:

for i in 1 2 3; do
  curl -sf -b "/tmp/n${i}.cookie" \
       -X PUT "https://node${i}.example.com:8080/api/admin/keys/cluster" \
       -H 'Content-Type: application/json' \
       -d "{\"key\":\"$CLUSTER_KEY\"}"
  echo "node${i}: key set"
done

Step 5 — re-authenticate to obtain a cross-node cookie

After the key rotation, log in to any one node to get a fresh cookie sealed under the shared key. This cookie is accepted by every node in the cluster:

curl -c /tmp/admin.cookie -sf \
     -X POST https://node1.example.com:8080/api/auth/login \
     -H 'Content-Type: application/json' \
     -d '{"username":"admin","password":"..."}'

Clean up the per-node bootstrap cookies:

rm /tmp/n1.cookie /tmp/n2.cookie /tmp/n3.cookie

Step 6 — verify gossip convergence

You can inspect the gossip health of any node at any time — no authentication required:

curl -sf http://node1.example.com:8080/api/gossip/stats | python3 -m json.tool

The response shows live CRDT counts, the number of successfully completed gossip rounds, the last sync time per peer, and cumulative error counters (persist_errors, wrapping_key_pull_errors). This endpoint is also displayed in the admin web UI on the Cluster Nodes page alongside the list of registered nodes.

Register an OAuth2 client on one node and poll the others until it appears:

# Create on node1.
CLIENT_ID=$(curl -sf -b /tmp/admin.cookie \
  -X POST https://node1.example.com:8080/api/admin/clients \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"test","redirect_uris":[],"scopes":["openid"]}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['client_id'])")

# Poll node2 until it appears (≤ 2 × interval_secs).
until curl -sf -b /tmp/admin.cookie \
      https://node2.example.com:8080/api/admin/clients \
      | python3 -c "import sys,json; [exit(0) for c in json.load(sys.stdin) if c['client_id']=='$CLIENT_ID']; exit(1)" \
      2>/dev/null; do
  sleep 1; echo "waiting..."
done
echo "converged on node2"

Delete the test client when done:

curl -sf -b /tmp/admin.cookie \
     -X DELETE "https://node1.example.com:8080/api/admin/clients/$CLIENT_ID"

Adding a node to an existing cluster

1. Start the new node with an empty database. Let it fully boot.
2. Log in to the new node with its freshly generated key (step 3 pattern above).
3. Push the cluster’s existing shared wrapping key to the new node (step 4 pattern).
4. Make the new node reachable by existing nodes:
   • Static peer list: add the new node’s address to the gossip.peers list on every existing node and restart each process. ahdapa does not reload configuration at runtime; a restart is required to pick up the updated peer list.
   • IPA topology (ipa_topology = true): no configuration change is needed. Once the new IPA replica is added to the replication topology, ahdapa automatically discovers it at the next topology refresh (default: within 5 minutes) and begins gossiping with it.
5. The new node will receive the full cluster state on the first gossip round and converge within interval_secs seconds.

IPA topology discovery

When ahdapa runs on a FreeIPA replica, you can enable automatic peer discovery instead of maintaining a static peers list:

[gossip]
ipa_topology              = true
ipa_topology_interval_secs = 300   # re-query every 5 minutes (default)
interval_secs             = 5

With ipa_topology = true:

• ahdapa queries cn=topology,cn=ipa,cn=etc,<suffix> at startup (before the first gossip round) and every ipa_topology_interval_secs seconds thereafter.
• Peer URLs are constructed as https://<hostname><issuer-path> — for example https://ipa2.example.com/idp when the issuer is https://ipa1.example.com/idp.
• All discovered replica hostnames are automatically added to the gossip admission allowlist (allowed_node_ids), so no manual allowlist configuration is needed.
• After each successful topology fetch, if gssapi.initiator_principal is set, ahdapa calls POST /api/gossip/register-kem on each newly-discovered peer that does not yet have this node’s ML-KEM-768 key. The request is authenticated with a Kerberos AP-REQ for HTTP@<peer_host> using the local machine credential, and includes both the ML-KEM-768 public key and the ECDSA P-256 gossip signing key. This pre-seeds both keys before the first gossip push so that the signing key is pinned and a rogue node cannot claim the allowlisted identity. The gossip layer rejects messages from senders with no pinned signing key, so seeding must complete before gossip can proceed.
• If a topology peer returns HTTP 404 (replica exists in IPA but does not yet run ahdapa), the error is logged at debug level and gossip continues with the next peer.
• Gossip is not disabled when peers is empty, provided ipa_topology = true.

Prerequisite — IPA permission grants

The HTTP service principal must be granted three IPA privileges:

These lookups use the service principal credential directly (no S4U2Self impersonation) because the target attributes are not visible to users reading their own entries.

With Ansible, playbooks/ipa_permissions.yml (part of site.yml) handles all of this in one idempotent run — using ipapermission, ipaprivilege, iparole, and delegation modules from ansible-freeipa — for every principal in the ipa_nodes and ahdapa_standalone inventory groups:

ansible-playbook -i inventory.ini contrib/demo/ipa/ansible/playbooks/ipa_permissions.yml

For manual setups, run once as an IPA admin:

# Custom permission — read user IdP attributes
ipa permission-add "Ahdapa - Read user IdP attributes" \
    --right=read --right=search --right=compare \
    --attrs=ipauserauthtype --attrs=ipaidpconfiglink --attrs=ipaidpsub \
    --type=user

# Topology read privilege
ipa privilege-add "Ahdapa Topology Read" \
    --desc="Allows ahdapa to read IPA replication topology for peer discovery"
ipa privilege-add-permission "Ahdapa Topology Read" \
    --permission="System: Read Topology Segments"

# IdP read privilege
ipa privilege-add "Ahdapa IdP Read" \
    --desc="Allows ahdapa to read IPA IdP configurations and user IdP bindings"
ipa privilege-add-permission "Ahdapa IdP Read" \
    --permissions="Ahdapa - Read user IdP attributes,System: Read External IdP server"

# Role — assign both privileges, add each HTTP service principal
ipa role-add "Ahdapa Services" \
    --desc="Role for ahdapa service accounts"
ipa role-add-privilege "Ahdapa Services" \
    --privileges="Ahdapa Topology Read,Ahdapa IdP Read"
ipa role-add-member "Ahdapa Services" \
    --services="HTTP/ipa.example.com@EXAMPLE.COM"

Replace ipa.example.com@EXAMPLE.COM with the HTTP service principal for each IPA server that runs ahdapa.

389-ds indexes for federated user lookups

ahdapa resolves federated users with an LDAP filter that matches both ipaIdpConfigLink and ipaIdpSub. Without equality indexes on those attributes the filter falls back to a full table scan (visible as notes=U in the 389-ds access log) and adds hundreds of milliseconds to every federated login. Run once per Directory Server instance:

INSTANCE="slapd-EXAMPLE-COM"   # realm, dots replaced with hyphens
dsconf $INSTANCE backend index add --attr ipaIdpConfigLink --index-type eq userRoot
dsconf $INSTANCE backend index add --attr ipaIdpSub        --index-type eq userRoot
dsconf $INSTANCE backend index reindex \
    --attr ipaIdpConfigLink --attr ipaIdpSub --wait userRoot

The Ansible playbook runs these steps automatically when indexes are missing.

Standalone (non-replica) nodes

A standalone node is an IPA-enrolled host that runs ahdapa but is not an IPA replica (no local 389-ds or KDC). Its HTTP service principal must be granted Kerberos constrained delegation (S4U2Proxy) so it can forward impersonated user credentials to the IPA LDAP and HTTP services when performing S4U2Self.

Run once as an IPA admin after enrolling the standalone host:

# Enable S4U2Self on the standalone HTTP principal
ipa service-mod HTTP/ahdapa.example.com@EXAMPLE.COM \
    --ok-to-auth-as-delegate=True

# Delegation target — list each IPA replica's HTTP and LDAP principals
ipa servicedelegationtarget-add ahdapa-delegation-targets
ipa servicedelegationtarget-add-member ahdapa-delegation-targets \
    --principals=HTTP/ipa.example.com@EXAMPLE.COM
ipa servicedelegationtarget-add-member ahdapa-delegation-targets \
    --principals=ldap/ipa.example.com@EXAMPLE.COM
# Repeat the two add-member lines for each additional IPA replica.

# Delegation rule — grant the standalone HTTP principal access to the target
ipa servicedelegationrule-add ahdapa-delegation
ipa servicedelegationrule-add-member ahdapa-delegation \
    --principals=HTTP/ahdapa.example.com@EXAMPLE.COM
ipa servicedelegationrule-add-target ahdapa-delegation \
    --servicedelegationtargets=ahdapa-delegation-targets

With Ansible, add the standalone node to the [ahdapa_standalone] inventory group. ipa_permissions.yml applies the delegation automatically for every host in that group. No ahdapa.toml changes are needed for standalone nodes beyond the standard IPA stanzas; gssproxy is configured with allow_constrained_delegation = true regardless of node type.

Gossip encryption

Each ahdapa node generates three cryptographic key pairs on first start:

• An ML-KEM-768 encryption key pair (post-quantum, FIPS 203). Peer nodes use the public key to encrypt gossip messages so that only this node can read them.
• An ECDSA P-256 signing key pair for gossip authentication. This node uses the private key to sign every gossip message it sends so that peers can verify the message came from this node and has not been tampered with.
• A JWT signing key pair using the algorithm configured by [server] jwt_signing_algorithm (default: ES256 / ECDSA P-256). This node uses the private key to sign JWT access tokens and ID tokens it issues. The private key never leaves the node; only the public key is distributed to peers so they can validate tokens this node issued. If the configured algorithm differs from the algorithm of the stored key, a new key is generated automatically on startup.

The ML-KEM-768 and ECDSA P-256 public keys are automatically distributed to peer nodes through the CRDT gossip mechanism. The JWT signing public key for token validation is likewise gossiped as part of SigningKeyEntry. Once all nodes have exchanged public keys, every gossip message is both encrypted (only the recipient can read it) and signed (the recipient can verify who sent it).

Cross-node token validation: Because every node’s JWT signing public key is available in the CRDT on all peers, any cluster node can cryptographically verify a token issued by any other node. The iss claim check in verify_bearer_jwt (used by /userinfo and /introspect) accepts not only the local [server] issuer but also any issuer URL listed in gossip.peers and any URL discovered via ipa_topology. This means introspecting a token issued by node A on node B succeeds without any session forwarding — the gossiped signing key provides the cryptographic guarantee, and the iss check confirms the token came from a known cluster member.

Key generation is automatic; all private keys are stored in the node’s local database (node_keys table) and are never transmitted over the network. The cluster wrapping key — used to protect session cookies — is CMS-encrypted with the node’s own ML-KEM-768 public key and stored locally; when a new node needs it, it pulls the key on demand from an existing peer via GET /api/gossip/wrapping-key. The response is a full SignedData(EnvelopedData) blob: the serving node signs the response with its gossip ECDSA P-256 key and encrypts it to the requester’s ML-KEM-768 key, so both the sender’s identity and the payload’s integrity are verified before the wrapping key is accepted.

Controlling which nodes can join

To prevent unauthorized nodes from self-registering, set gossip.allowed_node_ids to the explicit list of node identifiers that are permitted to participate:

[gossip]
peers            = ["https://node2.example.com:8080"]
allowed_node_ids = ["node1.example.com", "node2.example.com"]

The node_id is the value of the HOSTNAME environment variable (or the system hostname) at startup. Gossip messages that attempt to register a node_id not in the combined allowlist are silently dropped before merge.

When allowed_node_ids is empty and ipa_topology is false, the combined allowlist is empty and no node can self-register (fail-closed). Enable ipa_topology so that hostnames are discovered automatically, or list allowed_node_ids explicitly.

Bootstrapping a new cluster with CMS gossip

Important: The first gossip exchange between two nodes requires each node to already know the other’s ML-KEM-768 public key. On a completely fresh cluster, neither node knows the other’s key, so the gossip loop skips peers it has no KEM key for and waits.

IPA-integrated deployments (recommended): When ipa_topology = true and gssapi.initiator_principal is set, the topology refresh task automatically seeds each peer’s ML-KEM-768 key and ECDSA P-256 gossip signing key via POST /api/gossip/register-kem using the node’s Kerberos machine credential (HTTP/<hostname>@<REALM>). This happens before the first gossip round, so all IPA-enrolled nodes have pinned signing keys and known KEM keys without any manual intervention. No database copying or manual key seeding is needed.

Static-peer deployments: Use one of the following procedures:

1. Start Node A. Its public keys are registered in its own CRDT.

2. Copy Node A’s database to Node B before starting Node B (or start Node A first and let it run a few seconds, then start Node B). Node B will contain A’s NodeEntry and vice versa after the first successful merge.

3. Alternatively, fetch each node’s KEM key via GET /api/gossip/kem-info and seed it on all peers via POST /api/admin/nodes/seed (requires keys:rotate permission):

   # Fetch node A's KEM key.
   KEM_KEY=$(curl -sf https://nodeA.example.com:8080/api/gossip/kem-info \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['kem_public_key_der'])")
   
   # Seed it into node B.
   curl -sf -b /tmp/nb.cookie \
     -X POST https://nodeB.example.com:8080/api/admin/nodes/seed \
     -H 'Content-Type: application/json' \
     -d "{\"node_id\":\"nodeA\",\"kem_public_key_der\":\"$KEM_KEY\"}"
   

   Or with ahdapactl: ahdapactl cluster nodes seed --node-id nodeA --kem-key <base64url>

Once the first successful gossip exchange occurs, nodes learn each other’s KEM keys and all subsequent exchanges are encrypted automatically. The cluster wrapping key is re-sealed for the updated recipient set within one gossip cycle.

Joining a new node

IPA-integrated deployments: No manual key seeding is required. Once the new IPA replica appears in the replication topology, the topology refresh task on each existing node automatically discovers it, calls POST /api/gossip/register-kem to seed the new node’s ML-KEM-768 key and gossip signing key (authenticated with the existing node’s Kerberos machine credential), and begins gossiping with it. Similarly, the new node seeds its keys on all existing peers after its first topology refresh. The new node pulls the cluster wrapping key on the first successful gossip exchange.

Static-peer deployments:

1. Start the new node — its ML-KEM-768 key pair is generated automatically.
2. Add it to allowed_node_ids on all existing nodes (if configured).
3. Add the new node’s address to gossip.peers on all existing nodes and reload.
4. Within two gossip cycles (default 10 s), existing nodes learn the new node’s KEM key. The new node detects the cluster’s wrapping_key_id via gossip and pulls the actual wrapping key from a peer via GET /api/gossip/wrapping-key. It can then unseal session cookies from other nodes once the pull completes.

Automatic KEM re-registration after peer restart

When a peer restarts and loses its CRDT state (e.g. after a database wipe or a fresh reinstall), its KEM key and gossip signing key are gone. Subsequent gossip pushes from existing nodes are rejected with 401 Unauthorized because the peer no longer recognises their signing keys.

The gossip loop detects this automatically: a 401 response from a peer triggers an immediate call to POST /api/gossip/register-kem on that peer, seeding this node’s ML-KEM-768 public key and ECDSA P-256 gossip signing key. Re-registration is throttled to at most once per 60 seconds per peer so that a persistently-rejecting peer does not cause excessive Kerberos ticket acquisition. Once re-registration succeeds, gossip resumes automatically on the next round.

This recovery is fully automatic in IPA-integrated deployments where gssapi.initiator_principal is set. In static-peer deployments without a machine credential, the 401 is logged as a warning and the gossip push to that peer is skipped until the peer is manually re-seeded (see Bootstrapping a new cluster).

Removing a node

1. Remove the node from gossip.peers on all remaining nodes.
2. Remove it from allowed_node_ids if configured.
3. Rotate the cluster wrapping key via PUT /api/admin/keys/cluster (or ahdapactl cluster key rotate) — the removed node’s KEM key is no longer included in future re-seals, so it loses access to the wrapping key after rotation.

The removed node’s CRDT entry (signing key, KEM key, etc.) remains visible in GET /api/admin/nodes until it ages out past gossip.tombstone_ttl_secs. This is harmless: with the node absent from every peer list and the wrapping key rotated, it cannot participate in or decrypt cluster traffic.

Security considerations

Gossip and internal endpoint access control

POST /api/gossip/sync, GET /api/gossip/wrapping-key, and the internal forwarding endpoints (/api/internal/token/auth-code, /api/internal/quorum/vote) are served on the same port as the public OAuth2 endpoints — port-level firewall rules cannot isolate them without also blocking public OAuth2 clients. Access is enforced at the application layer by two complementary mechanisms:

Cryptographic authentication (primary)

Every gossip sync payload is a CMS SignedData(EnvelopedData) structure. The receiver verifies the ECDSA P-256 outer signature against the sender’s pinned gossip signing key. A sender whose key is not registered in the CRDT is rejected with 401 Unauthorized before any payload is read or applied. The ML-KEM-768 inner encryption additionally ensures the payload is opaque to any party that does not hold the addressed node’s private key.

Node admission allowlist (secondary)

The allowed_node_ids list and IPA topology discovery together control which node_ids may exchange CRDT state. Gossip messages from unlisted node_ids are dropped at the admission filter after signature verification. The combined allowlist fails closed: an empty union admits nobody.

Proxy-layer path restriction (optional)

If a reverse proxy fronts the cluster, its Location / location block can additionally restrict gossip paths to the cluster subnet as a defence-in-depth measure — see Reverse Proxy Setup for Apache and nginx examples. This is optional: the cryptographic and allowlist controls above already prevent any useful action by an unauthenticated caller.

Protect the wrapping key

The cluster wrapping key is the root of trust for session cookies. Each node stores its own CMS-encrypted copy locally (node_keys.wrapping_key_cms_der); the 32-byte key never appears in gossip payloads.

• If a node is decommissioned, delete it from the cluster. Future key rotations will not serve the wrapping key to its (now-absent) KEM public key, so it loses access.
• If you need to manually rotate the wrapping key, follow the provisioning procedure (steps 3–5): log in to all nodes first, push the new key, then re-authenticate. Peers detect the UUID change via gossip and pull the new key automatically.

TLS for inter-node traffic

Configure TLS on all nodes ([tls] section) and use https:// peer URLs in gossip.peers. TLS encrypts the transport; the CMS envelope encrypts the application payload. Both layers together prevent passive monitoring and active interception. See Configuration Reference.

Running the demo locally

contrib/demo/cluster/run.sh implements all of the above steps against three local nodes on ports 8080–8082 and verifies convergence end-to-end. It is also used as a CI integration test:

contrib/demo/cluster/run.sh            # non-interactive: exits 0 on pass, 1 on fail
contrib/demo/cluster/run.sh --interactive  # keeps nodes running until Ctrl-C

SPIFFE Integration

Ahdapa can act as a SPIFFE trust domain authority and Workload API server. When [spiffe] trust_domain is set in the configuration file, ahdapa:

• Generates or loads an ECDSA P-256 (or P-384) CA for the trust domain.
• Issues X.509-SVIDs and JWT-SVIDs to workloads that connect to the gRPC Workload API Unix socket.
• Publishes the trust bundle (CA cert + JWT signing keys) at GET /.well-known/spiffe-bundle.
• Bridges SPIFFE identity into OAuth2: workloads that present an X.509-SVID in an mTLS connection and whose SPIFFE ID matches a registered OAuth2 client receive an access token.

SPIFFE features are fully optional. When [spiffe] trust_domain is absent, no SPIFFE code paths are activated.

Specification coverage

The table below maps Ahdapa against the SPIFFE implementation feature matrix.

Quick start

Add a [spiffe] section to the configuration file:

[spiffe]
trust_domain     = "example.org"
workload_socket  = "/run/spiffe/workload.sock"
svid_ttl_seconds = 3600
ca_ttl_days      = 365

On first startup ahdapa generates a fresh ECDSA P-256 CA for the trust domain, stores the encrypted private key in the CRDT (so all cluster nodes share one CA), and begins serving the Workload API on the Unix socket.

Workload registration

Before a workload can receive an SVID, a registration entry must exist in the CRDT that matches the workload’s Unix identity. Registration entries are managed via the admin API (/api/admin/spiffe/entries) and the SPIFFE Entries page in the management WebUI. See Admin API — SPIFFE Workload Entries for the full endpoint reference. Each entry contains:

A workload must match all selectors in an entry to receive that entry’s SPIFFE ID.

Selector types

Selectors are stored as JSON objects with a "type" tag and a "value" field. Eleven selector types are supported:

Important notes on remote attestation: When a remote caller uses POST /spiffe/jwt-svid with a hostname field, the server builds an AttestationContext with UID and GID set to u32::MAX sentinel values. This means Uid, Gid, SupplementalGid, and Path selectors will never match remote callers of that endpoint — only Hostname, Hostgroup, ImaHash (if ima_hash is also provided), and NodeId selectors can match via jwt-svid.

When using the ahdapa-spiffe-proxy daemon (see SPIFFE Workload Proxy below), the proxy reads the actual SO_PEERCRED, /proc/<pid>/exe, and /proc/<pid>/status from its own local socket and forwards the real values to POST /spiffe/issue-svid. All eight selector types — including Uid, Gid, SupplementalGid, and Path — can therefore match in the proxy path.

Example entry (JSON body for POST /api/admin/spiffe/entries):

{
  "id":             "550e8400-e29b-41d4-a716-446655440000",
  "spiffe_id":      "spiffe://example.org/workload/myapp",
  "selectors":      [
    "{\"type\":\"Uid\",\"value\":1000}",
    "{\"type\":\"Path\",\"value\":\"/usr/bin/myapp\"}"
  ],
  "node_constraint": null,
  "ttl_seconds":    3600
}

The admin WebUI provides a SelectorBuilder widget that handles the JSON encoding automatically — use it to add selectors by type without writing raw JSON.

Selector JSON examples:

Kubernetes attestation

Ahdapa supports cgroup-based Kubernetes pod attestation with no additional network calls or dependencies. When a workload connects to the Workload API Unix socket from inside a Kubernetes pod, Ahdapa reads /proc/<pid>/cgroup at accept time and parses the pod UID, container ID, and QoS class from the cgroup path.

How it works

Both cgroup v1 and cgroup v2 are supported:

• cgroup v2 — a single line 0::/kubepods[.burstable|.besteffort]/pod<UUID>/<container-id>.
• cgroup v1 — any line whose third : field contains /kubepods.

The following information is extracted from the cgroup path:

On non-Kubernetes nodes the /proc/<pid>/cgroup read succeeds but the path does not match the kubepods pattern; all three Kubernetes selectors are simply left unset and never match. There is no configuration required and no overhead on non-Kubernetes deployments.

Selector examples

A registration entry that matches a specific pod (by UID) and QoS class:

{
  "id":        "550e8400-e29b-41d4-a716-446655440001",
  "spiffe_id": "spiffe://example.org/k8s/my-namespace/my-app",
  "selectors": [
    "{\"type\":\"K8sPodUid\",\"value\":\"550e8400-e29b-41d4-a716-446655440000\"}",
    "{\"type\":\"K8sQosClass\",\"value\":\"burstable\"}"
  ],
  "node_constraint": null,
  "ttl_seconds": 3600
}

A registration entry that matches by container ID (useful when pods are ephemeral and the UID changes on each restart, but a specific container image has a known ID):

{
  "id":        "550e8400-e29b-41d4-a716-446655440002",
  "spiffe_id": "spiffe://example.org/k8s/sidecar",
  "selectors": [
    "{\"type\":\"K8sContainerId\",\"value\":\"abc123def456\"}"
  ],
  "node_constraint": null,
  "ttl_seconds": 3600
}

What is not supported

The following Kubernetes-specific selectors are not yet implemented because they require calling the kubelet API (TLS configuration and network access to the node-local kubelet):

• Pod name
• Pod namespace
• Service account name
• Node name

These are tracked as a follow-up to the current cgroup-based implementation.

OIDC Federation

When [spiffe] oidc_issuer is set, Ahdapa exposes two OIDC endpoints that allow external OIDC-aware systems to discover and verify JWT-SVIDs:

[spiffe]
trust_domain = "example.org"
oidc_issuer  = "https://spiffe.example.org"

The issuer field in the discovery document is set to the configured oidc_issuer URL. The jwks_uri points to <server-issuer>/spiffe/oidc/jwks, where <server-issuer> is [server] issuer in the Ahdapa configuration.

For strict SPIFFE OIDC Federation compliance (where the discovery document must be at https://<trust-domain>/.well-known/openid-configuration), set up a reverse proxy or DNS alias so that https://spiffe.example.org/.well-known/openid-configuration redirects to the Ahdapa node.

Algorithm note: ML-DSA signing keys are excluded from the OIDC JWKS because the SPIFFE JWT-SVID specification only permits RS256/384/512, PS256/384/512, and ES256/384/512. The OIDC JWKS endpoint deliberately matches the SPIFFE allowlist so that JWT-SVIDs validated via OIDC Discovery behave identically to those validated via the Workload API.

SPIFFE Federation

SPIFFE Federation allows workloads in one trust domain to authenticate to workloads in another trust domain by sharing trust bundle material via signed bundle endpoints.

Configuring a federation relationship

Use the admin API to register a foreign trust domain’s bundle endpoint:

# https_web profile (WebPKI TLS — the endpoint's certificate is validated
# against the system trust roots or a configured CA bundle).
curl -s -X POST https://idp.example.org/api/admin/spiffe/federation \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trust_domain": "partner.example.com",
    "bundle_endpoint_url": "https://partner.example.com/spiffe-bundle",
    "bundle_endpoint_profile": "https_web"
  }'

# https_spiffe profile (the endpoint server presents an X.509-SVID;
# its SPIFFE ID must match endpoint_spiffe_id and its cert must chain
# to the cached foreign bundle — bootstrapped via https_web first).
curl -s -X POST https://idp.example.org/api/admin/spiffe/federation \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trust_domain": "partner.example.com",
    "bundle_endpoint_url": "https://partner.example.com/spiffe-bundle",
    "bundle_endpoint_profile": "https_spiffe",
    "endpoint_spiffe_id": "spiffe://partner.example.com/bundle-endpoint"
  }'

Refreshing a foreign bundle

After registering the relationship, import the foreign bundle:

# Fetch the bundle manually and import it via the admin API.
BUNDLE_JSON=$(curl -s https://partner.example.com/spiffe-bundle)
curl -s -X POST https://idp.example.org/api/admin/spiffe/federation/partner.example.com/bundle \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$BUNDLE_JSON"

Note: Automatic periodic bundle refresh (background polling) is not yet implemented. Until that feature lands, bundle refresh must be triggered manually via the admin API or via a cron job / CI pipeline.

Listing and deleting relationships

# List all configured federation relationships.
curl -s https://idp.example.org/api/admin/spiffe/federation \
  -H "Authorization: Bearer $TOKEN"

# Delete a relationship (the cached bundle is not automatically evicted).
curl -s -X DELETE https://idp.example.org/api/admin/spiffe/federation/partner.example.com \
  -H "Authorization: Bearer $TOKEN"

Workload API behaviour

Once a foreign bundle is cached, the SPIFFE Workload API includes it in all bundle responses:

• FetchX509SVIDResponse.federated_bundles — concatenated X.509 CA cert DER bytes per trust domain.
• FetchX509BundlesResponse.bundles — same as above, plus the local trust domain.
• FetchJWTBundlesResponse.bundles — raw JWK Set JSON bytes per trust domain.

Foreign bundles are CRDT-gossiped across cluster nodes so any node can serve them without contacting the remote endpoint directly.

Workload API (gRPC)

The Workload API is a gRPC service on the Unix domain socket configured by [spiffe] workload_socket. All RPC calls must carry the metadata header:

workload.spiffe.io: true

Calls that omit this header are rejected with PermissionDenied.

Caller attestation uses SO_PEERCRED on the Unix socket to obtain the caller’s UID, GID, and PID. The kernel-returned ucred struct length is verified to equal sizeof(ucred); a truncated response denies attestation (uid/gid are set to u32::MAX so no selector will match). At accept time the server also:

• Reads /proc/<pid>/exe to resolve the executable path.
• Reads /proc/<pid>/status to collect the supplemental group ID list (Groups: line).
• Reads /proc/<pid>/cgroup to extract Kubernetes pod identity (pod UID, container ID, QoS class).
• Computes SHA-256, SHA-512, and SHA-1 hashes of the executable binary (capped at 256 MB).
• Injects the node’s hostname (from /proc/sys/kernel/hostname at service init) into the context.

All eleven selector types are evaluated against this full AttestationContext.

JWT-SVID signing key: JWT-SVIDs are signed with the node’s active OAuth2 JWT signing key (same key used for OAuth2 access tokens), loaded from the shared cluster signing key store. The key is included in the trust bundle returned by FetchJWTBundles and GET /.well-known/spiffe-bundle. ML-DSA keys are excluded from the JWT-SVID bundle because the SPIFFE JWT-SVID specification only permits RS/PS/ES algorithms.

Trust bundle endpoint

GET /.well-known/spiffe-bundle

Returns an application/json JWK Set containing:

• The CA certificate as an x509-svid key (DER-encoded, base64url in x5c).
• Each active non-ML-DSA JWT signing key as a jwt-svid key.
• spiffe_sequence — monotonically increasing counter; consumers can detect bundle updates by comparing this value.
• spiffe_refresh_hint — suggested polling interval in seconds (configured by [spiffe] bundle_refresh_hint, default 300).

This endpoint is public and requires no authentication. The bundle is also served at /spiffe/bundle (same handler, both paths are active).

CA key management

The SPIFFE CA key is stored encrypted (AES-256-GCM, using the cluster wrapping key) in the CRDT and gossiped to all cluster nodes. Key loading follows this priority order:

1. CRDT contains an encrypted blob → decrypt and use.
2. ca_key_file starts with pkcs11: → load from HSM; cert loaded from ca_cert_file. The HSM-backed key is not stored in the CRDT.
3. ca_key_file and ca_cert_file are both set → load PEM files; encrypt the private key and gossip via CRDT.
4. Nothing found → generate a new ECDSA CA (algorithm from ca_algorithm); encrypt and gossip the key.

OAuth2 bridge

To issue OAuth2 access tokens to a workload that authenticates with its X.509-SVID, register an OAuth2 client and set its spiffe_id field to the workload’s SPIFFE ID:

POST /api/admin/clients
Content-Type: application/json

{
  "client_name":               "myapp",
  "token_endpoint_auth_method": "tls_client_auth",
  "tls_client_certificate":    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "spiffe_id":                 "spiffe://example.org/workload/myapp",
  "scopes":                    ["openid"]
}

When a workload presents its X.509-SVID in an mTLS connection and the SPIFFE URI SAN in the certificate matches the spiffe_id of a registered client, ahdapa issues an OAuth2 access token for that client. The certificate chain is also structurally verified against the SPIFFE CA before the SPIFFE ID is trusted.

OAuth2 token → JWT-SVID (reverse bridge)

A client that already holds a valid OAuth2 access token can exchange it for one or more JWT-SVIDs by calling POST /spiffe/jwt-svid.

Simple exchange (client SPIFFE ID)

When the request body contains only an audience, the server issues a single JWT-SVID using the spiffe_id registered on the OAuth2 client:

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

{"audience": ["https://target-service.example.org"]}

audience is optional and defaults to the server issuer URL. Returns 403 if the client has no spiffe_id registered.

Remote attestation exchange (hostname-based)

For workloads that cannot connect to the Unix socket directly (e.g. remote machines or containerised services), the exchange endpoint supports selector-based remote attestation. Include hostname (and optionally ima_hash) in the request body:

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

When hostname is provided, the server:

1. Looks up IPA host group memberships for the declared hostname via LDAP (server-verified — the caller cannot fake this step).
2. Builds an AttestationContext with the hostname, host groups, and (if supplied) the ima_hash. UID and GID are set to u32::MAX sentinel values so that Uid, Gid, SupplementalGid, and Path selectors never match remote callers.
3. Runs the full selector matching against all live RegistrationEntrys.
4. Issues one JWT-SVID per matching entry’s SPIFFE ID.
5. Falls back to the client’s registered spiffe_id if no entries match and the client has one set.
6. Returns 403 if neither path yields a SPIFFE ID.

The response always contains a svids array (one element per matched SPIFFE ID) and the current trust bundle:

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

See Protocol Endpoints — SPIFFE JWT-SVID Exchange for the full request/response reference.

Socket permissions

The workload_socket_mode key controls the Unix permission bits on the Workload API socket (expressed as a decimal integer). Common values:

The socket is created by the ahdapa process user. Workload processes must have read-write access to the socket file to call the Workload API. In production, set the socket file’s group to a shared group containing both the ahdapa service user and the workload users, and use workload_socket_mode = 432 (0o660).

Multi-node clusters

In a multi-node cluster the SPIFFE CA key is shared via the CRDT gossip protocol. All nodes present the same CA certificate, so X.509-SVIDs issued by any node are verifiable by any other node and by external workloads that trust the CA.

When using an HSM-backed CA key (ca_key_file = "pkcs11:..."), the private key never leaves the HSM and is not gossiped. Each node must have local access to the HSM and to the CA cert file (ca_cert_file).

Demo

A self-contained demo is included at contrib/demo/spiffe/. Run it with:

contrib/demo/spiffe/run.sh

The script generates a TLS PKI, pre-seeds a registration entry for the current user’s UID, starts a single-node ahdapa instance, bootstraps an admin account, and runs workload_client.py — a Python gRPC client that exercises all four Workload API RPCs (FetchX509SVID, FetchJWTSVID, FetchX509Bundles, FetchJWTBundles).

SPIFFE Workload Proxy

ahdapa-spiffe-proxy is a standalone daemon for IPA-enrolled hosts that do not run an Ahdapa instance of their own. It presents a full SPIFFE Workload API gRPC endpoint on a local Unix socket and forwards SVID requests to a remote Ahdapa node using the host’s Kerberos credentials.

When to use the proxy

Use the proxy when workloads on a non-Ahdapa host need SPIFFE identities but you cannot or do not want to run a full Ahdapa cluster node on that host. Typical scenarios:

• Application servers or batch hosts enrolled in IPA but not running Ahdapa.
• Containers where the host’s keytab is available but Ahdapa is not installed.
• Environments where a single central Ahdapa cluster serves multiple hosts.

How it works

1. At startup the proxy reads its configuration from /etc/ahdapa/spiffe-proxy.toml (overridable with a positional CLI argument).
2. If credential = "keytab", the proxy calls into libgssapi (equivalent to kinit -k -t <keytab> <principal>) to obtain a Kerberos TGT stored in a private in-memory ccache. If credential = "ccache", it uses the default ccache maintained externally (e.g. by SSSD or a systemd credential).
3. It exchanges a SPNEGO token for an OAuth2 bearer token by posting grant_type=client_credentials to <ahdapa_url>/token with Authorization: Negotiate <base64-SPNEGO>. This is the same kerberos_client_auth flow that SSSD uses for the identity API.
4. The bearer token is cached and refreshed proactively in the background at 75% of its expires_in lifetime.
5. The proxy serves all five SPIFFE Workload API RPCs on the configured Unix socket:
   • FetchJWTSVID — reads SO_PEERCRED from the local socket, reads /proc/<pid>/exe and /proc/<pid>/status, and forwards the real workload identity to Ahdapa via POST /spiffe/issue-svid. Returns the JWT-SVIDs from the response.
   • FetchX509SVID — additionally generates an ephemeral EC keypair locally (algorithm from x509_key_algorithm), sends only the SPKI DER to Ahdapa, receives the signed X.509-SVID certificate chain back, and assembles the X509SVID message with the local private key. The private key never leaves the proxy host.
   • FetchJWTBundles and FetchX509Bundles — fetch from GET /spiffe/spiffe-bundle every 300 seconds and stream updates to connected clients.
   • ValidateJWTSVID — fetches the bundle and validates the JWT locally.

Ahdapa server-side setup

On the Ahdapa node, the proxy host’s OAuth2 client must be registered with kerberos_client_auth and its service principal must appear in [spiffe] accepted_proxies.

POST /api/admin/clients
Content-Type: application/json

{
  "client_name":               "proxy-myhost.ipa.example.com",
  "token_endpoint_auth_method": "kerberos_client_auth",
  "kerberos_principal":        "host/myhost.ipa.example.com@IPA.REALM"
}

The default accepted_proxies = ["host", "HTTP"] accepts both host/myhost@REALM and HTTP/myhost@REALM principals. To restrict proxy access to a specific set of principals, list only the service components you trust:

[spiffe]
trust_domain     = "example.org"
accepted_proxies = ["host"]   # only host/ principals; not HTTP/

Set accepted_proxies = [] to disable the POST /spiffe/issue-svid endpoint entirely.

Proxy configuration file

The proxy reads /etc/ahdapa/spiffe-proxy.toml at startup.

[proxy]
ahdapa_url          = "https://ahdapa.ipa.example.com/idp"
trust_domain         = "example.org"
workload_socket      = "/run/spiffe/workload.sock"    # default
workload_socket_mode = 432                            # default (0o660)
svid_ttl_seconds     = 3600                           # default
x509_key_algorithm   = "EC-P256"                     # default

[kerberos]
credential     = "keytab"                             # or "ccache"
keytab         = "/etc/krb5.keytab"
principal      = "host/myhost.ipa.example.com@IPA.REALM"
target_service = "HTTP@ahdapa.ipa.example.com"
client_id      = "host/myhost.ipa.example.com@IPA.REALM"

[tls]
# ca_cert = "/etc/ipa/ca.crt"    # optional; defaults to system trust roots

[proxy] keys

[kerberos] keys

[tls] keys

Keytab access

/etc/krb5.keytab is typically 0600 root:root. The proxy service user (conventionally spiffe-proxy) must be able to read it. The recommended approach is to provision a dedicated keytab file:

ipa-getkeytab -s ipa.example.com -p host/myhost.ipa.example.com \
              -k /etc/ahdapa/spiffe-proxy.keytab
chown root:spiffe-proxy /etc/ahdapa/spiffe-proxy.keytab
chmod 0640 /etc/ahdapa/spiffe-proxy.keytab

Then reference it in the config:

[kerberos]
credential = "keytab"
keytab     = "/etc/ahdapa/spiffe-proxy.keytab"
principal  = "host/myhost.ipa.example.com@IPA.REALM"

Systemd service

The binary is installed as ahdapa-spiffe-proxy. The recommended systemd unit runs it as a dedicated system user and uses RuntimeDirectory=spiffe to create /run/spiffe/ with appropriate ownership:

[Unit]
Description=SPIFFE Workload API proxy for IPA-enrolled hosts
After=network-online.target

[Service]
Type=simple
User=spiffe-proxy
Group=spiffe-proxy
RuntimeDirectory=spiffe
RuntimeDirectoryMode=0755
ExecStart=/usr/sbin/ahdapa-spiffe-proxy /etc/ahdapa/spiffe-proxy.toml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

See also

• Protocol Endpoints — SPIFFE Proxy SVID Issuance for the full POST /spiffe/issue-svid request/response reference.

Configuration reference

See [spiffe] in the Configuration Reference for all keys and defaults.

Reverse Proxy Setup

ahdapa can run behind a TLS-terminating reverse proxy. The proxy handles HTTPS towards clients; ahdapa listens on a plain HTTP port reachable only from the proxy.

This page covers Apache httpd and nginx. Other proxies (HAProxy, Caddy) follow the same principles.

ahdapa configuration

Regardless of which proxy you use, configure ahdapa as follows:

Set issuer to the public HTTPS URL — it appears in the OIDC discovery document and in JWT iss claims. Set listen to a loopback address or Unix socket that the proxy can reach. Do not add a [tls] section; the proxy terminates TLS so ahdapa does not need to.

[server]
issuer = "https://idp.example.com"
listen = "127.0.0.1:8080"          # reachable only from the proxy

[db]
url = "sqlite:///var/lib/ahdapa/ahdapa.db"

# No [tls] section — TLS is terminated by the proxy.

Using a Unix domain socket instead of a TCP port is also supported:

[server]
issuer = "https://idp.example.com"
listen = "unix:/run/ahdapa/ahdapa.sock"

Point the proxy’s ProxyPass / proxy_pass at unix:/run/ahdapa/ahdapa.sock|http://localhost/ (Apache) or http://unix:/run/ahdapa/ahdapa.sock (nginx) instead of http://127.0.0.1:8080.

Apache httpd

Required modules

The following modules must be loaded. On Fedora and RHEL they are included in the httpd and mod_ssl packages; the LoadModule lines are present in the default configuration under /etc/httpd/conf.modules.d/.

mod_proxy        – reverse proxy core
mod_proxy_http   – HTTP backend support
mod_headers      – RequestHeader / Header directives
mod_remoteip     – rewrite REMOTE_ADDR from X-Forwarded-For
mod_ssl          – TLS for the public-facing listener

Install if not already present:

dnf install httpd mod_ssl

Virtual host

Place this file at /etc/httpd/conf.d/ahdapa.conf:

# Redirect plain HTTP to HTTPS.
<VirtualHost *:80>
    ServerName idp.example.com
    Redirect permanent / https://idp.example.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName idp.example.com

    # TLS certificate — replace with your actual paths.
    SSLEngine on
    SSLCertificateFile    /etc/pki/tls/certs/idp.example.com.crt
    SSLCertificateKeyFile /etc/pki/tls/private/idp.example.com.key
    SSLProtocol           TLSv1.2 TLSv1.3
    SSLCipherSuite        ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:!aNULL

    # Rewrite REMOTE_ADDR so ahdapa's access log shows real client IPs.
    RemoteIPHeader X-Forwarded-For

    # Forward requests to ahdapa.
    ProxyPreserveHost On
    ProxyPass        / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/

    # Inform ahdapa that the client connection is HTTPS.
    # ahdapa uses this to set the Secure flag on session cookies.
    RequestHeader set X-Forwarded-Proto "https"

    # Optional: restrict gossip paths to cluster peers at the proxy layer.
    # Gossip endpoints are protected by CMS authentication (ECDSA P-256 +
    # ML-KEM-768) and the allowed_node_ids allowlist, so this block provides
    # defence-in-depth only.  Remove it if gossip traffic reaches the nodes
    # directly rather than through this vhost.
    <Location /api/gossip>
        Require ip 192.168.0.0/24   # replace with your cluster subnet
    </Location>
</VirtualHost>

After editing, reload Apache:

apachectl configtest && systemctl reload httpd

nginx

Installation

dnf install nginx

Server block

Place this file at /etc/nginx/conf.d/ahdapa.conf:

# Redirect plain HTTP to HTTPS.
server {
    listen      80;
    listen      [::]:80;
    server_name idp.example.com;
    return      301 https://$host$request_uri;
}

server {
    listen      443 ssl;
    listen      [::]:443 ssl;
    server_name idp.example.com;

    # TLS certificate — replace with your actual paths.
    ssl_certificate     /etc/pki/tls/certs/idp.example.com.crt;
    ssl_certificate_key /etc/pki/tls/private/idp.example.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:!aNULL;

    # Pass real client IP to ahdapa's access log.
    real_ip_header    X-Forwarded-For;
    set_real_ip_from  127.0.0.1;        # trust the loopback address
    # set_real_ip_from 192.168.0.0/24;  # add if nginx itself is behind a load balancer

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Increase timeouts for long-polling endpoints (token introspection,
        # device flow polling).  The defaults (60 s) are usually sufficient.
        proxy_read_timeout 120s;
    }

    # Optional: restrict gossip paths to cluster peers at the proxy layer.
    # Gossip endpoints are protected by CMS authentication (ECDSA P-256 +
    # ML-KEM-768) and the allowed_node_ids allowlist, so this block provides
    # defence-in-depth only.  Remove it if gossip traffic reaches the nodes
    # directly rather than through this server block.
    location /api/gossip {
        allow   192.168.0.0/24;   # replace with your cluster subnet
        deny    all;

        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

After editing, reload nginx:

nginx -t && systemctl reload nginx

Interaction notes

These notes apply to both Apache and nginx.

Security headers

ahdapa emits Strict-Transport-Security, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Content-Security-Policy on every response. The headers are set with if_not_present semantics: a value already present in the response from the proxy wins. You can therefore override individual headers in the proxy config without modifying ahdapa.

The Content-Security-Policy header includes frame-ancestors 'none' (RFC 9700 §4.16), which prevents ahdapa pages from being embedded in frames or iframes on any origin.

Referrer-Policy: no-referrer is applied specifically to the /authorize endpoint (RFC 9700 §4.2.4) in addition to the global Referrer-Policy response header. This prevents OAuth parameters in the authorization URL (such as state and code_challenge) from leaking to any resource loaded during the auth flow.

Kerberos / SPNEGO

SPNEGO authentication works unchanged through both proxies. The Authorization: Negotiate … header is forwarded to ahdapa unmodified. Do not strip or rewrite the Authorization header in the proxy config.

RFC 5929 TLS channel binding

tls-server-end-point channel binding (RFC 5929) ties authentication to the TLS session between the client and the server. Behind a TLS-terminating proxy, ahdapa sees only a plain-text connection from the proxy and cannot observe the client’s TLS session, so channel binding is not available in this topology. This is a known limitation of TLS termination at the proxy layer.

Gossip topology

The recommended layout is to have gossip peers communicate directly on an internal network interface rather than through the public proxy vhost:

# node1.toml — gossip uses internal addresses, not the public hostname
[gossip]
peers = ["https://192.168.0.2:8080", "https://192.168.0.3:8080"]

This avoids routing intra-cluster traffic through the public-facing TLS terminator while still keeping gossip on HTTPS end-to-end. Configure gossip.ca_cert if the nodes present certificates signed by an internal CA rather than a public one.

If your network topology requires gossip to traverse the public proxy (for example, nodes in different data centres with no shared private network), point the peers at the public HTTPS URLs, ensure gossip.ca_cert is set or that the public CA is in the system trust store, and optionally tighten the proxy-layer <Location> / location ACL to the specific peer IP addresses.

FreeIPA Co-deployment

Ahdapa can run directly on an IPA server, sharing the existing Apache httpd instance that already serves /ipa (the IPA web API) and /ca, /kra, /acme (Dogtag PKI). The pattern follows the same drop-in conf.d model IPA uses for Dogtag: one extra Apache config file, one gssproxy entry, one ahdapa TOML file.

The resulting deployment serves ahdapa at https://<ipa-fqdn>/idp/.

How it fits together

graph TD
    B["Browser / OAuth2 client"]

    subgraph httpd["Apache httpd (IPA-managed) — HTTPS :443"]
        R1["/ipa/* → mod_wsgi (IPA API)"]
        R2["/ca/* → AJP → Dogtag"]
        R3["/idp/* → mod_proxy → ahdapa"]
    end

    E["ahdapa process<br/>(plain HTTP, Unix socket)"]

    DS["IPA Directory Server<br/>(slapd — ldapi://)"]
    KDC["KDC<br/>(GSSAPI / SPNEGO)"]

    B -->|"HTTPS :443"| httpd
    R3 -->|"Unix socket"| E
    E -->|"GSSAPI SASL<br/>(service cred / S4U2Self)"| DS
    E -->|"SPNEGO acceptor<br/>S4U2Self initiator"| KDC

Ahdapa handles its own Kerberos SPNEGO, password, OTP, and passkey authentication internally — Apache does not apply mod_auth_gssapi to the /idp path. TLS is terminated by Apache; ahdapa runs over plain HTTP on the Unix socket.

For LDAP attribute lookups, OTP token management, and passkey writes, ahdapa connects to the local Directory Server socket and authenticates via GSSAPI SASL — the same mechanism IPA tools use, with no special group membership required.

Two distinct LDAP credential modes are used:

• Service principal credential — used for all pre-authentication lookups (e.g. GET /api/auth/federated-hint, the ipauserauthtype gate at the start of every token flow). The HTTP service principal binds directly to LDAP without impersonating the user. This is required because FreeIPA LDAP ACLs prevent users from reading their own ipaidpconfiglink and related IdP attributes.
• S4U2Self — used for post-authentication operations (OTP token management, passkey writes, profile attribute lookups) where the request is scoped to an already-authenticated user. S4U2Self impersonation ensures that FreeIPA’s standard self-service ACIs apply and that the audit trail reflects the user, not the service.

Prerequisites

• FreeIPA is installed and the IPA server is running.
• mod_proxy and mod_proxy_http are loaded (they are standard on Fedora / RHEL).
• The ahdapa package is installed (/usr/bin/ahdapa, /usr/share/ahdapa/webui/).
• The ahdapa system user exists (useradd -r -s /sbin/nologin ahdapa).

Runtime directory — /run/ahdapa/ is created automatically by systemd-tmpfiles from ahdapa-tmpfiles.conf (mode 2750, owner ahdapa, group apache). The setgid bit causes the Unix socket created inside to inherit group apache; combined with UMask=0117 in the service unit, the socket ends up ahdapa:apache 0660 so Apache mod_proxy can connect without any explicit group membership changes.

Automated deployment with Ansible

For deployments that manage a full FreeIPA cluster, the Ansible playbooks under contrib/demo/ipa/ansible/ automate every step described in this page across all IPA nodes simultaneously.

# 1. Copy and edit the inventory.
cp contrib/demo/ipa/ansible/inventory.ini.example inventory.ini
$EDITOR inventory.ini   # set hostnames, ipa_domain, ipa_realm, passwords

# 2. Run the full site playbook.
ansible-playbook -i inventory.ini contrib/demo/ipa/ansible/site.yml

The site.yml entry point runs four phases in order:

After site.yml completes, ahdapa is running on every IPA node, the gossip layer discovers peers automatically via IPA replication topology, and Kerberos self-registration seeds each node’s ML-KEM-768 key on its peers before the first gossip round — no manual bootstrap is needed. See contrib/demo/ipa/ansible/README.md for inventory variables, vault encryption, and troubleshooting guidance.

The manual steps below remain accurate for single-node or non-Ansible deployments.

Files to install

Step-by-step setup

1. Install the gssproxy drop-in

IPA manages the HTTP service keytab at /var/lib/ipa/gssproxy/http.keytab through gssproxy (/etc/gssproxy/10-ipa.conf). Ahdapa reuses the same keytab via its own gssproxy service entry; no separate keytab extraction is needed.

cp contrib/demo/ipa/ahdapa-gssproxy.conf /etc/gssproxy/20-ahdapa.conf
chmod 0600 /etc/gssproxy/20-ahdapa.conf
systemctl restart gssproxy

The drop-in grants the ahdapa process:

• allow_protocol_transition = true — S4U2Self: obtain a Kerberos credential on behalf of an authenticated user for LDAP lookups and OTP/passkey self-service.
• allow_constrained_delegation = true — S4U2Proxy: forward that credential to the IPA LDAP service under constrained delegation.
• cred_usage = both — accept Kerberos service tickets from browsers (SPNEGO) and initiate credentials for S4U2Self.

2. Edit ahdapa.toml

Replace the placeholder strings throughout the sample config file:

The ldapi:// URI uses percent-encoded slashes in the socket path. Read the canonical value from /etc/ipa/default.conf (ldap_uri key), which already contains the correctly encoded URI for the local server. For realm IPA.TEST the encoded URI is ldapi://%2Fvar%2Frun%2Fdirsrv%2Fslapd-IPA-TEST.socket.

Install the config:

install -o root -g ahdapa -m 0640 \
    contrib/demo/ipa/ahdapa.toml /etc/ahdapa/ahdapa.toml

3. Install the Apache config

cp contrib/demo/ipa/ipa-idp-proxy.conf /etc/httpd/conf.d/ipa-idp-proxy.conf
apachectl configtest && systemctl reload httpd

The Apache config:

• Strips the /idp prefix before forwarding to ahdapa’s Unix socket.
• Rewrites the Path attribute on ahdapa’s session cookie from / to /idp/ so it does not collide with the ipa_session cookie at /ipa.
• Injects X-Forwarded-Proto: https so ahdapa generates correct https:// URIs in OAuth2 responses.
• Redirects HTTP requests for /idp/ to HTTPS using the RewriteEngine that ipa-rewrite.conf already enables.

4. Enable and start ahdapa

systemctl enable --now ahdapa

On first boot ahdapa initialises the database and generates a JWT signing key using the configured algorithm (default: ES256 / ECDSA P-256). Check startup logs:

journalctl -u ahdapa -n 50

Verification

# OIDC discovery document — issuer must end with /idp
curl -s https://ipa.example.com/idp/.well-known/openid-configuration | python3 -m json.tool

# Confirm the IPA web API is unaffected
curl -s https://ipa.example.com/ipa/json | python3 -m json.tool

# HTTP → HTTPS redirect
curl -I http://ipa.example.com/idp/
# Expected: HTTP/1.1 301 Moved Permanently
# Location: https://ipa.example.com/idp/

# WebUI
firefox https://ipa.example.com/idp/ui/

After logging in, open browser DevTools → Application → Cookies and confirm:

• ipa_session has Path: /ipa (IPA’s cookie, unchanged).
• session has Path: /idp (ahdapa’s cookie, scoped by the proxy).

Configuration notes

issuer is optional for IPA co-deployments

When gssapi.initiator_principal is set, [server] issuer is optional. Ahdapa derives it automatically as https://<node-fqdn>/idp where <node-fqdn> is the hostname extracted from the principal — for example, "HTTP/ipa1.ipa.test@IPA.TEST" yields https://ipa1.ipa.test/idp.

For multi-node clusters, set issuer explicitly to the stable ipa-ca.<domain> DNS alias so that all nodes mint tokens with the same iss:

[server]
# Optional when gssapi.initiator_principal is set.
# Derived automatically as https://<node-fqdn>/idp otherwise.
# Set explicitly to the ipa-ca alias for consistent iss across all nodes.
issuer = "https://ipa-ca.ipa.test/idp"

When issuer is absent and gssapi.initiator_principal is not set, Config::load() returns a validation error and ahdapa refuses to start.

Regardless of how issuer is determined, it must include the path prefix (/idp for IPA co-deployments). Every token’s iss claim, every redirect URI, and the OIDC Discovery and OAuth2 Authorisation Server Metadata documents are derived from this value. Clients validate iss against it, so the prefix must be present end-to-end.

ldapi:// uses GSSAPI SASL, not EXTERNAL

Ahdapa connects to the Directory Server via the Unix socket but still authenticates with GSSAPI SASL — the same as connecting over LDAPS. IPA Directory Server accepts GSSAPI SASL binds over ldapi:// without any special configuration or group membership for the ahdapa process user. The ldapi:// URI simply replaces the TCP connection with a Unix socket connection; the authentication layer is identical.

The socket path in the URI must use percent-encoded slashes (%2F). The correctly encoded URI for the local server is in /etc/ipa/default.conf under the ldap_uri key:

grep ldap_uri /etc/ipa/default.conf
# ldap_uri = ldapi://%2Fvar%2Frun%2Fdirsrv%2Fslapd-IPA-TEST.socket

Because the URI starts with ldapi://, ahdapa automatically uses direct LDAP for all attribute lookups, OTP management, and passkey writes (the IPA JSON-RPC API dispatch path is not activated).

gssproxy and the HTTP service principal

IPA’s HTTP/ipa.example.com service principal is shared by several processes:

All three entries in /etc/gssproxy/10-ipa.conf and /etc/gssproxy/20-ahdapa.conf point at the same keytab. Gssproxy authorises each service separately by euid; there is no conflict.

GSS_USE_PROXY is set automatically

When gssproxy = true in [gssapi], ahdapa calls std::env::set_var("GSS_USE_PROXY", "yes") before any GSSAPI operation. This routes all credential acquisition through gssproxy, which is required because the HTTP keytab at /var/lib/ipa/gssproxy/http.keytab is readable only by gssproxy (mode 0600, owner gssproxy), not by the ahdapa process user.

No manual environment variable export is needed in the unit file or shell.

URL prefix from issuer

Ahdapa derives its internal redirect base path from the path component of the issuer URL. With issuer = "https://ipa.example.com/idp" (whether set explicitly or auto-derived), every login redirect, consent page URL, device endpoint, and session cookie path is automatically prefixed with /idp. No additional configuration is required.

Passkey RP ID is derived automatically

FreeIPA derives the WebAuthn Relying Party ID from the Kerberos realm lowercased (e.g. IPA.TEST → ipa.test). Ahdapa applies the same derivation when passkey_rp_id is not set, so for a standard IPA deployment the key can be omitted from [ipa] entirely:

[ipa]
uri = "ldapi://%2Fvar%2Frun%2Fdirsrv%2Fslapd-IPA-TEST.socket"
# passkey_rp_id is not required — derived from [server] realm = "IPA.TEST"

Set passkey_rp_id explicitly only when you need to override the derived value (e.g. "localhost" for local development or "corp.example.com" for a custom domain).

The WebAuthn origin checked during passkey registration and assertion is always scheme://host — no path. Ahdapa strips the path component from the issuer URL automatically, so issuer = "https://ipa.example.com/idp" yields expected origin https://ipa.example.com. No additional configuration is needed.

Multi-node HA

For a high-availability setup with multiple IPA replicas each running ahdapa, you can either list peers manually or use automatic topology-based discovery.

Recommended: IPA topology-based discovery with Kerberos self-registration

Enable ipa_topology and ahdapa will query the IPA replication topology from LDAP and automatically gossip with all directly connected replica peers. No manual peer list is needed, and the peer list stays up to date as replicas are added or removed.

When gssapi.initiator_principal is also set, ahdapa additionally performs Kerberos self-registration after each topology refresh: for every newly-discovered peer that does not yet have this node’s ML-KEM-768 public key, ahdapa calls POST /api/gossip/register-kem on that peer authenticated with a Kerberos AP-REQ for HTTP@<peer_host>. This seeds the KEM key before the first gossip push, eliminating both the TOFU squatting window and the two-round bootstrap delay that static-peer deployments require. No database copying or manual key seeding is needed when bringing up a new replica.

[gossip]
ipa_topology              = true
ipa_topology_interval_secs = 300   # re-query every 5 minutes (default)
interval_secs             = 5

[gssapi]
service              = "HTTP"
gssproxy             = true
initiator_principal  = "HTTP/ipa.example.com@EXAMPLE.COM"
ccache               = "FILE:/run/ahdapa/ahdapa.ccache"

This requires granting the HTTP service principal several IPA permissions. The full set of required privileges is:

These lookups use the service principal credential directly (no S4U2Self impersonation) because the target attributes (ipaidpconfiglink, ipaIdP entries) are not visible to users reading their own entries.

With Ansible (recommended for multi-node deployments), all three privileges are provisioned idempotently by playbooks/ipa_permissions.yml:

ansible-playbook -i inventory.ini contrib/demo/ipa/ansible/playbooks/ipa_permissions.yml

For manual or single-node deployments, run once as an IPA admin (replace the principal name as appropriate):

# Topology privilege
ipa privilege-add "Ahdapa Topology Read" \
    --desc="Allows ahdapa to read IPA replication topology"
ipa privilege-add-permission "Ahdapa Topology Read" \
    --permission="System: Read Topology Segments"

# Custom permission for reading per-user IdP attributes
ipa permission-add "Ahdapa - Read user IdP attributes" \
    --right=read --right=search --right=compare \
    --attrs=ipauserauthtype --attrs=ipaidpconfiglink --attrs=ipaidpsub \
    --type=user

# IdP read privilege (one custom + one built-in permission)
ipa privilege-add "Ahdapa IdP Read" \
    --desc="Allows ahdapa to read IPA IdP configuration and user IdP attributes"
ipa privilege-add-permission "Ahdapa IdP Read" \
    --permission="Ahdapa - Read user IdP attributes"
ipa privilege-add-permission "Ahdapa IdP Read" \
    --permission="System: Read External IdP server"

# Role
ipa role-add "Ahdapa Services" \
    --desc="Role for ahdapa service accounts"
ipa role-add-privilege "Ahdapa Services" \
    --privilege="Ahdapa Topology Read"
ipa role-add-privilege "Ahdapa Services" \
    --privilege="Ahdapa IdP Read"
ipa role-add-member "Ahdapa Services" \
    --services="HTTP/ipa.example.com@EXAMPLE.COM"

389-ds equality indexes (recommended)

The LDAP filter ahdapa uses to resolve federated users is:

(&(objectClass=ipaIdpUser)(ipaIdpConfigLink=<dn>)(ipaIdpSub=<value>))

Without equality indexes on ipaIdpConfigLink and ipaIdpSub, every federated login triggers a full scan of cn=accounts,<suffix>, emitting notes=U in the 389-ds access log and adding hundreds of milliseconds to each login. Add the indexes once on the primary IPA server:

# Replace IPA-EXAMPLE-COM with your realm, dots replaced by dashes.
dsconf slapd-IPA-EXAMPLE-COM backend index add \
    --attr ipaIdpConfigLink --index-type eq userRoot
dsconf slapd-IPA-EXAMPLE-COM backend index add \
    --attr ipaIdpSub --index-type eq userRoot
dsconf slapd-IPA-EXAMPLE-COM backend index reindex \
    --attr ipaIdpConfigLink --attr ipaIdpSub --wait userRoot

The Ansible playbook playbooks/ipa_permissions.yml creates these indexes automatically.

Stable cluster hostname (ipa-ca)

FreeIPA creates a DNS alias ipa-ca.<domain> (e.g. ipa-ca.ipa.test) that resolves (round-robin) to all CA-capable IPA servers. Setting this as the OIDC issuer gives external IdPs a single redirect URI that survives individual node failures.

When gssapi.initiator_principal is configured (the standard IPA co-deployment), the [server] issuer field is optional. When absent, ahdapa derives it from the principal’s hostname (e.g. "HTTP/ipa1.ipa.test@IPA.TEST" → https://ipa1.ipa.test/idp). For multi-node clusters set it explicitly to the stable ipa-ca.<domain> alias so all nodes issue tokens with the same iss value:

[server]
# Recommended for multi-node clusters — all nodes use the same iss.
# When absent, derived from the principal FQDN (node-specific).
issuer = "https://ipa-ca.ipa.test/idp"

Ahdapa also automatically derives two issuer aliases at startup:

1. Node FQDN — extracted from the principal (e.g. HTTP/ipa1.ipa.test@IPA.TEST → https://ipa1.ipa.test/idp).
2. ipa-ca.<domain> — derived from the Kerberos realm lowercased (e.g. IPA.TEST → ipa-ca.ipa.test).

No issuer_aliases entry is needed for IPA deployments. Add issuer_aliases only for additional hostnames beyond these two (e.g. a load-balancer VIP).

Tokens are always minted with iss = https://ipa-ca.ipa.test/idp regardless of which node handles the request. The auto-derived per-node alias is accepted for:

• WebAuthn passkey origin: a user’s browser connecting directly to ipa1.ipa.test sends origin = https://ipa1.ipa.test in the WebAuthn assertion — accepted without error.
• Backchannel logout aud: upstream IdPs that have the alias registered as the RP client URL send aud = https://ipa1.ipa.test/idp in logout notifications — accepted.
• client_assertion JWT aud (RFC 7521): local services configured against the per-node FQDN may put https://ipa1.ipa.test/idp (or /token) in aud — accepted.

Discovery documents served from any alias hostname always advertise the canonical issuer value, so OIDC libraries see a consistent issuer regardless of which node they contacted.

Standalone (non-replica) ahdapa nodes

When ahdapa runs on a host that is not an IPA replica (for example, a dedicated IdP node enrolled in the IPA realm but not running dirsrv / KDC), S4U2Proxy delegation must be set up explicitly. IPA replicas already inherit the necessary delegation via the replica-join process; standalone nodes require the following one-time setup on the IPA server (performed as an IPA admin):

# Enable ok-to-auth-as-delegate on the standalone node's HTTP principal
ipa service-mod HTTP/ahdapa.example.com@EXAMPLE.COM \
    --ok-to-auth-as-delegate=True

# Create a service delegation target that includes the LDAP service
ipa servicedelegationtarget-add ahdapa-standalone-target
ipa servicedelegationtarget-add-member ahdapa-standalone-target \
    --principals=ldap/ipa.example.com@EXAMPLE.COM

# Create a service delegation rule authorising the standalone HTTP principal
ipa servicedelegationrule-add ahdapa-standalone-s4u2proxy
ipa servicedelegationrule-add-member ahdapa-standalone-s4u2proxy \
    --principals=HTTP/ahdapa.example.com@EXAMPLE.COM
ipa servicedelegationrule-add-target ahdapa-standalone-s4u2proxy \
    --servicedelegationtargets=ahdapa-standalone-target

With the Ansible playbooks, add the standalone node to the [ahdapa_standalone] inventory group and re-run playbooks/ipa_permissions.yml; the playbook handles all three steps idempotently for every host in that group.

Alternative: static peer list

If you prefer to manage peers explicitly, add the other nodes to peers using their full /idp URIs:

[gossip]
peers = [
    "https://ipa2.example.com/idp",
    "https://ipa3.example.com/idp",
]

Each node must use the same [db] cluster wrapping key. See Multi-node Cluster for the key synchronisation procedure.

FreeIPA external IdP auto-discovery

When [ipa] gssapi = true, Ahdapa automatically reads all ipaIdP objects from FreeIPA LDAP at startup and refreshes them every 300 seconds, making them available as upstream IdPs without any TOML configuration.

See Federation — FreeIPA auto-discovery for the full description, federated user resolution, and the recommended LDAP indexes.

IPA upstream IdP ACR/AMR overrides

IPA-sourced IdPs often do not return acr or amr claims. Per-IdP defaults can be set via the admin panel and are stored in the CRDT.

See Federation — IPA upstream IdP ACR/AMR overrides for the admin UI and API details.

SSSD id_provider = idp — secretless deployment with kerberos_client_auth

For large-scale SSSD deployments, ahdapa supports a template client registration that lets every FreeIPA-enrolled machine authenticate as an OAuth2 client using its existing Kerberos host keytab (host/hostname@REALM). No per-machine client_secret needs to be generated, distributed, or rotated.

How it works

1. An administrator registers one template OAuth2 client with kerberos_principal_pattern = "host/*@REALM".
2. Each enrolled machine’s SSSD is configured with that single idp_client_id and no idp_client_secret.
3. At token time SSSD presents a Kerberos AP-REQ (the machine’s TGS for the ahdapa HTTP service) in Authorization: Negotiate. Ahdapa verifies the token via SPNEGO, extracts the machine principal, checks it against the glob pattern, and issues a client_credentials access token.

Step-by-step setup

1. Register the template client

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

Note the returned client_id — this is the value machines place in idp_client_id.

The directory.read scope is required for SSSD’s identity lookups via the /api/identity/ endpoints. SSSD performs a two-phase lookup: Phase 1 searches by username or group name; Phase 2 resolves group memberships or group members using the id returned in Phase 1. See Identity API for the full endpoint specification and JSON contract.

2. (Optional) Add HBAC-based access control

Create a FreeIPA HBAC service and rules to restrict which machines may obtain tokens:

ipa hbacsvc-add sssd-idp --desc "SSSD IdP token endpoint access"
ipa hbacrule-add sssd-idp-enrolled \
    --desc "Allow enrolled workstations to get IdP tokens"
ipa hbacrule-add-service sssd-idp-enrolled --hbacsvcs=sssd-idp
# Add individual hosts (hostgroup matching is not yet supported — see known limitation):
ipa hbacrule-add-host sssd-idp-enrolled \
    --hosts=node1.example.com --hosts=node2.example.com

Then update the template client to reference the HBAC service:

curl -s -b session.jar \
  -X PUT -H 'Content-Type: application/json' \
  -d '{
    "kerberos_hbac_service": "sssd-idp"
  }' \
  https://idp.example.com/api/admin/clients/<client_id>

Known limitation: HBAC rules that grant access by hostgroup membership currently evaluate as deny for Kerberos machine principals. Use individual host entries in the HBAC rule until this limitation is resolved. When kerberos_hbac_service is set and the HBAC rule set contains no applicable rules, the server denies all token requests (fail-closed).

3. Deploy sssd.conf — same file on every machine

[domain/example.com]
id_provider = idp
idp_client_id = <template_client_id>
# No idp_client_secret — the machine keytab is used automatically

Token sub for template clients

Access tokens issued to template clients carry the actual machine principal as the sub claim (e.g. host/node1.example.com@EXAMPLE.COM), not the template client_id. This makes individual machines distinguishable in audit logs and token introspection responses even though they share a single client registration.

Discovery advertisement

kerberos_client_auth appears in token_endpoint_auth_methods_supported only when [ipa] gssapi = true. When GSSAPI is disabled, the method is absent from discovery.

Dynamic registration exclusion

POST /register rejects token_endpoint_auth_method = "kerberos_client_auth" with invalid_client_metadata. Kerberos clients must be registered by an administrator via the admin API.

See Kerberos client authentication for full field reference and validation rules.

FreeIPA HBAC rule mirroring

FreeIPA HBAC rules (stored in cn=hbac,<suffix>) can be imported into ahdapa as Identity HBAC policies via the admin API. The conceptual mapping is direct: FreeIPA’s “Who”, “Host”, and “Service” axes correspond to ahdapa’s Identity Subject (users/user groups), Identity Handler (OAuth2 client), and Scoped Access (allowed scopes) respectively.

The LDAP search bases for host and service objects used by the HBAC typeahead lookup endpoints (/api/admin/hbac/lookup/hosts and /api/admin/hbac/lookup/services) are derived automatically from the discovered domain suffix — no configuration keys are needed:

• Hosts: cn=computers,cn=accounts,<suffix>
• Services: cn=services,cn=accounts,<suffix>

See Identity HBAC Policy for a full description of the policy engine, axis semantics, and the admin API.

Remote IPA (ahdapa on a separate host)

When ahdapa runs on a separate host rather than on the IPA server itself, use an LDAPS URI instead of ldapi://:

[ipa]
uri = "ldaps://ipa.example.com"

With a non-ldapi:// URI and a GSSAPI initiator configured, ahdapa automatically switches to the FreeIPA JSON-RPC API (https://ipa.example.com/ipa/session/json) for attribute lookups, OTP token management, and passkey writes. The API session cookie is cached per user (default TTL 1200 s) so the GSSAPI round-trip happens at most once per session rather than on every request.

This mode requires only HTTP/ahdapa-host → HTTP/ipa-host Kerberos constrained delegation; ldap/ipa-host delegation is not needed.

OTP bind verification always uses direct LDAP regardless of the uri scheme, because the OTP_REQUIRED_OID client control is a bind-time mechanism with no JSON-RPC equivalent.

For the reverse proxy, replace the ldapi:// line and use a standalone Apache or nginx vhost as described in Reverse Proxy Setup; the issuer and listen configuration principles are the same.

Identity HBAC Policy

Identity HBAC (Identity Handler-Based Access Control) is a way to restrict which users can obtain tokens from which applications. Think of it as a firewall between your users and your OAuth2 clients: you decide who can log in to what, and what data each application is allowed to receive.

The basic idea

Without any policies, every authenticated user can get a token for any registered client. Once you create at least one policy, Ahdapa starts enforcing rules — a user can only get a token if at least one live policy explicitly allows it.

Policies follow the same mental model as FreeIPA’s HBAC rules for SSH access, extended to the OAuth2 world:

Common use cases

Restrict an application to a specific group

Only members of hr-staff can log in to the HR portal:

Rule: "HR portal access"
  Users: (any)  →  User groups: hr-staff
  Client: hr-portal
  Scopes: openid, email, profile

Lock down a sensitive client to named individuals

Only alice and bob may access the payroll system:

Rule: "Payroll access"
  Users: alice, bob
  Client: payroll-app
  Scopes: openid, email

Require MFA for a privileged client

Finance users need a second factor before getting tokens for the reporting tool:

Rule: "Finance reporting — MFA required"
  User groups: finance-team
  Client: reporting-tool
  MFA bypass: off  (MFA step-up required)
  Scopes: openid, profile, email, groups

Allow any user for a low-sensitivity app, but restrict scopes

All users can use the wiki, but it only receives openid and email — no group membership or POSIX attributes:

Rule: "Wiki — any user, limited scopes"
  Users: any user
  Client: company-wiki
  Scopes: openid, email

Restrict by network

Internal dashboard is only accessible from the corporate network:

Rule: "Internal dashboard — office network only"
  User groups: employees
  Client: internal-dashboard
  Source networks: 10.0.0.0/8, 172.16.0.0/12
  Scopes: openid, profile, groups

Control OBO delegation targets

A pipeline agent is allowed to perform token exchange on behalf of users, but only when delegating to the specific backend service. Because all HBAC rules default to mfa_bypass=false, any rule covering a machine-to-machine flow must set mfa_bypass=true explicitly:

Rule: "Pipeline agent OBO delegation"
  Users: (any)
  Client: pipeline-agent
  Scopes: openid, email
  MFA bypass: true  (required for M2M flows — default is false = MFA required)
  Delegation targets: host/backend.example.com

To allow the agent to delegate to any service without an explicit allowlist:

Rule: "Pipeline agent — wildcard delegation"
  Users: (any)
  Client: pipeline-agent
  Scopes: openid, email
  MFA bypass: true
  Delegation target category: true  (wildcard — any target_service is permitted)

Two-rule pattern for OBO deployments with multiple clients

When any deployment has at least one live HBAC rule (enforcement is active), machine-to-machine clients that issue client credentials tokens also need coverage. A reliable pattern uses two rules:

Rule 1 — CC base (covers all clients for client_credentials):

Rule: "M2M base — client credentials for all clients"
  client_category: all
  user_category: all
  scope_category: all
  mfa_bypass: true
  delegation_targets: ["_cc_only"]   ← sentinel SPN prevents OBO delegation

The _cc_only sentinel is an SPN that no real service will ever request via target_service. When a token exchange request specifies a real backend SPN, this rule fails the delegation check and does not grant OBO access. The rule covers only plain client credentials requests (where no target_service is evaluated).

Rule 2 — OBO rule (explicit delegation to the backend):

Rule: "Agent OBO to backend"
  clients: [pipeline-agent-id]
  user_category: all
  scope_category: all
  mfa_bypass: true
  delegation_targets: ["host/backend.example.com"]

With this two-rule setup:

• All clients can obtain CC tokens (_cc_only sentinel prevents accidental OBO).
• Only the designated agent can perform OBO delegation to the backend.
• Both rules set mfa_bypass=true so the exchange is not rejected for missing AMR.

Delegation targets for OBO token exchange

When a client performs RFC 8693 token exchange with a target_service parameter, the HBAC rule that grants the exchange must also explicitly permit that Kerberos SPN. Two fields on each rule control this:

When a token exchange request includes target_service, the server:

1. Evaluates all regular HBAC axes (user, client, scope, network, device, ACR).
2. Among the rules that match those axes, checks whether at least one permits the SPN.
3. If none does → 403 access_denied.

When no target_service is provided, the delegation-target axis is not evaluated and delegation_targets has no effect.

If target_service is provided but no live HBAC rules exist at all, the request is denied (fail-closed), even though an empty rule set is normally allow-all for user identity flows.

Unconstrained-axis warning: A rule with delegation_targets = [] (empty list) and delegation_target_category = false does not restrict delegation at all — any target_service value will match it. When this condition is detected at evaluation time, a WARN-level log entry is emitted so operators can identify rules that may grant broader delegation than intended. The request is still processed; no error is returned to the client.

To manage delegation targets via the API, use the PATCH (PUT) endpoint with add_delegation_targets and remove_delegation_targets arrays:

# Allow delegation to a specific backend
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>

# Enable wildcard (any target_service allowed)
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>

Managing policies

Admin WebUI

Navigate to Identity HBAC policy in the sidebar. The list shows all active policies with their enabled status and a count of members.

Click any policy name to open the detail editor. Two collapsible sections keep the form focused:

• Users — who is allowed (specific users, user groups, or any user)
• PAM / SSH — hosts and services carried from FreeIPA rules; Ahdapa stores them but does not use them for OAuth2 evaluation
• OAuth2 — which clients, which scopes, source networks, device groups, and security requirements (MFA, ACR)

The General section at the top controls the policy name, description, and whether the policy is enabled.

Click Edit to make changes, Save to apply them, Delete to remove the policy.

On the Clients page, the “Identity HBAC policy” section at the bottom shows which policies apply to that client, and links directly to creating a new policy pre-scoped to that client.

Via the API

Administrators can also manage policies through the REST API. See the developer reference for the full endpoint list. A quick example:

# Restrict the HR portal to hr-staff members
curl -s -b session.jar \
  -X POST -H 'Content-Type: application/json' \
  -d '{
    "name": "HR portal — hr-staff only",
    "description": "Only hr-staff members can log in to the HR portal",
    "enabled": true,
    "user_groups": ["hr-staff"],
    "clients": ["hr-portal"],
    "allowed_scopes": ["openid", "email", "profile"]
  }' \
  https://idp.example.com/api/admin/hbac

Key behaviours to know

No policies → everyone allowed. If you have not created any policies, all authenticated users can get tokens for all clients. This preserves backward compatibility for fresh deployments.

First policy starts enforcement. The moment at least one live policy exists, access is evaluated. A user who does not match any policy is denied.

Machine-to-machine flows are excluded from user-identity HBAC. The client_credentials grant type carries no user principal, so user-axis HBAC evaluation is skipped for it. However, if you use any user-facing HBAC rule at all (which starts enforcement), M2M clients that perform OBO token exchange are evaluated via the subject token’s sub. Any HBAC rule that may match an OBO or CC flow must set mfa_bypass: true explicitly — DWRegister defaults to false (no enable-tags → disabled), so a rule without an explicit mfa_bypass=true returns mfa_required=true, and the token exchange handler rejects the request because machine-to-machine flows carry no AMR.

Token exchange (OBO) is subject to HBAC. RFC 8693 token exchange requests are evaluated against the HBAC rule set using the subject token’s sub as the identity. Group-based rules and network-axis rules do not apply during OBO exchange (group membership is not embedded in access tokens; the originating network is not available at token exchange time).

OBO with no live rules emits a warning but is allowed (without target_service). When a token exchange request arrives and no live HBAC rules exist, Ahdapa logs a WARN-level message noting that all policy checks will be skipped. If the request also carries a target_service parameter, the request is denied (403 access_denied) even with no live rules — preventing implicit Kerberos delegation in a misconfigured environment.

Malformed act chain returns 400 invalid_request. If the actor_token JWT carries an act claim that cannot be deserialized as a valid actor-claim chain, the token exchange endpoint returns 400 invalid_request rather than silently truncating the chain.

Disabled policies are ignored. A disabled policy has no effect — it does not grant or deny anything. Use the enabled toggle to temporarily suspend a policy without deleting it.

Multiple matching rules expand access. If two rules both match a request, the user gets the union of the scopes each rule allows. Rules are not ordered; the most permissive matching combination wins.

Policy changes replicate automatically. In a multi-node cluster, policy changes gossip to every node within seconds. You do not need to restart anything.

RBAC: who can manage policies

Assign the hbac:read and hbac:write permissions to roles that should manage policies. A read-only role can view policies but not modify them:

[[rbac.role]]
name        = "hbac-admin"
permissions = ["hbac:read", "hbac:write"]

[[rbac.role]]
name        = "hbac-viewer"
permissions = ["hbac:read"]

[[rbac.group_role]]
group = "admins"
role  = "hbac-admin"

OAuth2 Client Lifecycle

This section covers the complete lifecycle of an OAuth2 client interacting with ahdapa: from initial registration through token issuance, use, renewal, and final revocation. Each chapter is self-contained — you can read whichever chapter covers the flow your application needs without reading the others.

The Registering a client chapter explains how to create and manage clients. The remaining chapters cover each OAuth2 grant type, how to use the tokens that result, and how to perform a clean sign-out.

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.

Authorization Code Flow

The authorization code flow (RFC 6749 §4.1) is the standard mechanism for web applications and native apps that act on behalf of a user. It separates the authorization step (user consent in the browser) from the token step (server-to-server exchange), so access tokens never appear in the browser’s address bar or history.

PKCE (RFC 7636) is required for all clients — confidential and public alike — in line with RFC 9700 best practices.

Step 1 — Discover endpoints (one-time setup)

Fetch the server metadata to locate all endpoint URLs:

curl -s https://idp.example.com/.well-known/openid-configuration | python3 -m json.tool

Key fields:

The discovery document is cached for 24 hours (Cache-Control: public, max-age=86400).

Step 2 — Generate PKCE values

PKCE binds the authorization request to the token request, preventing authorization code interception attacks.

import secrets, hashlib, base64

# Generate a cryptographically random verifier (43-128 chars)
code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b'=').decode()

# Derive the challenge: S256 = BASE64URL(SHA-256(ASCII(verifier)))
digest = hashlib.sha256(code_verifier.encode()).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b'=').decode()

Store code_verifier in the server-side session; include code_challenge and code_challenge_method=S256 in the authorization request.

ahdapa only accepts S256. The plain method is rejected with invalid_request.

Step 3 — Send the authorization request

Redirect the user’s browser to the authorization endpoint:

GET https://idp.example.com/authorize
  ?response_type=code
  &client_id=3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20profile%20email%20offline_access
  &state=OPAQUE_RANDOM_STATE_VALUE
  &nonce=OPAQUE_RANDOM_NONCE_VALUE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

The authorization endpoint also emits Referrer-Policy: no-referrer on all responses (RFC 9700 §4.2.4) to prevent OAuth parameters from leaking to third-party resources loaded by the consent page.

Pushed Authorization Requests (PAR, RFC 9126)

Rather than putting all parameters in the browser’s URL, POST them directly to the server first and receive a request_uri to use in the redirect. This keeps parameters out of browser history and validates them before the user ever sees the consent screen.

curl -s -X POST https://idp.example.com/par \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email offline_access" \
  -d "state=OPAQUE_STATE" \
  -d "nonce=OPAQUE_NONCE" \
  -d "code_challenge=BASE64URL_CHALLENGE" \
  -d "code_challenge_method=S256"

Response — 201 Created:

{
  "request_uri": "urn:ietf:params:oauth2:request_uri:BASE64URL_TOKEN",
  "expires_in": 90
}

Then redirect the browser with only client_id and request_uri:

GET https://idp.example.com/authorize
  ?client_id=3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b
  &request_uri=urn%3Aietf%3Aparams%3Aoauth2%3Arequest_uri%3ABASE64URL_TOKEN

The request_uri expires after 90 seconds and can be used only once. PAR accepts all token endpoint authentication methods except kerberos_client_auth (which is not a browser-facing flow).

Step 4 — User authentication and consent

If the user has no valid session, ahdapa redirects them to the login page (/ui/auth/login?return_to=...). When GSSAPI is configured, the authorization endpoint first attempts SPNEGO negotiation, enabling single-round-trip authentication for Kerberos-capable browsers.

After authentication, the user is shown a consent page listing the requested scopes. On approval the browser is redirected to redirect_uri.

Scopes are intersected with the client’s registered scope set before being offered for consent. If you request openid email profile but the client is only registered for openid email, only those two scopes are offered and stored in the authorization code.

Step 5 — Authorization response

On success, the user’s browser is redirected to:

https://app.example.com/callback
  ?code=AUTHORIZATION_CODE
  &state=OPAQUE_RANDOM_STATE_VALUE
  &iss=https%3A%2F%2Fidp.example.com

The iss parameter is always included (RFC 9207 / authorization_response_iss_parameter_supported).

Verify that state matches what you stored in step 3 before proceeding.

On error, the redirect carries error and error_description instead:

https://app.example.com/callback
  ?error=access_denied
  &error_description=User+denied+access
  &state=OPAQUE_RANDOM_STATE_VALUE

Common error values: access_denied, invalid_scope, invalid_request.

Step 6 — Exchange the code for tokens

From your server (never from the browser), POST to the token endpoint:

curl -s -X POST https://idp.example.com/token \
  -u "3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b:CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "code_verifier=CODE_VERIFIER_FROM_STEP_2"

The redirect_uri must exactly match the one used in the authorization request. A missing redirect_uri returns invalid_request; a mismatched value returns invalid_grant.

Successful response — 200 OK:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6IkFCQ0QxMjM0In0...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "BASE64URL_ENCRYPTED_REFRESH_TOKEN",
  "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFCQ0QxMjM0In0...",
  "scope": "openid profile email offline_access"
}

• access_token — a signed JWT (RFC 9068 at+JWT type), valid for tokens.access_token_ttl seconds (default 900).
• id_token — included when openid is in the granted scope. A signed JWT (JWT type) with identity claims. Expires at the same time as the access token.
• refresh_token — included when offline_access is in the granted scope. An AEAD-encrypted opaque blob; not a JWT.

Error responses use the RFC 6749 error format:

{"error": "invalid_grant"}

Common errors: invalid_grant (bad code, replayed code, PKCE failure, wrong redirect_uri), invalid_request (missing required parameter), invalid_client (authentication failure), invalid_scope.

Authorization codes are single-use; replaying one returns invalid_grant.

Step 7 — Validate tokens

Access token

The access token is a compact JWT. Validate it using the server’s JWKS:

1. Fetch GET https://idp.example.com/jwks and cache it (5-minute cache TTL).
2. Find the key matching the token’s kid header claim.
3. Verify the signature using the algorithm in alg (ES256, EdDSA, ML-DSA-65, etc.).
4. Verify standard claims:
   • iss equals https://idp.example.com
   • aud contains your client_id
   • exp is in the future
   • iat is reasonable (not too far in the past)

The access token payload looks like:

{
  "iss": "https://idp.example.com",
  "sub": "alice@EXAMPLE.COM",
  "aud": ["3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b"],
  "exp": 1716000900,
  "iat": 1716000000,
  "nbf": 1716000000,
  "jti": "node1/550e8400-e29b-41d4-a716-446655440000",
  "scope": "openid profile email offline_access",
  "client_id": "3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b"
}

ID token

The ID token contains identity claims for the authenticated user:

{
  "iss": "https://idp.example.com",
  "sub": "alice@EXAMPLE.COM",
  "aud": ["3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b"],
  "exp": 1716000900,
  "iat": 1716000000,
  "nbf": 1716000000,
  "auth_time": 1715999990,
  "nonce": "OPAQUE_RANDOM_NONCE_VALUE",
  "acr": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
  "amr": ["pwd"],
  "at_hash": "BASE64URL_LEFT_HALF_SHA256_OF_ACCESS_TOKEN"
}

aud is always a JSON array of strings. nbf is always present and equals iat. at_hash is the base64url encoding of the left half of the SHA-256 hash (or the hash corresponding to the ID token signing algorithm) of the ASCII representation of the access token (OIDC Core §3.3.2.11).

Verify that nonce matches what you sent in step 3.

Step 8 — Use the access token

Include the access token as a Bearer credential on protected resource requests:

GET /api/me HTTP/1.1
Host: resource.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6IkFCQ0QxMjM0In0...

For stronger security, upgrade to DPoP sender-constrained tokens.

Client Credentials Flow

The client credentials flow (RFC 6749 §4.4) is the machine-to-machine grant type. There is no user involved: the client authenticates itself at the token endpoint and receives an access token scoped to that client’s own permissions.

Public clients (token_endpoint_auth_method = "none") are not permitted to use this grant — a client must prove its identity to receive a token.

When to use

Use the client credentials flow when:

• A backend service needs to call another service and no user session is involved.
• A machine (SSSD host, CI runner, monitoring agent) needs to authenticate itself.
• You need a token that represents the client rather than a specific user.

For user-delegated access, use the authorization code flow or device authorization flow instead.

Token request

POST /token with grant_type=client_credentials. Authenticate the client using one of the methods described below.

The response does not include a refresh_token (RFC 6749 §4.4.3 — the server SHOULD NOT issue one). To renew, simply repeat the token request.

Successful response — 200 OK:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6IkFCQ0QxMjM0In0...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid"
}

The access token sub is the client_id (RFC 9068 §2.2), except for Kerberos template clients where sub is the authenticated machine principal (see kerberos_client_auth below).

Authentication methods

client_secret_basic

The client ID and secret are encoded as HTTP Basic credentials:

curl -s -X POST https://idp.example.com/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=openid"

client_secret_post

Credentials are sent as form body parameters:

curl -s -X POST https://idp.example.com/token \
  -d "grant_type=client_credentials" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "scope=openid"

client_secret_jwt

A JWT is signed with an HMAC key derived from the client_secret. The JWT must contain iss = sub = client_id, aud pointing to the token endpoint or issuer, a short exp, and a unique jti. The server validates the HMAC signature, the claims, and enforces single-use on jti.

curl -s -X POST https://idp.example.com/token \
  -d "grant_type=client_credentials" \
  -d "client_id=CLIENT_ID" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=HMAC_SIGNED_JWT" \
  -d "scope=openid"

private_key_jwt

A JWT is signed with the client’s private key. The server fetches the corresponding public key from the client’s registered jwks_uri.

# Build and sign the assertion JWT (example using Python's PyJWT):
# {
#   "iss": "CLIENT_ID",
#   "sub": "CLIENT_ID",
#   "aud": "https://idp.example.com/token",
#   "iat": <now>,
#   "exp": <now + 60>,
#   "jti": "<unique-uuid>"
# }

curl -s -X POST https://idp.example.com/token \
  -d "grant_type=client_credentials" \
  -d "client_id=CLIENT_ID" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=SIGNED_JWT" \
  -d "scope=openid"

The aud claim must be either the token endpoint URL (https://idp.example.com/token) or the issuer URL (https://idp.example.com). A unique jti is required; replay is detected and rejected.

tls_client_auth and self_signed_tls_client_auth

The client presents its registered TLS certificate during the TLS handshake. The server verifies that the SHA-256 thumbprint of the presented certificate matches the stored thumbprint. The resulting access token contains a cnf.x5t#S256 claim binding it to the certificate.

curl -s -X POST https://idp.example.com/token \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  -d "grant_type=client_credentials" \
  -d "client_id=CLIENT_ID" \
  -d "scope=openid"

For reverse-proxy deployments, configure tls.client_cert_header in ahdapa.toml. See Configuration.

kerberos_client_auth

An ahdapa-specific extension for SSSD deployments where every enrolled machine holds a Kerberos host keytab (host/hostname@REALM).

The machine presents its Kerberos AP-REQ in the standard HTTP Negotiate header. Multi-round GSSAPI exchanges are not supported on the token endpoint — the AP-REQ must complete in a single round trip (normal for host/ service principals).

# Acquire a service ticket for the IdP's HTTP service principal
kinit -k -t /etc/krb5.keytab host/node1.example.com@EXAMPLE.COM

curl -s -X POST https://idp.example.com/token \
  --negotiate -u: \
  -d "grant_type=client_credentials" \
  -d "client_id=TEMPLATE_CLIENT_ID" \
  -d "scope=openid directory.read"

Include directory.read in the scope when the token will be used with the Identity API (/api/identity/users, /api/identity/groups).

kerberos_client_auth requires:

• [ipa] gssapi = true in the server configuration.
• The client registered via the admin API with kerberos_principal or kerberos_principal_pattern (not via DCR — dynamic registration rejects it).

For template clients (those with kerberos_principal_pattern), the access token sub is the authenticated machine principal (e.g. host/node1.example.com@EXAMPLE.COM) rather than the client_id. This makes individual machines distinguishable in audit logs and introspection responses.

See Authentication Methods for registration details and SSSD deployment patterns.

Scopes

The granted scope is the intersection of the requested scope with the client’s registered scope set. If scope is omitted, all of the client’s registered scopes are granted.

# Request only a subset of registered scopes
curl -s -X POST https://idp.example.com/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=openid"

DPoP sender-constrained tokens

Add a DPoP header to the token request to obtain a sender-constrained access token. See Using and Validating Tokens for the full DPoP proof construction.

curl -s -X POST https://idp.example.com/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "DPoP: DPOP_PROOF_JWT" \
  -d "grant_type=client_credentials" \
  -d "scope=openid"

When a DPoP proof is accepted, the response includes "token_type": "DPoP" and the access token’s cnf claim contains "jkt" — the JWK thumbprint of the client’s DPoP key. Every subsequent use of the access token must be accompanied by a fresh DPoP proof.

Token renewal

Client credentials tokens do not have refresh tokens. When a token expires, repeat the token request with the same credentials. The short default lifetime (15 minutes) means that leaked access tokens are naturally short-lived, which is why refresh tokens are not needed for machine-to-machine flows.

Device Authorization Flow

The device authorization flow (RFC 8628) enables devices that cannot display a URL or receive a redirect — TVs, CLI tools, smart appliances, IoT sensors — to authorize a user without a browser on the device itself.

Overview

1. The device requests a code pair from ahdapa.
2. The device displays a short user code and the verification URL to the user.
3. The user visits the URL on a separate device (phone, laptop) and enters the code to grant access.
4. The device polls the token endpoint until the user approves or the code expires.

Step 1 — Device authorization request

POST /device_authorization with the client_id and requested scope. Client authentication follows the same rules as the token endpoint: client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, none (public clients), or kerberos_client_auth (SPNEGO/Negotiate).

curl -s -X POST https://idp.example.com/device_authorization \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "scope=openid profile email offline_access"

Successful response — 200 OK:

{
  "device_code": "BASE64URL_DEVICE_CODE",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://idp.example.com/device",
  "verification_uri_complete": "https://idp.example.com/device?user_code=BCDF-GHJK",
  "expires_in": 1800,
  "interval": 5
}

Machine clients using kerberos_client_auth

An enrolled machine (e.g. an SSSD host) can authenticate to /device_authorization using its Kerberos host keytab instead of a client secret. The machine presents its AP-REQ in the standard HTTP Negotiate header:

# The machine acquires a Kerberos ticket for the IdP's HTTP service principal.
kinit -k -t /etc/krb5.keytab host/node1.example.com@EXAMPLE.COM

curl -s -X POST https://idp.example.com/device_authorization \
  --negotiate -u: \
  -d "client_id=TEMPLATE_CLIENT_ID" \
  -d "scope=openid offline_access"

The client must be registered with:

• token_endpoint_auth_method = "kerberos_client_auth"
• grant_types containing urn:ietf:params:oauth:grant-type:device_code
• The desired scopes including offline_access if a refresh token is wanted

The server verifies the SPNEGO token, matches the machine principal against the registered kerberos_principal or kerberos_principal_pattern, and issues the device code pair exactly as for a secret-authenticated client.

Use case: A headless machine (IoT gateway, data-collection appliance) holds a Kerberos keytab and needs to act on behalf of an authorised user. The machine itself has no browser and no client secret. It authenticates the OAuth2 client registration with Kerberos, then prompts a user to visit the verification URL on a phone or laptop to grant the specific user-level authorization.

Polling the token endpoint after the user approves also uses Kerberos:

curl -s -X POST https://idp.example.com/token \
  --negotiate -u: \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "client_id=TEMPLATE_CLIENT_ID" \
  -d "device_code=BASE64URL_DEVICE_CODE"

See Kerberos client authentication for registration requirements and template-client patterns.

Step 2 — User interaction

Show the user the verification_uri and user_code:

To authorize this device, visit:
  https://idp.example.com/device

And enter the code:
  BCDF-GHJK

Or scan this QR code: [QR for verification_uri_complete]

This code expires in 30 minutes.

The user visits the URL on a separate authenticated device (or authenticates on arrival if they have no session), enters the code, and approves or denies access. The server records their decision in the database.

Step 3 — Polling the token endpoint

While the user is authorizing, the device polls POST /token at the rate specified by interval. Authenticate the client the same way as in step 1.

curl -s -X POST https://idp.example.com/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=BASE64URL_DEVICE_CODE"

Poll responses before the user acts:

{"error": "authorization_pending"}

If you poll too quickly:

{"error": "slow_down"}

When slow_down is received, increase the polling interval by at least 5 seconds for all subsequent attempts.

Step 4 — Successful authorization

Once the user approves, the next poll returns tokens:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6IkFCQ0QxMjM0In0...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "BASE64URL_ENCRYPTED_REFRESH_TOKEN",
  "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFCQ0QxMjM0In0...",
  "scope": "openid profile email offline_access"
}

The device code is consumed on first successful redemption. Subsequent polls for the same device_code return invalid_grant.

Step 5 — Expiry and error handling

Using refresh tokens

The device flow issues a refresh token when offline_access is in the granted scope. Use it to renew the access token without requiring the user to re-authorize the device. See Refresh Tokens.

Token Exchange

The token exchange grant (RFC 8693) allows a client to exchange an existing token for a new one — typically to narrow scope, change the audience, or delegate authority from one service to another. Ahdapa implements the full RFC 8693 OBO (On-Behalf-Of) flow including actor token validation, act claim chains, three-way scope intersection, delegation target guards, and HBAC policy enforcement.

Use cases

• Service-to-service delegation (OBO) — Service A holds a user’s access token and needs to call Service B on the user’s behalf. A exchanges the token for a new one addressed to Service B, presenting its own access token as the actor_token. The issued token carries an act claim identifying Service A as the actor.
• Scope narrowing — A gateway holds a broad-scope token but wants to call a downstream service with only the scopes that service needs.
• Federation bridge — A client presents an upstream IdP’s ID token and receives an ahdapa-issued access token.

Token request

POST /token with grant_type=urn:ietf:params:oauth:grant-type:token-exchange. Authenticate the client at the token endpoint using any supported method.

curl -s -X POST https://idp.example.com/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=SUBJECT_ACCESS_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "actor_token=ACTOR_ACCESS_TOKEN" \
  -d "actor_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "scope=openid" \
  -d "audience=TARGET_CLIENT_ID" \
  -d "target_service=host/backend.example.com"

Supported subject_token_type values

Actor token validation

When actor_token is supplied, ahdapa performs the following checks before any token is issued:

1. OBO actor gate — The requesting client must have allow_token_exchange_actor = true in its registration. If this flag is absent (the default), the request is rejected immediately with 403 access_denied before any token parsing occurs.

2. JWT validity — The actor_token is verified as a signed JWT against ahdapa’s own JWKS. An actor token from an external issuer is not accepted.

3. iss and aud binding — The actor token’s iss must match the ahdapa issuer URL. Its aud must contain the requesting client_id (not the issuer URL). Ahdapa issues access tokens with aud = [client_id] per RFC 9068, so a token issued to a different client is rejected here, preventing cross-client actor token theft.

4. sub binding — The actor token’s sub claim must equal the requesting client_id. Cross-client delegation (one client acting on behalf of a different client) is not supported.

5. Act chain depth cap — The nested act chain within the actor token is counted. Chains deeper than 5 hops are rejected with 400 invalid_request to prevent stack-overflow and DoS via unbounded nesting.

Scope intersection

The granted scope is the three-way intersection of:

1. The scopes explicitly requested in the scope parameter (or the subject token’s full scope if scope is omitted),
2. The scopes carried in the subject token (scope claim), and
3. The scopes registered for the requesting client.

A client cannot receive more via OBO than the original subject token held, regardless of its own registered scopes.

• If the intersection is empty → 400 invalid_scope.
• If the intersection is non-empty but smaller than requested → 200 OK with the narrowed scope (silent narrowing per RFC 8693).

Act claim

When actor_token is present and passes validation, the issued OBO token carries an act claim:

{
  "act": {
    "sub": "pipeline-agent",
    "workload_type": "pipeline-agent"
  }
}

sub is the actor’s client_id. workload_type is resolved from the CRDT-registered client entry — not from the actor token claim — to prevent label spoofing. If the client has no workload_type set, the field is omitted.

For multi-hop delegation, existing act chains from the actor token are preserved and nested inside the new act object (up to the depth cap of 5).

Delegation target guard

When target_service is included in the request, HBAC evaluation additionally checks whether the matching rule permits that Kerberos SPN:

• If the rule has delegation_target_category = true, any target_service is permitted (wildcard).
• Otherwise, the SPN must appear in the rule’s delegation_targets list.
• If no matching rule permits the SPN → 403 access_denied.
• If target_service is provided but no live HBAC rules exist → 403 access_denied (fail-closed for delegation).

HBAC enforcement

HBAC policy is evaluated for every token exchange request (when live rules exist). The evaluation uses the subject token’s sub as the identity, the requesting client_id, the granted scopes, and the target_service (if any).

Network-axis HBAC rules (source IP matching) are not applied during token exchange — the originating network of the OBO caller is not available at this point. Group-based HBAC rules are also not applied during OBO exchange, as group membership is not embedded in the subject token JWT.

If HBAC denies the request, the response is 403 access_denied and an audit event token_exchange_denied is written.

Response — 200 OK

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6IkFCQ0QxMjM0In0...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid"
}

When a DPoP proof was included in the request, "token_type": "DPoP" is returned and the access token’s cnf.jkt contains the DPoP key thumbprint.

When the subject token came from an upstream IdP (ID token exchange), the resulting access token contains a sub_id claim in iss_sub format linking the token back to the upstream identity:

{
  "sub_id": {
    "format": "iss_sub",
    "iss": "https://upstream.example.com",
    "sub": "upstream-user-id"
  }
}

Grant type restriction

If the requesting client has an explicit grant_types list (set at registration), it must include "urn:ietf:params:oauth:grant-type:token-exchange". Clients without a grant_types list may use this grant type freely.

Client registration requirements

For a client to participate in OBO token exchange as an actor (supplying actor_token), its registration must have allow_token_exchange_actor = true. This field is false by default.

The workload_type field on the client registration provides a machine-readable label that appears in the act.workload_type claim of issued OBO tokens. Set this to a meaningful category such as "pipeline-agent" or "api-gateway" to enable audit correlation across multi-hop chains.

See Admin API — Client fields for how to set these fields.

Trusting upstream ID tokens

To exchange an upstream provider’s ID token, that provider’s issuer must be:

• Listed in federation.trusted_issuers, or
• Discovered automatically as a FreeIPA IdP ([ipa] gssapi = true), or
• Reachable via an OIDC Federation 1.0 trust chain anchored in federation.trust_anchors.

An ID token from an untrusted issuer is rejected with invalid_grant.

Example: OBO exchange with actor token

# Step 1: obtain the subject user's access token (e.g. via authorization_code)
SUBJECT_TOKEN="<user access token>"

# Step 2: obtain the agent's own access token (client_credentials)
ACTOR_TOKEN=$(curl -s -X POST https://idp.example.com/token \
  -u "pipeline-agent:agent-secret" \
  -d "grant_type=client_credentials&scope=openid" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# Step 3: perform OBO exchange
curl -s -X POST https://idp.example.com/token \
  -u "pipeline-agent:agent-secret" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=$SUBJECT_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "actor_token=$ACTOR_TOKEN" \
  -d "actor_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "scope=openid" \
  -d "target_service=host/backend.example.com"

The issued token’s act claim will identify the pipeline agent and its workload_type. See also the OBO demo for a self-contained walkthrough.

Using and Validating Tokens

This chapter explains how to present ahdapa-issued tokens to resource servers and how to validate them.

Bearer tokens

The standard way to present an access token is as a Bearer credential in the Authorization header (RFC 6750):

GET /api/resource HTTP/1.1
Host: resource.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6IkFCQ0QxMjM0In0...

If the token is missing or invalid, the resource server should respond with 401 Unauthorized and a WWW-Authenticate: Bearer header. A token with insufficient scope should return 403 Forbidden.

DPoP (RFC 9449)

DPoP (Demonstrating Proof-of-Possession) binds an access token to a specific public key controlled by the client. Even if the access token is stolen, it cannot be used without the corresponding private key.

Generating a DPoP key pair

Generate a key pair and keep the private key in memory. Common choices: ES256 (ECDSA P-256), RS256, EdDSA.

Constructing a DPoP proof

For each request, construct a compact JWS with:

Header:

{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "BASE64URL_X",
    "y": "BASE64URL_Y"
  }
}

Payload:

{
  "jti": "UNIQUE_UUID_PER_PROOF",
  "htm": "POST",
  "htu": "https://idp.example.com/token",
  "iat": 1716000000
}

• jti — unique identifier for this proof. The server rejects replays within a 5-minute window (±300 seconds of iat).
• htm — HTTP method (uppercase) of the request this proof accompanies.
• htu — Full URI of the endpoint, without fragment. Must exactly match the URL the server sees.
• iat — Current Unix timestamp. The server rejects proofs whose iat is more than 300 seconds from the current time.

Sign the compact JWS <header_b64>.<payload_b64> with your private key and append the signature.

Requesting a DPoP-bound token

Include the DPoP header in the token request:

curl -s -X POST https://idp.example.com/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "DPoP: DPOP_PROOF_JWT_FOR_TOKEN_ENDPOINT" \
  -d "grant_type=client_credentials" \
  -d "scope=openid"

When the proof is valid, the response includes "token_type": "DPoP" and the access token’s cnf claim contains the JWK thumbprint:

{
  "cnf": { "jkt": "SHA256_JWK_THUMBPRINT" }
}

Using a DPoP-bound access token

For every subsequent use of the token, construct a fresh DPoP proof with:

• htm = the HTTP method of the resource request
• htu = the URL of the resource endpoint
• ath = BASE64URL(SHA-256(ASCII(access_token))) (RFC 9449 §4.3)

Present both headers:

GET /api/resource HTTP/1.1
Host: resource.example.com
Authorization: DPoP eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6IkFCQ0QxMjM0In0...
DPoP: DPOP_PROOF_JWT_FOR_THIS_RESOURCE_REQUEST

Note Authorization: DPoP (not Bearer) when the token is DPoP-bound.

Resource servers that support DPoP must verify both the token signature and the DPoP proof, and check that cnf.jkt matches the thumbprint of the key in the DPoP proof header.

DPoP nonces

RFC 9449 §5 allows servers to issue a DPoP-Nonce response header and require clients to embed the nonce in the nonce claim of subsequent proofs. This prevents replay within the iat window at the cost of a round-trip to obtain the nonce.

ahdapa does not currently issue DPoP-Nonce headers. Clients should not include a nonce claim in DPoP proofs sent to ahdapa. A future version may enforce nonces as a stronger replay-prevention measure; the use_dpop_nonce error code will be returned when that change is deployed.

DPoP and mTLS combined

When a client uses both mTLS and DPoP simultaneously, the access token’s cnf object contains both x5t#S256 (mTLS binding) and jkt (DPoP binding):

{
  "cnf": {
    "x5t#S256": "BASE64URL_CERT_SHA256",
    "jkt": "SHA256_JWK_THUMBPRINT"
  }
}

mTLS-bound tokens (RFC 8705)

When a client uses tls_client_auth or self_signed_tls_client_auth, every access token it receives contains a cnf.x5t#S256 claim:

{
  "cnf": {
    "x5t#S256": "BASE64URL_SHA256_OF_LEAF_CERT_DER"
  }
}

Resource servers that enforce certificate binding must verify that the SHA-256 thumbprint of the client certificate presented in the TLS connection matches cnf.x5t#S256 in the token.

ahdapa advertises "tls_client_certificate_bound_access_tokens": true in both discovery documents, indicating that all tokens issued to mTLS clients carry this binding claim.

JWKS and token verification

Fetching the JWKS

curl -s https://idp.example.com/jwks

Response:

{
  "keys": [
    {
      "kid": "ABCD1234",
      "use": "sig",
      "kty": "EC",
      "crv": "P-256",
      "x": "BASE64URL_X",
      "y": "BASE64URL_Y"
    }
  ]
}

The JWKS is cached for 5 minutes (Cache-Control: public, max-age=300). Cache it in your application and refresh when a token presents an unknown kid.

Supported algorithms

ahdapa supports the following signing algorithms for access tokens and ID tokens:

The configured algorithm is set via server.jwt_signing_algorithm in ahdapa.toml (default: ES256).

ID tokens support a subset: RS256, ES256, EdDSA, ML-DSA-65.

Validating an access token

1. Decode the JWT header to find kid and alg.
2. Fetch the JWKS and locate the key with matching kid.
3. Verify the signature.
4. Validate the standard claims:
   • iss must equal the configured issuer (e.g. https://idp.example.com).
   • aud must contain your client’s client_id (or your resource server’s identifier).
   • exp must be in the future.
   • iat should be in the recent past (not more than a few minutes ago).
   • nbf must not be in the future. nbf is always present in ahdapa-issued access tokens and ID tokens (RFC 9068 §2.2).
5. For DPoP tokens: also verify cnf.jkt against the DPoP proof.
6. For mTLS tokens: also verify cnf.x5t#S256 against the presented certificate.

The access token type header is "typ": "at+JWT". ID tokens use "typ": "JWT".

Token introspection (POST /introspect, RFC 7662)

Resource servers that cannot validate JWTs locally (e.g. because they do not have a JWT library, or because they need to check revocation state for refresh tokens) can call the introspection endpoint.

Authentication is required — same methods as the token endpoint.

curl -s -X POST https://idp.example.com/introspect \
  -u "RESOURCE_SERVER_CLIENT_ID:RESOURCE_SERVER_SECRET" \
  -d "token=TOKEN_TO_INSPECT" \
  -d "token_type_hint=access_token"

Active token response:

{
  "active": true,
  "sub": "alice@EXAMPLE.COM",
  "scope": "openid profile email",
  "client_id": "3f8a2c1e-7d4b-4e9f-a0c1-2b3d4e5f6a7b",
  "username": "alice@EXAMPLE.COM",
  "token_type": "Bearer",
  "exp": 1716000900,
  "iat": 1716000000,
  "iss": "https://idp.example.com",
  "jti": "node1/550e8400-e29b-41d4-a716-446655440000"
}

Inactive or unknown token response:

{"active": false}

The token_type_hint parameter (access_token or refresh_token) influences which format is tried first. The server tries both regardless.

For refresh tokens, the introspection response also checks the CRDT revocation state — a token whose family has been revoked returns "active": false even if it has not yet expired.

The introspecting client’s client_id is checked against the token’s aud claim. A resource server can only introspect tokens addressed to it.

UserInfo endpoint

For OIDC flows, fetch the user’s profile claims from the UserInfo endpoint (OIDC Core §5.3) using the access token:

curl -s https://idp.example.com/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

The response includes the claims associated with the scopes granted:

{
  "sub": "alice@EXAMPLE.COM",
  "iss": "https://idp.example.com",
  "name": "Alice Smith",
  "given_name": "Alice",
  "family_name": "Smith",
  "preferred_username": "alice",
  "email": "alice@example.com",
  "email_verified": true,
  "groups": ["admins", "developers"]
}

preferred_username is mapped from the LDAP uid attribute (OIDC Core §5.1). It is present when the profile scope is granted and the user’s uid attribute is available from the directory.

The openid scope is required. Requesting the endpoint without openid in the token’s scope returns 403 Forbidden. The claims returned depend on which scopes were granted and what scope definitions are configured in the admin panel.

Refresh Tokens

A refresh token lets a client obtain a new access token without asking the user to re-authenticate. ahdapa implements refresh token rotation: every use of a refresh token immediately invalidates it and issues a replacement. Reuse of an old token signals theft and revokes the entire family.

When are refresh tokens issued?

Refresh tokens are issued only for:

• Authorization code flow (authorization_code grant) — always, as part of the issue_tokens call.
• Device authorization flow (device_code grant) — always, as part of the same issue_tokens call.

Refresh tokens are not issued for:

• client_credentials — RFC 6749 §4.4.3 says the server SHOULD NOT issue one. Re-request a new access token directly.
• token-exchange — no refresh token.
• jwt-bearer — no refresh token.

Refresh tokens are only issued when the client requests the offline_access scope (OIDC Core §11 / RFC 9700). Flows that do not include offline_access in the granted scope receive an access token (and, if requested, an ID token) but no refresh token. Re-authenticate or include offline_access to obtain a refresh token.

Using a refresh token

POST /token with grant_type=refresh_token. Authenticate the client the same way as on the original token request.

curl -s -X POST https://idp.example.com/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=BASE64URL_ENCRYPTED_REFRESH_TOKEN"

Optional parameters:

• scope — Request a subset of the original scopes. Scope widening (requesting scopes not in the original grant) is rejected with invalid_scope. When omitted, the original scope is preserved unchanged.

Successful response — 200 OK:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6IkFCQ0QxMjM0In0...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "NEW_BASE64URL_ENCRYPTED_REFRESH_TOKEN",
  "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFCQ0QxMjM0In0...",
  "scope": "openid profile email offline_access"
}

The response always includes a new refresh_token. The old token is immediately invalid.

Rotation and replay detection

Refresh tokens are stateful: ahdapa tracks each token family in the CRDT using a monotonically increasing token_index. When a refresh token is used:

1. The server checks the CRDT family record. If token_index in the presented token is less than the stored max_index, the token has already been used — replay detected, return invalid_grant.
2. The server increments max_index and stores the new state (gossipped to all cluster nodes).
3. A new refresh token with token_index = max_index is issued.

If a token is replayed (an old index is re-presented), the server returns invalid_grant immediately. This signals that the refresh token may have been stolen; the client should force the user to re-authenticate.

The family is explicitly revocable via DELETE /api/admin/refresh-families/{family_id} (admin API). Revoking a family sets max_index = u64::MAX, permanently invalidating all tokens in that family.

Expiry

Refresh tokens expire after tokens.refresh_token_ttl seconds (default: 86400 = 24 hours). An expired token returns invalid_grant. The expiry is from the time the token was issued, not from its last use.

When a refresh token expires:

1. The client receives invalid_grant on the next refresh attempt.
2. The user must re-authenticate via the authorization code flow or device authorization flow to obtain new tokens.

Scope narrowing on refresh

You can request a subset of the originally granted scopes on refresh:

curl -s -X POST https://idp.example.com/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=BASE64URL_ENCRYPTED_REFRESH_TOKEN" \
  -d "scope=openid"

The acr, amr, and auth_time claims in the resulting access token and ID token are preserved from the original authentication session — refreshing does not change the authentication assurance level.

DPoP and mTLS on refresh

If the original access token was DPoP-bound or mTLS-bound, include the same DPoP proof or client certificate on the refresh request. The new access token will carry the same cnf binding.

Best practices

• Store refresh tokens securely (server-side session, encrypted persistent storage). Never store them in browser localStorage or cookies accessible to JavaScript.
• Detect invalid_grant on refresh and prompt the user to re-authenticate.
• Use the shortest access token lifetime that is practical for your deployment (tokens.access_token_ttl). Refresh tokens compensate for short-lived access tokens without requiring frequent re-authentication.
• Revoke refresh token families on explicit sign-out via POST /revoke. See Revocation and Sign-Out.

Revocation and Sign-Out

Revoking tokens and terminating user sessions are distinct operations in ahdapa. This chapter covers both.

Token revocation (POST /revoke, RFC 7009)

The revocation endpoint accepts an access token or a refresh token. The client must authenticate using the same method it uses at the token endpoint.

Revoke a refresh token

Revoking a refresh token invalidates its entire family. Any subsequent use of any token in that family — including tokens issued by previous rotations — returns invalid_grant.

curl -s -X POST https://idp.example.com/revoke \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "token=BASE64URL_REFRESH_TOKEN" \
  -d "token_type_hint=refresh_token"

Internals: the server sets max_index = u64::MAX for the family in the CRDT and persists this to the database immediately. The change is gossipped to all cluster nodes. Any node that receives a subsequent refresh request for this family will reject it.

Revoke an access token

Access tokens can be revoked via the same endpoint:

curl -s -X POST https://idp.example.com/revoke \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "token=BASE64URL_ACCESS_TOKEN" \
  -d "token_type_hint=access_token"

Internals: the server extracts the jti and exp claims from the JWT without re-verifying the signature and inserts them into the crdt_revoked_access_tokens LWW-map. The entry is gossiped to all cluster nodes immediately. Token introspection on any node will return active: false for that jti until the access token’s natural expiry. Expired entries are pruned automatically from both memory and the database on each gossip cleanup tick, so the blocklist does not grow unboundedly.

Resource servers that validate access tokens locally (JWK-set signature check only) will not see the revocation unless they call /introspect. Use short access token lifetimes (tokens.access_token_ttl) together with revocation for defence-in-depth against compromised tokens.

Response

The revocation endpoint always returns 200 OK, even for unknown or already-expired tokens (RFC 7009 §2.2). This prevents oracle attacks that would let an attacker determine which tokens are valid.

HTTP/1.1 200 OK

Error responses

Authentication failures return 401 Unauthorized before reaching the revocation logic:

{"error": "invalid_client"}

Rate limit exceeded returns 429 Too Many Requests.

Session revocation (admin API)

To revoke all sessions for a specific user — for example after a security incident or account lockout — use the refresh families admin API:

# List all refresh families for a given subject
curl -s https://idp.example.com/api/admin/refresh-families -b session.jar \
  | python3 -m json.tool

# Revoke a specific family
curl -s -X DELETE \
  https://idp.example.com/api/admin/refresh-families/FAMILY_ID \
  -b session.jar

This requires the clients:write RBAC permission.

RP-initiated logout (OIDC Session Management)

Relying parties can initiate logout by redirecting the user’s browser to the /logout path:

GET https://idp.example.com/logout
  ?id_token_hint=ID_TOKEN
  &post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Flogout-complete
  &state=OPAQUE_STATE_VALUE

What happens server-side:

1. The session cookie is cleared.
2. If id_token_hint is provided and parseable, the corresponding refresh token family is looked up and revoked.
3. The user is redirected to post_logout_redirect_uri (if provided), with the state parameter appended.

post_logout_redirect_uri does not need to be pre-registered; any HTTPS URL is accepted.

Front-channel vs. back-channel logout

ahdapa provides RP-initiated logout as described above. Formal OIDC front-channel logout (iframes in the browser) and back-channel logout (HTTP callbacks from the IdP to RPs) are not implemented. Use token revocation and short access token lifetimes to limit the exposure window when a session ends.

Best practices

• Always call POST /revoke with the refresh token when the user explicitly signs out of your application. This propagates across all cluster nodes via CRDT gossip.
• Keep access token lifetimes short (tokens.access_token_ttl). Even with revocation, resource servers that do local JWT validation won’t honour the blocklist — short lifetimes remain the primary mitigation.
• Use offline_access only when persistent access is genuinely required. Omitting it means no refresh token is requested and the user must re-authenticate after the session expires.
• Revoke the refresh token on sign-out even when you also redirect to the logout endpoint — belt-and-suspenders against the user manually returning to your app before the session cookie expires.

Demos

The contrib/demo/ directory contains self-contained scenarios that each exercise one or more ahdapa features. Every demo ships with a configuration file, a static users or clients file, and a run.sh script. Most scripts exit 0 on pass and 1 on failure and are run as CI integration tests after every successful build.

Quick-start — basic single-node run

For an unstructured single-node session with no particular feature focus, use the top-level script:

bash contrib/demo/run.sh

The script builds the WebUI if webui/dist/ is absent, then locates the ahdapa binary (system-installed PATH → target/release/ahdapa → target/debug/ahdapa → cargo build) and prints the resolved path before starting. It starts ahdapa at http://127.0.0.1:8080 using contrib/demo/ahdapa.sample.toml. Credentials: alice / alice123, bob / bob123, carol / carol123. Press Ctrl-C to stop.

Demo overview

Each demo page describes:

• what it shows,
• prerequisites,
• how to run it (with example output),
• how to explore it interactively where applicable.

Common options

Binary selection

All demo scripts use the same binary selection order:

1. System-installed ahdapa found in $PATH (resolved to its full absolute path).
2. target/release/ahdapa — a release build in the repository workspace.
3. target/debug/ahdapa — a debug build in the repository workspace.
4. Falls back to cargo build (produces a debug binary) if none of the above exist.

The selected path is printed before the server starts:

Using binary: /usr/bin/ahdapa

Log verbosity

All scripts default to RUST_LOG=ahdapa=debug,info (ahdapa debug messages plus info level for all other crates). Set RUST_LOG in the environment before running a script to override:

# Quieter — ahdapa info only
RUST_LOG=info contrib/demo/run.sh

# More verbose — trace everything
RUST_LOG=trace contrib/demo/run.sh

Demo: three-node gossip cluster

Location: contrib/demo/cluster/

Runs three ahdapa instances on loopback ports 8080, 8081, and 8082 behind a shared self-signed TLS certificate. The script verifies that CRDT state converges across all three nodes, cross-node token issuance works, and a token issued on one node is introspected successfully on another.

What it shows

1. CRDT convergence — a public OAuth2 client registered on node1 appears on node2 and node3 within a few gossip intervals (configured at 2 s).
2. Tombstone propagation — deleting the client on node3 propagates back to node1 within the same gossip window.
3. Any-node token issuance — a confidential OAuth2 client registered on node1 can obtain a client_credentials access token from any of the three nodes once the CRDT has converged.
4. Cross-node token introspection — a token issued by node1 is accepted by node2’s /introspect endpoint; all nodes share the same signing keys via gossip.
5. Cross-node session revocation — enabled by distributed_mode = "eventual" in each node config. Logouts written into the revoked_sessions LwwMap propagate to all peers within one gossip round.
6. Scope definition replication — custom scope-to-claim mappings created on any node propagate to all peers.
7. Sustained multi-client traffic — three confidential clients (created on different nodes) are exercised across all nodes in rotation for 35 s; per-node latency and gossip push statistics are printed at the end.

Prerequisites

• openssl(1) — for generating the demo TLS PKI (present on all modern Linux systems).
• python3 — for JSON parsing in convergence checks.
• Ports 8080, 8081, and 8082 free. The script evicts any stale processes bound to those ports before starting.
• The ahdapa binary — the script looks in $PATH first (resolved to its full absolute path), then target/release/ahdapa, then target/debug/ahdapa, and falls back to cargo build if none is found.

Running

# Non-interactive: runs all steps, prints PASS/FAIL, exits.
contrib/demo/cluster/run.sh

# Interactive: same steps, then keeps nodes running until Ctrl-C.
contrib/demo/cluster/run.sh --interactive

What the script does

1. Generates a P-256 CA root and a server certificate with subjectAltName=IP:127.0.0.1, shared by all three nodes. Valid for 1 day.
2. Starts all three nodes with fresh SQLite databases under /tmp/.
3. Logs in as alice on each node, then generates a random 32-byte cluster wrapping key and pushes it to all three via PUT /api/admin/keys/cluster, then re-authenticates on node1 to obtain a cross-node session cookie.
4. Fetches each node’s ML-KEM-768 and ECDSA P-256 gossip keys via GET /api/gossip/kem-info and seeds them into the other two via POST /api/admin/nodes/seed so that the first encrypted gossip round can proceed.
5. Creates a public OAuth2 client on node1 and polls node2 and node3 until it appears (convergence check).
6. Deletes the client on node3 and confirms the deletion propagates to node1.
7. Creates a confidential client on node1 (client_secret_post), waits for convergence, then requests a client_credentials token from each node and verifies HTTP 200 with access_token on each.
8. Introspects the node1 token via node2’s /introspect endpoint and asserts active: true.
9. Creates two more clients (one on node2, one on node3), waits for convergence, then runs 35 s of rotating token traffic across all three nodes and clients.
10. Prints per-node token latency, per-client success rates, and gossip push statistics, then prints PASS or FAIL.

Example output (abbreviated)

Generating TLS PKI (CA + server certificate)...
  CA cert:     .../tls/ca.pem
  server cert: .../tls/cert.pem
Starting node1 (:8080)...
Starting node2 (:8081)...
Starting node3 (:8082)...
Waiting for all nodes to be ready...
  node1 ready.
  node2 ready.
  node3 ready.
Synchronizing cluster wrapping key across all nodes...
  generated cluster key: dGVzdGtleXRl...  (truncated)
  node1: cluster key set.
  node2: cluster key set.
  node3: cluster key set.
  re-authenticated on node1 with shared key.
Bootstrapping gossip KEM and signing key exchange...
  node1 KEM node_id: 127.0.0.1:8080
  node2 KEM node_id: 127.0.0.1:8081
  node3 KEM node_id: 127.0.0.1:8082
  seeded node2 keys → node1
  ...
  Waiting 5 s for first gossip rounds...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 1 — create an OAuth2 client on node1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Created client: 3f8a1b2c-...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 2 — wait for gossip to replicate the client to node2 and node3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  node2: client appeared after 3s
  node3: client appeared after 3s

  ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Statistics — 35s window, 11 batches × 3 clients
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Token endpoint (by node):
  Node      Requests     Success     Avg latency
  ────────  ────────  ───────  ───────────
  node1            8   8/8          6ms
  node2            8   8/8          5ms
  node3            8   8/8          5ms
  total           24  24/24

  Gossip (outbound pushes, traffic window only):
  Node      Pushes     Total bytes     Avg/push   Skips
  ────────  ──────  ───────────  ────────  ─────
  node1          3         22500        7500       8
  node2          2         15000        7500       9
  node3          2         15000        7500       9
  total          7         52500       —         26

  Generation-skip rate: 26/33 push attempts skipped (78%)
  cluster converged — majority of gossip rounds were no-ops

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PASS — all cluster demo steps succeeded.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Interactive exploration

With --interactive, the script keeps all three nodes running after the verification steps. The browser will warn about the self-signed certificate; add contrib/demo/cluster/tls/cert.pem to your browser’s trust store or click through the warning for local testing.

node1  https://127.0.0.1:8080/ui/
node2  https://127.0.0.1:8081/ui/
node3  https://127.0.0.1:8082/ui/

Log in as alice / alice123 on any node. The admin panel reflects the same client list on all three nodes; changes made on any node appear on the others within the gossip interval.

Configuration notes

Key settings in each node config:

[gossip]
peers            = ["https://127.0.0.1:808x", "https://127.0.0.1:808y"]
interval_secs    = 2
allowed_node_ids = ["127.0.0.1:8080", "127.0.0.1:8081", "127.0.0.1:8082"]

[cluster]
distributed_mode = "eventual"

GSSAPI/Kerberos is disabled (keytab path set to /nonexistent/keytab); alice authenticates with a password from the static users file. The [tls] section is not present in the static config files; the script appends it at runtime using the paths of the generated certificate and key.

CI usage

The script is also run as a CI integration test in the cluster-demo job of .github/workflows/ci.yml. It exits 0 on pass and 1 on any assertion failure.

See also

• Multi-node Cluster — full cluster configuration reference.
• Gossip Protocol — protocol internals.

Demo: two-IdP federation

Location: contrib/demo/federation/

Starts two ahdapa instances on loopback ports 8080 and 8081 and demonstrates section-6 authentication delegation: a downstream IdP (IdP A) redirects users to an upstream IdP (IdP B) for authentication, then maps the returned identity to a local account.

Topology

What it shows

• Federation login — alice@CORP.LOCAL is linked to bob@PARTNER.LOCAL. Entering alice at IdP A’s login page redirects the browser to IdP B; the user authenticates as bob there, and IdP A issues a local session for alice.
• Local login — carol@CORP.LOCAL logs in with a local password at IdP A without any federation redirect.
• Two-stage login UX — the login page first asks for a username, calls GET /api/auth/federated-hint to check for a federation hint, then either redirects to the upstream (federated case) or shows a password field (local case).
• OIDC dynamic client registration — IdP A registers itself as a client at IdP B via POST /register (RFC 7591) during setup; the assigned client_id is substituted into IdP A’s runtime config.
• Federated account linking — the admin API (POST /api/admin/federated-accounts) creates the bob@PARTNER.LOCAL → alice@CORP.LOCAL mapping; no manual database editing is needed.

Demo accounts

Prerequisites

• ahdapa binary — the script looks in $PATH first (resolved to its full path), then target/release/ahdapa, then target/debug/ahdapa, and falls back to cargo build if none is found.
• python3 — for JSON parsing in the setup script.
• curl.
• openssl — for generating the EC P-256 key used in the upstream client auth stanza.
• npm — if the WebUI dist/ directory does not yet exist, the script builds it.
• Ports 8080 and 8081 free.

Running

contrib/demo/federation/run.sh

What the script does

1. Checks that ports 8080 and 8081 are free; exits with an error if not.
2. Builds the WebUI (webui/dist/) if the directory is absent, then locates or builds the ahdapa binary (PATH → release → debug → cargo build).
3. Generates a P-256 private key for IdP A’s upstream client auth stanza (stored at /tmp/ahdapa-demo-idpa-upstream.pem).
4. Starts IdP B on port 8081; waits for its discovery document to be served.
5. Registers IdP A as a public OIDC client at IdP B via POST http://127.0.0.1:8081/register using the demo registration token (demo-federation-setup-token — set in idpb.toml). The response contains the generated client_id.
6. Writes a runtime config for IdP A at /tmp/ahdapa-demo-idpa-runtime.toml by substituting the real client_id into the __IDPA_CLIENT_ID__ placeholder in idpa.toml.
7. Starts IdP A on port 8080; waits for its discovery document.
8. Logs in as alice at IdP A via the admin API, then calls POST /api/admin/federated-accounts to link bob@PARTNER.LOCAL to alice@CORP.LOCAL.
9. Prints the URLs and waits until Ctrl-C. Press Ctrl-C to stop both servers; the script traps SIGINT and kills both processes.

Example startup output

Using binary: /usr/bin/ahdapa
==> Starting IdP B (Partner IdP) on :8081…
    Waiting for IdP B..................... ready.
==> Registering IdP A as OIDC client at IdP B…
    client_id=a1b2c3d4-e5f6-...
==> Generating IdP A runtime config…
==> Starting IdP A (Downstream Corp) on :8080…
    Waiting for IdP A......... ready.
==> Creating admin session at IdP A (alice)…
==> Linking bob@PARTNER.LOCAL → alice@CORP.LOCAL…
    bob@PARTNER.LOCAL  →  alice@CORP.LOCAL

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  TWO-IdP FEDERATION DEMO

  IdP A — Downstream Corp    http://127.0.0.1:8080
    WebUI:       http://127.0.0.1:8080/ui/
    Local users: alice / alice123  |  carol / carol123

  IdP B — Partner IdP        http://127.0.0.1:8081
    WebUI:       http://127.0.0.1:8081/ui/
    Local users: bob / bob123  |  diana / diana123

  FEDERATION (§6 auth delegation)
    Start external auth at IdP A:
      http://127.0.0.1:8080/auth/external/partner-idp

  Press Ctrl-C to stop both servers.

Exploring the demo

Open http://127.0.0.1:8080/ui/ in a browser.

Federated login path:

1. Enter alice in the username field and press Enter.
2. The page detects the federation hint and redirects to IdP B’s login form.
3. Enter bob / bob123 at IdP B.
4. IdP B redirects back to IdP A’s callback (/internal/callback/partner-idp).
5. IdP A maps bob@PARTNER.LOCAL to alice@CORP.LOCAL and issues a local session.
6. The admin panel shows alice as the logged-in user.

Local login path:

1. Enter carol and press Enter.
2. A password field appears (no federation hint for carol).
3. Enter carol123. Session is established at IdP A directly.

To initiate the federation flow from a client application, redirect to:

http://127.0.0.1:8080/auth/external/partner-idp

Append standard OAuth2 parameters (client_id, redirect_uri, response_type, scope, state, code_challenge, code_challenge_method) as query parameters.

Configuration notes

The upstream IdP stanza in IdP A’s config:

[[federation.upstream_idps]]
id               = "partner-idp"
issuer           = "http://127.0.0.1:8081"
client_id        = "<substituted at runtime>"
private_key_path = "/tmp/ahdapa-demo-idpa-upstream.pem"
scopes           = ["openid", "profile", "email"]
callback_path    = "/internal/callback/partner-idp"

IdP A trusts tokens issued by IdP B:

[federation]
trusted_issuers = ["http://127.0.0.1:8081"]

See also

• Federation — full federation configuration reference.
• GitHub federation demo — using GitHub as an upstream OAuth2 provider.

Demo: GitHub OAuth2 social login

Location: contrib/demo/github/

Starts one ahdapa instance configured to use GitHub as an upstream OAuth2 provider. Users authenticate at GitHub and are mapped to a local ahdapa account. This demo shows how to integrate a plain OAuth2 provider that does not support OIDC Discovery or ID tokens.

What it shows

• Non-OIDC upstream provider — GitHub does not expose an OIDC Discovery document or issue ID tokens. All three endpoints (authorization_endpoint, token_endpoint, userinfo_endpoint) are configured explicitly in the [[federation.upstream_idps]] stanza.
• Numeric subject claim — after the code exchange, ahdapa calls GET https://api.github.com/user with the GitHub access token and extracts the id field (a numeric integer) as the upstream_sub.
• Auto-link flow — the script detects the numeric GitHub user ID from the server log after the first (rejected) login attempt, then creates the federated_accounts row automatically so the second visit succeeds.
• Default group and ACR/AMR injection — the upstream stanza sets default_groups, default_acr, and default_amr so that downstream applications receive meaningful authentication context even though GitHub does not return these fields.

Prerequisites

• A GitHub OAuth App with:

  • Homepage URL: http://127.0.0.1:8080
  • Authorization callback URL: http://127.0.0.1:8080/internal/callback/github

  Register one at: GitHub → Settings → Developer settings → OAuth Apps → New OAuth App. Copy the Client ID and generate a Client Secret.

• ahdapa binary — the script looks in $PATH first (resolved to its full path), then target/release/ahdapa, then target/debug/ahdapa, and falls back to cargo build if none is found.

• Port 8080 free.

• A browser to complete the GitHub OAuth2 flow.

Running

contrib/demo/github/run.sh

The script prompts for the GitHub OAuth App credentials if they are not already set in the environment:

GitHub OAuth App Client ID: <paste here>
GitHub OAuth App Client Secret: <paste here>

Alternatively, export them before running:

export GITHUB_CLIENT_ID=Ov23liABCDEF123456
export GITHUB_CLIENT_SECRET=abcdef1234567890abcdef1234567890abcdef12
contrib/demo/github/run.sh

What the script does

1. Reads GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET from the environment or prompts for them.
2. Substitutes the values into github.toml (__GITHUB_CLIENT_ID__ and __GITHUB_CLIENT_SECRET__ placeholders) and writes contrib/demo/github/github-runtime.toml.
3. Starts ahdapa on port 8080 and waits for it to be ready.
4. Logs in as alice via the admin API to obtain a session cookie.
5. Checks GET /api/admin/federated-accounts — if the GitHub account is already linked, prints the URL and waits for Ctrl-C.
6. If not yet linked, prints the URL and watches the server log for a "no local account linked" line that contains the GitHub numeric user ID.

First-time link flow

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 1 — visit this URL to start the GitHub login:

    http://127.0.0.1:8080/auth/external/github

  GitHub will ask for permission and redirect back here.
  Because your account is not linked yet you will see a
  403 page — that is expected. This script detects your
  GitHub user ID from the server log and links the account
  automatically.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Watching for your GitHub user ID...

1. Visit http://127.0.0.1:8080/auth/external/github in a browser.
2. GitHub prompts for permission to share your profile. Authorize it.
3. GitHub redirects back to ahdapa. Because no federated_accounts row exists yet, ahdapa returns HTTP 403. This is expected.
4. The script detects your numeric GitHub user ID (e.g. 12345678) from the server log and calls POST /api/admin/federated-accounts to create the link between your GitHub account and abbra@CORP.LOCAL.

  Detected GitHub user ID: 12345678
  Linking to abbra@CORP.LOCAL...
  Account linked.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Step 2 — visit the URL again to complete the login:

    http://127.0.0.1:8080/auth/external/github

  You will be redirected to GitHub and back, then land in the
  admin panel logged in as abbra@CORP.LOCAL.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

5. Visit the URL again. GitHub recognizes the already-authorized app and redirects immediately. ahdapa finds the link and issues a local session for abbra@CORP.LOCAL. The admin panel opens.

On subsequent runs the account is already linked and the login works on the first visit.

Configuration notes

The relevant upstream IdP stanza in github.toml:

[[federation.upstream_idps]]
id                         = "github"
issuer                     = "https://github.com"
client_id                  = "__GITHUB_CLIENT_ID__"
client_secret              = "__GITHUB_CLIENT_SECRET__"
token_endpoint_auth_method = "client_secret_post"
authorization_endpoint     = "https://github.com/login/oauth/authorize"
token_endpoint             = "https://github.com/login/oauth/access_token"
userinfo_endpoint          = "https://api.github.com/user"
subject_claim              = "id"
scopes                     = ["read:user", "user:email"]
callback_path              = "/internal/callback/github"
default_groups             = ["corp-staff"]
default_acr                = "urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword"
default_amr                = ["pwd", "fed"]

Key points:

• subject_claim = "id" — uses the numeric integer field from the GitHub userinfo response as the external subject identifier rather than a username string.
• default_groups, default_acr, default_amr — injected into every token issued after a successful GitHub login because GitHub’s userinfo does not include these fields.
• No discovery_url — OIDC Discovery is not used; all three endpoints are provided explicitly.

The demo maps GitHub users to abbra@CORP.LOCAL. To map to a different local account, change the LOCAL_SUB variable in run.sh.

Security notes

github-runtime.toml is git-ignored because it contains the real client secret. Do not commit it. The secret is held only in the script’s environment and the runtime config file, which is deleted on Ctrl-C.

See also

• Federation — full federation configuration reference.
• Two-IdP federation demo — OIDC federation between two ahdapa instances.

Demo: FreeIPA/Kerberos deployment

Location: contrib/demo/ipa/

Ansible playbooks that install a FreeIPA cluster and deploy ahdapa on every node behind IPA’s Apache httpd. This demo describes a production-representative deployment rather than a local script: it requires real infrastructure (Fedora 44 hosts with DNS) and takes 15–30 minutes to complete.

Architecture

Browser / OAuth2 client
        |
        | HTTPS :443
        v
Apache httpd (IPA-managed)
  /ipa/*   → mod_wsgi (IPA API)
  /ca/*    → AJP → Dogtag PKI
  /idp/*   → mod_proxy → ahdapa (Unix socket)
        |
        v
ahdapa process (plain HTTP over Unix socket)
  GSSAPI SASL → IPA Directory Server (slapd, ldapi://)
  SPNEGO      → KDC

ahdapa listens on a Unix domain socket at /run/ahdapa/ahdapa.sock. Apache proxies all /idp/* traffic there. TLS is terminated by Apache; ahdapa needs no [tls] section.

After installation, ahdapa is available at https://<node-fqdn>/idp/.

What the demo shows

• IPA-integrated authentication — SPNEGO single sign-on for domain members; password, OTP, and passkey login for others.
• Automatic peer discovery via IPA topology — ahdapa reads the IPA replication topology from LDAP and gossips with all directly connected replicas automatically. No static peer list is required.
• Kerberos key bootstrapping — each node seeds its ML-KEM-768 key on peers via POST /api/gossip/register-kem authenticated with the node’s Kerberos machine credential. No manual key seeding is needed.
• FreeIPA IdP auto-discovery — IdPs registered with ipa idp-add … are discovered at startup and refreshed every 300 s. No [[federation.upstream_idps]] entries are needed in ahdapa.toml.
• ipauserauthtype enforcement — users with ipauserauthtype=idp set in FreeIPA are automatically redirected to the correct upstream IdP; password, OTP, and passkey flows are blocked for those users.
• SSSD id_provider = idp secretless deployment — IPA-enrolled machines use kerberos_client_auth (no per-machine secret) to obtain tokens and call the /api/identity/ directory API for user and group lookups.
• HBAC policies — Identity HBAC rules restrict which users may obtain tokens for which OAuth2 clients, enforced at the token endpoint.

Prerequisites

• Fedora 44 on all target hosts.

• Working forward and reverse DNS for every FQDN (IPA requires this).

• SSH key-based access with passwordless sudo on all hosts.

• On the Ansible control node:

  pip install ansible
  ansible-galaxy collection install freeipa.ansible_freeipa ansible.posix
  

  Or install from the distribution package:

  dnf install ansible-freeipa
  ansible-galaxy collection install ansible.posix
  

• ahdapa packages are installed from the abbra/synta COPR.

Running

# 1. Copy and edit the inventory.
cp contrib/demo/ipa/ansible/inventory.ini.example \
   contrib/demo/ipa/ansible/inventory.ini
$EDITOR contrib/demo/ipa/ansible/inventory.ini

# 2. (Recommended) encrypt passwords with ansible-vault.
ansible-vault encrypt_string 'SomeAdminPass1!' --name ipa_admin_password
ansible-vault encrypt_string 'SomeDSPass1!'    --name ipa_ds_password
# Paste the output into inventory.ini.

# 3. Run the full site playbook.
ansible-playbook -i contrib/demo/ipa/ansible/inventory.ini \
                    contrib/demo/ipa/ansible/site.yml

Individual phases

# Install and configure the IPA primary server.
ansible-playbook -i inventory.ini playbooks/ipa_server.yml

# Enroll IPA replicas (serial).
ansible-playbook -i inventory.ini playbooks/ipa_replica.yml

# Deploy ahdapa on all IPA nodes.
ansible-playbook -i inventory.ini playbooks/ahdapa.yml

# Grant IPA permissions to all ahdapa service principals.
ansible-playbook -i inventory.ini playbooks/ipa_permissions.yml

What gets installed

IPA privilege grants

ahdapa authenticates to the FreeIPA LDAP directory as its HTTP service principal (HTTP/<fqdn>@<REALM>). Three privileges are required:

ipa_permissions.yml creates and assigns these privileges idempotently for all node HTTP principals.

Inventory variables

Additional defaults are in contrib/demo/ipa/ansible/group_vars/all.yml.

Post-installation verification

After site.yml completes:

# Verify OIDC discovery endpoint.
curl -s https://ipa1.example.com/idp/.well-known/openid-configuration \
    | python3 -m json.tool | head -20

# Obtain a Kerberos ticket and test SPNEGO login.
kinit alice@IPA.EXAMPLE.COM
curl -s --negotiate -u: -c /tmp/alice.jar \
    https://ipa1.example.com/idp/api/auth/info | python3 -m json.tool

# Register an OAuth2 client via Kerberos-authenticated dynamic registration.
kinit -k -t /etc/http.keytab HTTP/client.ipa.example.com@IPA.EXAMPLE.COM
curl -s -o /dev/null -w "%{http_code}\n" \
    --negotiate -u: -c /tmp/session.jar \
    https://ipa1.example.com/idp/authorize
# → 400  (expected; no OAuth2 params given but session cookie is set)

curl -s -b /tmp/session.jar \
    -X POST -H 'Content-Type: application/json' \
    -d '{
        "redirect_uris": ["https://client.ipa.example.com/callback"],
        "client_name": "My App",
        "scope": "openid profile email"
    }' \
    https://ipa1.example.com/idp/register | python3 -m json.tool

HBAC demo

Restrict which users can obtain tokens for a specific OAuth2 client:

# 1. Create the demo OAuth2 client.
curl -s -b /tmp/admin.jar \
    -X POST -H 'Content-Type: application/json' \
    -d '{
        "client_id": "demo-app",
        "client_name": "Demo Application",
        "redirect_uris": ["https://demo.ipa.example.com/callback"],
        "scope": "openid profile email"
    }' \
    https://ipa1.example.com/idp/api/admin/clients | python3 -m json.tool

# 2. Create an HBAC policy: only alice may use demo-app.
curl -s -b /tmp/admin.jar \
    -X POST -H 'Content-Type: application/json' \
    -d '{
        "name": "alice can use demo-app",
        "enabled": true,
        "users": ["alice"],
        "clients": ["demo-app"],
        "allowed_scopes": ["openid", "profile"]
    }' \
    https://ipa1.example.com/idp/api/admin/hbac | python3 -m json.tool

# 3. List active HBAC policies.
curl -s -b /tmp/admin.jar \
    https://ipa1.example.com/idp/api/admin/hbac | python3 -m json.tool

After step 2, any user other than alice who attempts to obtain a token for demo-app receives an access_denied error at the token endpoint. The gossip protocol replicates the rule to all cluster nodes within one gossip interval.

Configuration notes

The static reference configuration is at contrib/demo/ipa/ahdapa.toml. Key points:

[server]
issuer  = "https://ipa.example.com/idp"
listen  = "unix:/run/ahdapa/ahdapa.sock"

[gssapi]
gssproxy            = true
initiator_principal = "HTTP/ipa.example.com@EXAMPLE.COM"

[ipa]
uri            = "ldapi://%2Fvar%2Frun%2Fdirsrv%2Fslapd-EXAMPLE-COM.socket"
cache_ttl_secs = 60

[gossip]
ipa_topology  = true
interval_secs = 5

• listen = "unix:/run/ahdapa/ahdapa.sock" — Apache proxies to this socket.
• gssproxy = true — uses gssproxy to obtain the HTTP service credential; no separate keytab extraction is needed.
• ipa_topology = true — peers are discovered from the IPA replication topology; no static peers list is required.

Troubleshooting

Files

See also

• FreeIPA Co-deployment — full IPA co-deployment guide.
• Multi-node Cluster — cluster configuration reference.
• Identity HBAC Policy — HBAC policy reference.

Demo: RFC 8693 OBO token exchange with HBAC

Location: contrib/demo/obo/

Demonstrates ahdapa’s full RFC 8693 On-Behalf-Of (OBO) token exchange flow with HBAC policy enforcement, actor token validation, act claim chains, and delegation target guards. Runs on a single node over plain HTTP with SQLite and static users — no Kerberos, LDAP, or TLS setup required.

What it shows

1. Basic OBO with act claim chain — A pipeline agent performs token exchange on behalf of a frontend service. The issued JWT carries an act claim with sub set to the agent’s client_id and workload_type set from the agent’s registered client profile.

2. Delegation target guard — The HBAC rule restricts which Kerberos service principals the agent may delegate to (delegation_targets). A request with the matching target_service is allowed; a request with a non-matching SPN is denied with access_denied.

3. OBO actor gate — Clients must have allow_token_exchange_actor = true to supply an actor_token. A rogue service without this flag receives access_denied immediately, before HBAC evaluation.

4. Three-way scope narrowing — The granted scope is the intersection of the requested scopes, the subject token’s scopes, and the acting client’s registered scopes. Requesting a scope the agent is not registered for yields invalid_scope.

5. HBAC client-axis deny — The HBAC rule’s clients list includes only the pipeline agent. A service that omits actor_token is still blocked by HBAC when it attempts token exchange as a different client.

Prerequisites

Running

# Non-interactive: exits 0 on pass, 1 on failure
contrib/demo/obo/run.sh

# Interactive: keeps node running until Ctrl-C
contrib/demo/obo/run.sh --interactive

Run the Python script manually against an already-running node:

python3 contrib/demo/obo/obo-hbac-demo.py \
    --base-url http://127.0.0.1:8080 \
    --admin-user alice \
    --admin-password alice123

Files

Expected output

PASS  scenario 1: basic OBO — act claim present and workload_type correct
PASS  scenario 2: delegation target allowed (host/backend.example.com)
PASS  scenario 3: delegation target denied (host/untrusted.example.com)
PASS  scenario 4: actor gate — rogue service rejected (access_denied)
PASS  scenario 5: scope narrowing — invalid_scope for unregistered scope

Key configuration concepts demonstrated

allow_token_exchange_actor must be true on a client for it to supply actor_token. This is a client-level gate independent of HBAC.

workload_type is set on the client registration and embedded in act.workload_type in OBO tokens issued when that client is the actor.

delegation_targets on an HBAC rule is a list of Kerberos SPNs the rule permits as target_service. Only rules that already match user, client, scope, and network axes are considered for the delegation check.

delegation_target_category = true on an HBAC rule is a wildcard: any target_service value is permitted by that rule.

mfa_bypass = true is required for M2M rules. DWRegister (the CRDT type backing mfa_bypass) defaults to false when no tags have been recorded. A rule without an explicit mfa_bypass=true returns mfa_required=true from HBAC evaluation, and the token exchange handler rejects the request because OBO and CC flows carry no AMR.

HBAC rule structure

The demo creates two HBAC rules rather than one:

demo-cc-base — covers all clients for plain client credentials: client_category=all, user_category=all, scope_category=all, mfa_bypass=true, delegation_targets=["_cc_only"]. The _cc_only sentinel prevents this rule from granting OBO delegation to any real service principal: when a token exchange carries a real target_service, the delegation check filters this rule out.

demo-obo-policy — explicit OBO grant for the agent: clients=[agent_id], user_category=all, scope_category=all, mfa_bypass=true, delegation_targets=["host/correct-server.example.com"].

Scenario 5 supplies target_service="host/correct-server.example.com" so the delegation axis is evaluated. The _cc_only sentinel rule is excluded in the delegation phase, and only the OBO rule satisfies the request.

Demo: passkey (WebAuthn) login

Location: contrib/demo/passkey/

Starts a single ahdapa instance configured for WebAuthn passkey authentication using static users — no FreeIPA or Kerberos infrastructure is required. On first run only password login is available; a registration helper page lets you create a passkey credential and add it to the users file.

What it shows

• WebAuthn credential registration — a standalone HTML page served by the demo instance walks through the navigator.credentials.create() call and generates the passkey:<credentialId>,<COSE_Key> line for the users file.
• Passkey login — after adding the credential to the overlay file, entering a username on the login page triggers the navigator.credentials.get() prompt instead of (or before) the password field.
• Overlay-based credential management — a gitignored overlay file is merged with the base users file at startup. The overlay takes precedence over same- username entries in the base file, so passkey credentials can be added without modifying the tracked users.toml.
• RP ID scoping — the demo uses RP ID localhost. Passkeys registered with this configuration are tied to localhost and will not work on any other origin.

Prerequisites

• ahdapa binary — the script looks in $PATH first (resolved to its full path), then target/release/ahdapa, then target/debug/ahdapa, and falls back to cargo build if none is found.
• npm — for building the WebUI dist/ directory on first run.
• A browser that supports WebAuthn (all modern browsers do).
• Port 8080 free.
• For hardware security key testing: a FIDO2-capable key (YubiKey, SoloKey, etc.)
• For virtual authenticator testing: Chrome DevTools → Application → Web Authentication → Enable virtual authenticator.

Running

contrib/demo/passkey/run.sh

On first run (when no webui/dist/ directory and no pre-built binary exist) the script builds the WebUI and the binary, then starts ahdapa. If a binary is already installed or built, it is used directly and the build step is skipped. The selected binary path is printed before launch:

==> Building WebUI (first run)…
Using binary: /home/user/ahdapa/target/release/ahdapa

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  PASSKEY DEMO

  Server           → http://localhost:8080
  WebUI            → http://localhost:8080/ui/
  OIDC discovery   → http://localhost:8080/.well-known/openid-configuration

  Register page    → http://localhost:8080/ui/passkey-register.html

  Password logins:
    alice / alice123  (admins, editors)
    bob   / bob123   (editors)
    carol / carol123

  Passkey login:   no

  RP ID:           localhost
  DB:              /tmp/ahdapa-passkey-demo.db (delete to reset)

  Press Ctrl-C to stop.

Enabling passkey login

Step 1 — start the demo

contrib/demo/passkey/run.sh

Step 2 — register a passkey for alice

Open http://localhost:8080/ui/passkey-register.html in a browser. Enter alice and click Register passkey. The browser prompts for authentication via platform authenticator, a hardware key, or a virtual authenticator in DevTools.

After the ceremony completes, the page displays a line in the form:

passkey:<base64-credentialId>,<base64-COSE_Key>

Copy this line.

Step 3 — create the overlay file

cp contrib/demo/passkey/users.passkeys.toml.example \
   contrib/demo/passkey/users.passkeys.toml

Edit users.passkeys.toml and paste the copied line into alice’s passkeys array. Ensure the password field is also present so password login continues to work:

[[user]]
username    = "alice"
password    = "alice123"
name        = "Alice Admin"
given_name  = "Alice"
family_name = "Admin"
email       = "alice@dev.local"
groups      = ["admins", "editors"]
passkeys    = [
    "passkey:AAAA...base64...,BBBB...base64...",
]

Step 4 — restart the demo

Stop the running server (Ctrl-C), then:

contrib/demo/passkey/run.sh

The startup output now shows Passkey login: yes (alice). On the login page, entering alice triggers the passkey prompt from the browser instead of the password field.

Configuration notes

The run.sh script merges the overlay and base files before starting:

# If overlay exists, prepend it (overlay entries take precedence).
cat users.passkeys.toml users.toml > /tmp/ahdapa-passkey-demo-users.toml

The merged file path is set in ahdapa.toml:

[users]
file = "/tmp/ahdapa-passkey-demo-users.toml"

RP ID

The passkey_rp_id must match the origin of the page that registered the credential. For localhost development it is always "localhost". For a production FreeIPA deployment, set it to the IPA domain name (e.g. "ipa.example.com"), which is also what FreeIPA uses when managing passkeys via ipa user-add-passkey.

[ipa]
passkey_rp_id = "localhost"

Resetting

Delete the demo database to discard all CRDT state (OAuth2 clients, keys) and start fresh:

rm /tmp/ahdapa-passkey-demo.db

The passkey credential registered in the browser is separate from the database: it is stored in the operating system’s credential store or on the hardware key. You can re-register any time using the registration page.

See also

• Authentication Methods — passkey and WebAuthn configuration reference.
• FreeIPA Co-deployment — passkey management integrated with FreeIPA ipa user-add-passkey.

Demo: static OAuth2 clients and identity directory API

Location: contrib/demo/static-clients/

Starts a single ahdapa instance with three OAuth2 clients pre-seeded from a TOML file. The script verifies that the static clients are present and protected from modification or deletion, then demonstrates the /api/identity/ directory API used by SSSD and other machine-identity consumers.

What it shows

• TOML-seeded clients — clients declared in clients.toml are upserted into the CRDT at startup. They participate in normal gossip replication and database persistence.
• Write protection — the admin API returns 403 Forbidden for DELETE and PUT requests targeting a client with source = "static".
• kerberos_client_auth template client — the sssd-template client allows any IPA-enrolled host to authenticate using its Kerberos keytab without a per-machine secret. The kerberos_principal_pattern field controls which principals match.
• Identity directory API for SSSD — the directory-reader client holds the directory.read scope. The script obtains a client_credentials token for it and exercises the two-phase user and group lookup API (/api/identity/users, /api/identity/groups, /api/identity/users/{id}/groups, /api/identity/groups/{id}/members).
• Auth guards — the identity API returns 401 Unauthorized without a token and 403 Forbidden for a token that lacks the directory.read scope.

Prerequisites

• ahdapa binary — the script looks in $PATH first (resolved to its full path), then target/release/ahdapa, then target/debug/ahdapa, and falls back to cargo build if none is found.
• python3 — for JSON parsing.
• Port 8080 free.

Running

# Non-interactive: runs all steps and exits.
contrib/demo/static-clients/run.sh

# Interactive: same steps, then keeps the server running until Ctrl-C.
contrib/demo/static-clients/run.sh --interactive

What the script does

1. Starts ahdapa with ahdapa.toml (which sets [clients] file = "clients.toml"). The static clients are seeded into the CRDT before the first request is served.
2. Logs in as alice (admin) to obtain a session cookie.
3. Lists all clients via GET /api/admin/clients and verifies sssd-template, dev-console, and directory-reader are present.
4. Attempts DELETE /api/admin/clients/sssd-template — expects 403 Forbidden.
5. Attempts PUT /api/admin/clients/sssd-template — expects 403 Forbidden.
6. Obtains a client_credentials access token for directory-reader using HTTP Basic authentication (client_secret_basic).
7. Uses the token to call:
   • GET /api/identity/users?username=alice&exact=true — Phase 1 user lookup.
   • GET /api/identity/users?username=bob&exact=true — Phase 1 user lookup.
   • GET /api/identity/users/<alice-id>/groups — Phase 2 group membership.
   • GET /api/identity/users/bob/groups — Phase 2 using short uid.
   • GET /api/identity/groups?search=corp-staff&exact=true — Phase 1 group lookup.
   • GET /api/identity/groups/corp-staff/members — Phase 2 group member list.
8. Verifies auth guards: no token → 401, wrong scope → 403.

Example output (abbreviated)

Starting ahdapa (log: .../ahdapa.log)...
Server ready (pid 12345).
Logging in as alice (admin)...

── Listing clients ──────────────────────────────────────────────────────
[
    {"client_id": "sssd-template", ...},
    {"client_id": "dev-console",   ...},
    {"client_id": "directory-reader", ...}
]

  ✓ sssd-template is present
  ✓ dev-console is present
  ✓ directory-reader is present

── Testing delete protection ────────────────────────────────────────────
  ✓ DELETE /api/admin/clients/sssd-template → 403 (protected)

── Testing update protection ────────────────────────────────────────────
  ✓ PUT /api/admin/clients/sssd-template → 403 (protected)

── Identity API demo ────────────────────────────────────────────────────
  Obtaining token for directory-reader (client_credentials)...
  ✓ Token obtained (512 chars)

── Phase 1 — user lookup: alice ─────────────────────────────────────────
[{"id": "alice@CORP.LOCAL", "username": "alice", ...}]
  ✓ alice resolved — id=alice@CORP.LOCAL

── Phase 1 — user lookup: bob ───────────────────────────────────────────
[{"id": "bob@CORP.LOCAL", "username": "bob", ...}]
  ✓ bob resolved — id=bob@CORP.LOCAL

── Phase 2 — groups for alice (using fully-qualified id) ────────────────
[{"id": "corp-staff", ...}, {"id": "editors", ...}]
  ✓ alice belongs to 2 group(s)

── Phase 2 — groups for bob (using short uid) ───────────────────────────
[{"id": "corp-staff", ...}]

── Phase 1 — group lookup: corp-staff ───────────────────────────────────
[{"id": "corp-staff", ...}]
  ✓ corp-staff resolved

── Phase 2 — members of corp-staff ─────────────────────────────────────
[{"username": "alice", ...}, {"username": "bob", ...}]
  ✓ corp-staff has 2 member(s)

── Auth guard: missing token → 401 ─────────────────────────────────────
  ✓ No token → 401 Unauthorized

── Auth guard: missing scope → 403 ──────────────────────────────────────
  ✓ Token without directory.read → 403 Forbidden

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Demo complete.
  Static clients: seeded and read-only.
  Identity API:   two-phase user/group lookup verified.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Interactive exploration

With --interactive, the server stays running after verification. The following endpoints are available for manual testing:

Token endpoint:  http://127.0.0.1:8080/token
Identity API:    http://127.0.0.1:8080/api/identity/users?username=alice&exact=true
Admin API:       http://127.0.0.1:8080/api/admin/clients

To obtain a token for manual identity API calls:

TOKEN=$(curl -sf -X POST http://127.0.0.1:8080/token \
    -u "directory-reader:dir-reader-secret" \
    -d "grant_type=client_credentials&scope=directory.read" \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

curl -s -H "Authorization: Bearer $TOKEN" \
    "http://127.0.0.1:8080/api/identity/users?username=alice&exact=true" \
    | python3 -m json.tool

Configuration notes

ahdapa.toml points to the clients file:

[clients]
file = "contrib/demo/static-clients/clients.toml"

Static clients

sssd-template — Kerberos machine authentication template. Any host with a host/<hostname>@EXAMPLE.COM keytab can authenticate using kerberos_client_auth. The HBAC service sssd-idp gates which hosts are allowed (when FreeIPA HBAC is configured).

[[client]]
client_id   = "sssd-template"
client_name = "SSSD Machine Template (Kerberos)"
token_endpoint_auth_method = "kerberos_client_auth"
scopes      = ["openid"]
grant_types = ["client_credentials"]
kerberos_principal_pattern = "host/*@EXAMPLE.COM"
kerberos_hbac_service      = "sssd-idp"

dev-console — Public authorization-code client for a local developer console. No client secret; uses PKCE.

[[client]]
client_id   = "dev-console"
client_name = "Developer Console"
token_endpoint_auth_method = "none"
redirect_uris = ["http://localhost:8081/callback"]
scopes        = ["openid", "profile", "email"]
grant_types   = ["authorization_code"]

directory-reader — Confidential client for SSSD-style machine identity lookups. Uses HTTP Basic authentication (client_secret_basic). The directory.read scope gates access to the /api/identity/ endpoints.

[[client]]
client_id     = "directory-reader"
client_name   = "Directory Reader (SSSD / machine identity lookup)"
token_endpoint_auth_method = "client_secret_basic"
client_secret = "dir-reader-secret"
scopes        = ["directory.read"]
grant_types   = ["client_credentials"]

Identity API two-phase lookup

The /api/identity/ API follows the same two-phase protocol as SSSD’s id_provider = idp lookup:

Phase 1 — search:

GET /api/identity/users?username=<name>&exact=true
GET /api/identity/groups?search=<name>&exact=true

Returns a JSON array with basic attributes. The id field in each entry is the fully-qualified identity handle (e.g. alice@CORP.LOCAL) used in Phase 2 calls.

Phase 2 — detail:

GET /api/identity/users/<id>/groups
GET /api/identity/groups/<id>/members

<id> may be the fully-qualified handle (URL-encoded) or the short uid. Both forms are accepted.

All identity API endpoints require a bearer token with the directory.read scope. Requests without a token return 401 Unauthorized; requests with a token that lacks the scope return 403 Forbidden.

Users file

users.toml includes POSIX attributes so that the identity API can return uid_number, gid_number, home_directory, login_shell, and gecos:

[[user]]
username       = "alice"
password       = "alice123"
uid_number     = 10001
gid_number     = 10001
home_directory = "/home/alice"
login_shell    = "/bin/bash"
gecos          = "Alice Atkinson,,,"
groups         = ["corp-staff", "editors"]

How static clients work

On startup, AppState::new() reads the file pointed to by [clients] file, converts each [[client]] entry to a ClientEntry with source = "static", and calls crdt.clients.upsert() for each one using the current timestamp. Because LWW (Last-Write-Wins) semantics apply, the file always wins on restart: any database row for the same client_id from a prior run is overwritten.

After seeding, the CRDT is persisted to the database and gossiped to peers — static clients participate in normal replication. The admin API rejects DELETE and PUT requests for clients with source = "static", returning 403 Forbidden.

See also

• Identity API — full /api/identity/ endpoint reference.
• Configuration — [clients] — clients.file key documentation.
• FreeIPA Co-deployment — SSSD — production SSSD deployment with kerberos_client_auth.

Configuration Reference

The configuration file is TOML. Its path is read from the AHDAPA_CONFIG environment variable (default: /etc/ahdapa/config.toml).

[server]

[db]

[gssapi]

Exactly one of keytab or gssproxy = true should be set. If neither is reachable at startup, the server logs a warning and continues with SPNEGO disabled. Password-based authentication via LDAP still works.

[ipa]

Required IPA privileges

When [ipa] gssapi = true and [gssapi] initiator_principal is set, the HTTP service principal must hold the following IPA privileges (granted via the Ahdapa Services role):

See FreeIPA Co-deployment — Multi-node HA for the ipa privilege-add / ipa permission-add commands and the Ansible playbook that provisions all of these idempotently.

ipauserauthtype enforcement

When [ipa] gssapi = true, ahdapa reads the ipauserauthtype LDAP attribute for each user at login time and enforces it as a gate on all non-Kerberos token flows. The per-user value overrides the global default stored in cn=ipaconfig,cn=etc,<suffix>; if neither is set, any method is permitted (backward-compatible, fail-open behaviour).

Recognised values (case-insensitive, may be combined):

An empty effective set (no per-user value and no global default) means no restriction — all methods are allowed.

ipauserauthtype error responses

When the ipauserauthtype gate rejects a token request, the token endpoint returns 401 Unauthorized with a JSON body:

Method not in allowed set:

{
  "error": "invalid_credentials",
  "error_description": "Authentication method not allowed by user policy."
}

idp in effective set — user must use an external IdP:

{
  "error": "federated_login_required",
  "error_description": "This account must authenticate via an external identity provider.",
  "redirect_to": "/auth/external/ipa-google-workspace"
}

The redirect_to field contains the path to initiate the upstream IdP login flow. The upstream IdP identifier (ipa-google-workspace in the example) is derived from the ipaidpconfiglink attribute on the user’s LDAP entry.

The global default auth types are fetched at startup and refreshed alongside the IPA IdP list every 300 seconds.

[webui]

Branding example

[webui]
static_dir     = "/usr/share/ahdapa/webui"
logo_url       = "/branding/logo.png"
custom_css_url = "/branding/custom.css"
default_theme  = "dark"

The logo and custom CSS files should be served by the reverse proxy (e.g. an nginx location /branding/ block) or an external CDN. When external origins are used (e.g. "https://cdn.corp.example.com/logo.png"), ahdapa automatically adds the origin to the Content Security Policy so browsers do not block the resources.

[tokens]

All keys are optional. Lifetimes are in seconds.

[federation]

All keys are optional. When this section is absent, the server publishes a valid Entity Statement but rejects all incoming federated assertions.

[[federation.upstream_idps]]

Repeat this section once per upstream IdP for §6 authentication delegation. When configured, the login page redirects federated users to the upstream instead of showing a local password field.

IPA auto-discovery: When [ipa] gssapi = true, ahdapa automatically reads all ipaIdP LDAP objects from cn=idp,<suffix> at startup and after every 300-second refresh cycle, and converts them into upstream IdP registrations without requiring any [[federation.upstream_idps]] entries. Each IPA-sourced IdP gets id = "ipa-{slug}" (the CN lowercased with spaces replaced by -) and callback_path = "/internal/callback/ipa-{slug}". Entries in the static TOML take precedence over IPA-sourced entries that share the same id. Manual [[federation.upstream_idps]] sections are still needed for IdPs that are not registered in FreeIPA (e.g. GitHub, Google, or custom providers without an ipaIdP object).

Client authentication

Exactly one authentication method must be configured:

Core fields

Static endpoint overrides (non-OIDC providers)

By default the server fetches {issuer}/.well-known/openid-configuration to discover endpoints. For providers that don’t publish OIDC Discovery (GitHub, Discord, Slack, etc.) set these overrides instead:

§5 claims backing

Account linkage

After setting up an [[federation.upstream_idps]], link accounts via the admin API:

POST /api/admin/federated-accounts
Content-Type: application/json

{
  "upstream_iss": "https://partner.example.com",
  "upstream_sub": "bob@PARTNER.LOCAL",
  "local_sub":    "alice@CORP.LOCAL"
}

Accounts can also be resolved automatically from FreeIPA’s ipaIdpUser LDAP schema when LDAP is configured.

Examples

Another ahdapa / Keycloak / Okta / Auth0 (OIDC + private_key_jwt):

[[federation.upstream_idps]]
id               = "corp-sso"
issuer           = "https://partner.example.com"
client_id        = "abc123"
private_key_path = "/etc/ahdapa/upstream-corp-sso.pem"
scopes           = ["openid", "profile", "email"]
callback_path    = "/internal/callback/corp-sso"

Google / GitLab / LinkedIn (OIDC Discovery + client_secret_post):

[[federation.upstream_idps]]
id                         = "google"
issuer                     = "https://accounts.google.com"
client_id                  = "12345.apps.googleusercontent.com"
client_secret              = "GOCSPX-..."
token_endpoint_auth_method = "client_secret_post"
scopes                     = ["openid", "profile", "email"]
callback_path              = "/internal/callback/google"

GitHub (plain OAuth2 — no OIDC Discovery, no ID token):

[[federation.upstream_idps]]
id                         = "github"
issuer                     = "https://github.com"
client_id                  = "Iv1.abc123"
client_secret              = "ghp_..."
token_endpoint_auth_method = "client_secret_post"
authorization_endpoint     = "https://github.com/login/oauth/authorize"
token_endpoint             = "https://github.com/login/oauth/access_token"
userinfo_endpoint          = "https://api.github.com/user"
subject_claim              = "id"
scopes                     = ["read:user", "user:email"]
callback_path              = "/internal/callback/github"

Apple Sign In (private_key_jwt required by Apple):

[[federation.upstream_idps]]
id               = "apple"
issuer           = "https://appleid.apple.com"
client_id        = "com.example.your-service-id"
private_key_path = "/etc/ahdapa/apple-authkey.pem"
scopes           = ["openid", "name", "email"]
callback_path    = "/internal/callback/apple"

[users]

Optional. Configures a static users file for local authentication without a live FreeIPA/LDAP server. When set, username and password authentication checks this file before PAM and LDAP. Users not found here fall through to PAM (if [pam] is configured and the binary was built with --features pam) and then to LDAP. Profile attribute and group lookup follows a three-step chain: static users → varlink (if [varlink] is configured) → LDAP.

Static users file format

The file is TOML with one [[user]] section per user. Passwords are stored in plain text — use this only for local development and CI.

Example

[users]
file = "/etc/ahdapa/users.toml"

# /etc/ahdapa/users.toml
[[user]]
username       = "alice"
password       = "changeme"
name           = "Alice Admin"
given_name     = "Alice"
family_name    = "Admin"
email          = "alice@example.com"
groups         = ["admins"]
uid_number     = 10001
gid_number     = 10001
home_directory = "/home/alice"
login_shell    = "/bin/bash"

[[user]]
username = "bob"
password = "changeme"
email    = "bob@example.com"
groups   = ["viewers"]

[clients]

Optional. Seeds a fixed set of OAuth2 clients from a TOML file at startup. Clients defined here are upserted into the CRDT with the current timestamp (so the file always wins after a restart), persisted to the database, and gossiped to cluster peers. The admin API rejects PUT and DELETE requests for static clients with 403 Forbidden.

If the file is configured but cannot be read or parsed, startup fails with a fatal error (unlike [users], which warns and continues). This is intentional: static clients are typically critical infrastructure (e.g. an SSSD machine-auth template).

Static clients file format

The file is TOML with one [[client]] section per client.

Exactly one of kerberos_principal / kerberos_principal_pattern must be set when token_endpoint_auth_method = "kerberos_client_auth".

Example

[clients]
file = "/etc/ahdapa/clients.toml"

# /etc/ahdapa/clients.toml

[[client]]
client_id   = "sssd-template"
client_name = "SSSD Machine Template"
token_endpoint_auth_method = "kerberos_client_auth"
scopes      = ["openid", "directory.read"]
grant_types = ["client_credentials"]
kerberos_principal_pattern = "host/*@EXAMPLE.COM"
kerberos_hbac_service      = "sssd-idp"

[[client]]
client_id   = "ci-pipeline"
client_name = "CI Pipeline"
token_endpoint_auth_method = "private_key_jwt"
scopes      = ["openid", "profile"]
grant_types = ["client_credentials"]
jwks_uri    = "https://ci.example.com/.well-known/jwks.json"

[varlink]

Optional. When present, ahdapa queries the local system user database via the io.systemd.UserDatabase varlink interface for profile attributes and group memberships before falling back to FreeIPA LDAP. This is useful on systemd-based hosts where users are managed by systemd-homed, sssd, or another NSS/userdb provider registered with the systemd multiplexer.

Requires the varlink Cargo feature to be enabled at compile time (--features varlink). If the binary was built without this feature, the [varlink] section is accepted in the config file but silently ignored.

Password authentication is not supported through varlink: the privileged section of a userdb record (which contains hashed passwords) is not accessible to non-root processes. Password authentication uses the static users file, then PAM (if [pam] is configured), and finally LDAP.

Requires systemd 246 or later with /run/systemd/userdb/io.systemd.Multiplexer present.

Example

[varlink]
service      = "io.systemd.Multiplexer"
timeout_secs = 5

[pam]

Optional. When present, ahdapa delegates password verification to the system PAM stack before falling back to FreeIPA LDAP. This covers any PAM-integrated backend: SSSD (FreeIPA, Active Directory via SSSD), winbindd, systemd-homed, or any other PAM module. When PAM returns PAM_NEW_AUTHTOK_REQD (expired password), the user is redirected to /login/change-password to complete a password change before their session is established.

Requires the pam-devel package at build time. Enable at compile time with --features pam. If the binary was built without this feature, the [pam] section is accepted in the config file but silently ignored.

The password authentication lookup chain is: static users file → PAM (if [pam] configured) → LDAP simple bind.

Install contrib/systemd/ahdapa-pam.conf as /etc/pam.d/ahdapa to provide the PAM service definition. The default includes system-auth; replace it with sssd or winbind as appropriate for your environment.

Example

[pam]
service      = "ahdapa"
timeout_secs = 30

[rbac] / [[rbac.role]] / [[rbac.group_role]]

Role-based access control for the admin API. When this section is absent, all admin API requests return 403 — access is denied to everyone. Add it to grant admin access to specific groups.

Groups are resolved in order: (1) the static users file, (2) the varlink system userdb if [varlink] is configured and the binary was built with the varlink feature, (3) FreeIPA LDAP memberOf if LDAP is configured. The first source that returns a non-empty result is used.

[[rbac.role]]

Repeat once per role.

[[rbac.group_role]]

Maps a group name to a role. Repeat once per (group, role) pair.

Permission strings

Example

[[rbac.role]]
name        = "admin"
permissions = ["*"]

[[rbac.role]]
name        = "viewer"
permissions = [
  "clients:read", "keys:read", "federation:read",
  "users:read", "nodes:read", "audit:read", "scopes:read",
]

[[rbac.group_role]]
group = "admins"
role  = "admin"

[[rbac.group_role]]
group = "helpdesk"
role  = "viewer"

[gossip]

[cluster]

Optional. Controls multi-node coordination behaviour. When this section is absent or distributed_mode = "off", ahdapa operates in single-node mode: auth codes can only be exchanged on the issuing node, and session revocation is node-local only.

All keys are optional. The section itself is optional — omitting it is equivalent to distributed_mode = "off".