This module integrates HumHub with a SAML 2.0 Identity Provider (IdP) so your users can sign in via Single Sign-On.

Quick start

1. Open Administration → Users → Authentication → SAML in HumHub.
2. Either click Import IdP metadata and paste (or upload) the metadata XML from your IdP, or fill in the four basic fields manually (Entity ID, SingleSignOn URL, SingleLogout URL, IdP signing certificate).
3. Save.
4. Switch to the HumHub Metadata tab and register HumHub at your IdP — either by sharing the SP metadata XML download or by copying the displayed values into the IdP's SP configuration.

Standard SAML claims (id, email, username, firstname, lastname) are auto-detected from a curated list of common attribute names — LDAP OIDs, ADFS / SOAP schemas, Microsoft / Azure AD claims, raw shortnames. No manual attribute mapping is needed for the default fields. Use the Attribute mapping setting only to override the auto-detection or to map custom profile fields.

Identity Provider notes

SimpleSAMLphp

Works with the standard SAML 2.0 SP profile. Use the IdP metadata import.

Active Directory Federation Services (AD FS)

1. In AD FS Management, add a Relying Party Trust for HumHub.
2. Import HumHub's SP metadata XML (download from the HumHub Metadata tab).
3. Add Claim Issuance Policy rules that send the standard user attributes (email, sAMAccountName / UPN, givenName, surname) — HumHub's auto-detection recognises both raw shortnames and the AD-FS default http://schemas.xmlsoap.org/… claim URLs, so either form works.
4. Ensure URL rewriting is enabled at the IIS / reverse proxy in front of HumHub.

AD FS often rejects unsigned outgoing logout messages. If you use Single Logout, enable Sign LogoutRequest and Sign LogoutResponse under Security and configure the HumHub SP keypair under HumHub identity (Service Provider).

Keycloak

Works out of the box:

1. In Keycloak, create a new SAML client and import HumHub's SP metadata.
2. In HumHub, click Import IdP metadata and paste Keycloak's metadata (Realm settings → Endpoints → SAML 2.0 Identity Provider Metadata).
3. Save.

Standard claims are auto-detected — no attribute-mapping changes needed.

Older versions of this manual recommended enabling Single Role Attribute on Keycloak's role_list mapper. That workaround is no longer required.

Okta

Works via the standard SP metadata import. In Okta, create the application via Applications → Create App Integration → SAML 2.0 and either upload HumHub's SP metadata or paste in the individual values from the HumHub Metadata tab.

Microsoft Entra ID (Azure AD)

Works via the Enterprise Applications → New application → Create your own application → Non-gallery flow. Upload HumHub's SP metadata under Single sign-on → SAML → Upload metadata file. The HumHub auto-detection recognises Azure-AD's http://schemas.microsoft.com/identity/claims/* claim names out of the box.

Other IdPs

Any SAML 2.0–compliant IdP should work via the standard metadata exchange. If you hit an integration issue, please open one at humhub/saml-sso-issues — include the IdP name/version and any error messages from the HumHub log (Administration → Information → Logging).

Users

By default SAML acts as a pure authentication client — new users that sign in through SAML are created the same way as form-based self-registrations. Their profile fields stay editable and admin approval follows the global Require approval before login setting.

The Users section in the SAML settings offers two checkboxes to change this:

• SAML manages user profiles — when enabled, users that sign in via SAML are flagged as SAML-managed. Attributes provided by the IdP become read-only in the user's profile — neither the user nor an admin can change them locally.
• Auto-approve new SAML users — when enabled, new users that sign in via SAML skip the global Require approval before login check. Only effective in combination with SAML manages user profiles.

The flag is only applied to new users created via SAML — existing users keep their original provisioning state.

Encrypted and signed SP messages

Several settings under Security — signed AuthnRequest, signed LogoutRequest / LogoutResponse, encrypted NameID / Assertion — require a HumHub-side X.509 keypair so the SP can sign outgoing messages and decrypt incoming encrypted content. Create a self-signed one:

openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

Paste the contents into the HumHub identity (Service Provider) section of the SAML settings:

• saml.pem → HumHub private key
• saml.crt → HumHub certificate (X.509)

After saving, the IdP needs to learn the new SP certificate too — re-download the SP metadata XML from the HumHub Metadata tab and re-import it on the IdP side.

SAML protocol bindings

SAML defines two HTTP bindings for transporting messages between SP and IdP. HumHub's current support:

Direction	What HumHub supports
SP → IdP (AuthnRequest, login)	HTTP-Redirect only
IdP → SP (Response with Assertion, ACS)	HTTP-POST (standard)
SP → IdP (LogoutRequest)	HTTP-Redirect only
IdP → SP (LogoutRequest / LogoutResponse, SLO callback)	HTTP-Redirect and HTTP-POST (both accepted)

Known limitation: the bundled onelogin/php-saml library does not support HTTP-POST for outgoing AuthnRequest or LogoutRequest. Most IdPs accept both — the limitation only matters when an IdP specifically requires HTTP-POST for these directions (rare, seen with some hardened enterprise ADFS setups and a few large-AuthnRequest signed-flow scenarios).

If you need HTTP-POST for outgoing requests, please open an issue at humhub/saml-sso-issues describing the IdP you're integrating with — implementing it requires custom code outside the OneLogin library and we'll prioritise based on real demand.

Advanced configuration

The settings exposed in the admin form cover the common cases. For exotic deployments, the underlying OneLogin SAML library accepts many more options. Override anything in the SP / IdP / security sections via protected/config/common.php:

<?php
return [
    'modules' => [
        'saml-sso' => [
            'advancedSettings' => [
                'security' => [
                    // Example: relax destination validation if your IdP
                    // rewrites the ACS URL through a proxy.
                    'relaxDestinationValidation' => true,
                ],
                'sp' => [
                    // ...
                ],
                'idp' => [
                    // ...
                ],
            ],
        ],
    ],
];

Reference:

• advanced_settings_example.php
• settings_example.php

advancedSettings is merged on top of the values built from the admin form, so admin-form settings win unless the same key is set in advancedSettings.

System requirements

• HumHub 1.19 or newer.
• PHP 8.2 or newer (HumHub 1.19 baseline).
• PHP extensions: openssl, dom, libxml, zlib. All ship with standard PHP builds on the major Linux distributions.

X.509 handling uses the system OpenSSL library — no separate installation step required.