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

Mode summary

Example

# Recommended HA default — cross-node session revocation, any-node code exchange.
[cluster]
distributed_mode = "eventual"

# Forwarding mode — zero replay window for auth code exchanges.
[cluster]
distributed_mode = "forwarding"

# Strict mode — quorum pre-approval before every token issuance.
[cluster]
distributed_mode  = "strict"
quorum_k          = 0       # majority: floor(peers/2)+1
quorum_timeout_ms = 500
quorum_fallback   = false   # hard-reject on quorum failure

[tls]

When this section is absent or enabled = false, ahdapa listens on plain HTTP. Use this section when ahdapa terminates TLS itself; omit it when a reverse proxy handles TLS.

mTLS client authentication (RFC 8705)

When a client registers with token_endpoint_auth_method set to tls_client_auth or self_signed_tls_client_auth, the token endpoint authenticates the client by comparing the SHA-256 thumbprint of the presented TLS certificate against the thumbprint stored for that client. Two certificate delivery paths are supported:

Native TLS (ahdapa terminates TLS): the client certificate is extracted from the TLS handshake by the accept loop and injected into the request as an extension. No additional configuration is needed beyond enabling [tls].

Reverse proxy (a proxy terminates TLS and forwards the cert): set client_cert_header to the name of the header the proxy uses (e.g. "X-Client-Cert" for HAProxy, or the nginx $ssl_client_escaped_cert variable forwarded as "X-SSL-Client-Cert"). Also set trusted_proxy_cidrs to the CIDR(s) of your proxy tier. Requests from outside those CIDRs will not have the header honoured.

To register an mTLS client via the admin API, supply the client certificate as PEM in the tls_client_certificate field of the create/update request. The server computes the SHA-256 thumbprint and stores only that; the full certificate is not persisted.

Certificate-bound access tokens (RFC 8705 §3): every access token issued to an mTLS client contains a cnf claim with x5t#S256 set to the base64url-encoded SHA-256 thumbprint of the client certificate presented at the token endpoint. Resource servers that receive such a token must verify that the cnf.x5t#S256 value matches the certificate the client used to establish the mTLS connection for the resource request, preventing token theft by a party without the certificate’s private key. The discovery documents (/.well-known/oauth-authorization-server and /.well-known/openid-configuration) advertise "tls_client_certificate_bound_access_tokens": true (RFC 8705 §7.3) so that clients know to expect this binding.

When a client authenticates with both mTLS and DPoP simultaneously, the access token cnf object contains both x5t#S256 (mTLS binding) and jkt (DPoP key thumbprint binding).

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

{
  "client_name": "my-service",
  "redirect_uris": ["https://my-service.example.com/callback"],
  "scopes": ["openid", "profile"],
  "token_endpoint_auth_method": "tls_client_auth",
  "tls_client_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Example

[tls]
enabled   = true
cert_file = "/etc/pki/tls/certs/idp.example.com.pem"
key_file  = "/etc/pki/tls/private/idp.example.com.key"

For gossip between nodes that use a private CA:

[tls]
enabled   = true
cert_file = "/etc/pki/tls/certs/node.pem"
key_file  = "/etc/pki/tls/private/node.key"
ca_cert   = "/etc/pki/tls/certs/cluster-ca.pem"

[spiffe]

Optional. When trust_domain is set, ahdapa acts as a SPIFFE trust domain authority and Workload API server. All other keys have safe defaults. When this section is absent or trust_domain is unset, no SPIFFE functionality is activated.

See SPIFFE Integration for a setup guide.

CA key loading priority

1. CRDT contains an encrypted CA key blob (from a previous startup or gossip) → decrypt with the cluster wrapping key and use.
2. ca_key_file starts with pkcs11: → load from HSM; ca_cert_file is required. The HSM key is not stored in the CRDT.
3. Both ca_key_file and ca_cert_file are set → load PEM files; encrypt the private key and gossip via CRDT.
4. Nothing set → generate a new ECDSA CA (algorithm from ca_algorithm); encrypt and gossip the key.

Example

[spiffe]
trust_domain         = "example.org"
workload_socket      = "/run/spiffe/workload.sock"
workload_socket_mode = 432   # 0o660 — owner + group read-write
svid_ttl_seconds     = 3600
ca_ttl_days          = 365
ca_algorithm         = "EC-P256"
ca_subject_cn        = "example.org SPIFFE CA"
ca_subject_o         = "Example Corp"
bundle_refresh_hint  = 300
# accepted_proxies is optional; the default shown below is applied when absent
accepted_proxies     = ["host", "HTTP"]

HSM-backed CA:

[spiffe]
trust_domain    = "example.org"
ca_cert_file    = "/etc/ahdapa/spiffe-ca.pem"
ca_key_file     = "pkcs11:token=spiffe-ca;object=ca-key;type=private"

Environment variables

Minimal example

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

Three-node cluster example

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

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

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

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

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

[tokens]
access_token_ttl  = 600
refresh_token_ttl = 43200

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

[cluster]
distributed_mode = "eventual"

Each of the three nodes lists the other two as peers. A full mesh is not required: each node only needs to reach any one other node for state to eventually propagate to the entire cluster.

Access control for gossip and internal endpoints: The /api/gossip/* and /api/internal/* endpoints are served on the same port as the public OAuth2 endpoints and are protected at the application layer. /api/gossip/sync, /api/gossip/wrapping-key, and the two /api/internal/ endpoints are authenticated by CMS (ECDSA P-256 signature + ML-KEM-768 encryption) and the allowed_node_ids allowlist. /api/gossip/register-kem is authenticated by Kerberos SPNEGO. Port-level firewall rules cannot selectively block these paths without also blocking public OAuth2 clients. A reverse proxy can add an optional path-level restriction — see Reverse Proxy Setup. The internal endpoints return 404 Not Found when distributed_mode = "off" or "eventual".