Enterprise SSO

# /home/.aihummer/etc/gateway.env
AIHUMMER_OIDC_ISSUER=https://idp.example.com/

AiHummer authenticates administrators and users against your identity provider. The primary, production-path control is **OIDC**, which protects the admin API; **SAML**, **LDAP/AD** and **SCIM** provisioning are also implemented, alongside **local auth** for setups without an external IdP. ## OIDC protects the admin API OIDC is **deny-by-default** and is the control that protects `/v1/admin/*`. Configure it with `AIHUMMER_OIDC_ISSUER` (and the related client settings). ```ini # /home/.aihummer/etc/gateway.env AIHUMMER_OIDC_ISSUER=https://idp.example.com/ ``` There is an **oidc-setup runbook** (`docs/runbooks/oidc-setup.md`) that walks through registering the client and wiring the issuer. > [!DANGER] > Without OIDC configured, the admin API trusts **dev headers** for identity. > That mode is for local development only — **never expose an admin endpoint to > the internet without OIDC (or another enforced auth) in front of it.** > Configure `AIHUMMER_OIDC_ISSUER` before any non-local deployment. > [!TIP] > Layer OIDC with the [IP allowlist](/en/v1.0/security/network-audit-airgapped) > and [scoped API keys](/en/v1.0/security/rbac) so that admin access is gated by > identity, network and privilege together. ## SAML SAML single sign-on is implemented, exposing the standard service-provider endpoints: | Endpoint | Purpose | |---|---| | `GET /saml/metadata` | Service-provider metadata for your IdP. | | `POST /saml/acs` | Assertion Consumer Service — receives the SAML response. | | `GET /saml/login` | Initiates the SAML login flow. | > [!NOTE] > SAML is implemented but is **not fully live-proven** against every IdP. Treat > it as available and validate it against your specific identity provider before > relying on it in production. ## LDAP / Active Directory LDAP/AD authentication is implemented for environments that authenticate users against a directory server. > [!NOTE] > As with SAML, LDAP/AD is implemented but **not fully live-proven** across all > directory configurations. Test it against your own directory before rollout. ## SCIM provisioning SCIM lets your IdP provision and de-provision users automatically, via the standard SCIM v2 user endpoints: | Endpoint | Purpose | |---|---| | `GET /scim/v2/Users` | List / query provisioned users. | | `POST /scim/v2/Users` | Create a user. | | `GET /scim/v2/Users/{id}` | Read a single user. | | `PUT /scim/v2/Users/{id}` | Update a user. | | `DELETE /scim/v2/Users/{id}` | De-provision a user. | Provisioning through SCIM keeps the user directory in sync with your IdP so that joiners and leavers are reflected without manual admin work. ## Local auth When there is no external IdP, AiHummer supports **local authentication**. On a fresh database the gateway prints a one-time `admin` password to the log on first start; log in and change it immediately. Local auth is suitable for small or isolated deployments, but for organizations with an IdP, OIDC remains the recommended production path. ## Choosing an approach | Mechanism | Best for | Status | |---|---|---| | OIDC | Protecting the admin API in any non-local deployment | Recommended production path | | SAML | Enterprises standardized on SAML SSO | Implemented; validate against your IdP | | LDAP / AD | Directory-based authentication | Implemented; validate against your directory | | SCIM | Automated user provisioning from the IdP | Implemented (SCIM v2 Users) | | Local auth | Small or isolated deployments without an IdP | Built in | ## Where to next - [RBAC & scoped API keys](/en/v1.0/security/rbac) — authorize the identities your IdP authenticates. - [Network, audit & air-gapped](/en/v1.0/security/network-audit-airgapped) — gate admin access by network and keep an audit trail. - [Secrets vault](/en/v1.0/security/vault) — where credentials and tokens live.