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.

Since version 2.4.0, 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. See Attribute auto-detection for the exact lookup order.

Attribute auto-detection

For each standard field, HumHub checks the attribute names below in the listed order and uses the first one that is present in the SAML assertion with a non-empty value. Multi-valued attributes are reduced to their first value.

Rules:

• An Attribute mapping line for a field (e.g. username=...) always wins and disables the auto-detection for that field, even if the mapped attribute is missing from the assertion. Remove the line to re-enable the auto-detection.
• Installations upgraded from versions before 2.4 usually still contain the former default mapping (username=urn:oid:0.9.2342.19200300.100.1.1 etc.). Check whether these lines match the attributes your IdP actually sends.
• The SAML NameID is always used as id when the assertion contains one, so the auto-detection of id only applies to assertions without a NameID. Add an id=... line to the Attribute mapping to use another attribute.
• A NameID that is a valid e-mail address is used as email and takes precedence over the auto-detected e-mail attributes (e.g. mail). Add an email=... line to the Attribute mapping to use a specific attribute instead.
• Enable Log available SAML attributes to see which attribute names your IdP sends.

id

1. urn:oid:1.3.6.1.1.1.1.0 (LDAP uidNumber)
2. http://schemas.microsoft.com/identity/claims/objectidentifier (Entra ID)
3. uidNumber
4. objectGUID
5. objectguid
6. subjectid
7. userid
8. id

email

1. urn:oid:0.9.2342.19200300.100.1.3 (LDAP mail)
2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress (AD FS)
3. http://schemas.microsoft.com/identity/claims/email (Entra ID)
4. mail
5. email
6. emailAddress
7. EmailAddress
8. email_address

username

1. urn:oid:0.9.2342.19200300.100.1.1 (LDAP uid)
2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn (AD FS UPN)
3. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name (AD FS name)
4. http://schemas.microsoft.com/identity/claims/preferred_username (Entra ID)
5. http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname (AD FS / Windows)
6. http://schemas.goauthentik.io/2021/02/saml/username (Authentik)
7. sAMAccountName
8. samaccountname
9. uid
10. username
11. userName
12. UserName
13. preferred_username

Because the UPN comes first, an IdP that sends both UPN and a plain user name (e.g. AD FS, Authentik) results in usernames like john@example.com. To use the plain name instead, add a mapping such as username=http://schemas.goauthentik.io/2021/02/saml/username.

If no username is found, it is generated from the e-mail address when SAML manages user profiles is enabled. Otherwise the user has to choose a username on the registration form.

firstname

1. urn:oid:2.5.4.42 (LDAP givenName)
2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname (AD FS)
3. givenName
4. givenname
5. GivenName
6. firstname
7. firstName
8. first_name

lastname

1. urn:oid:2.5.4.4 (LDAP sn)
2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname (AD FS)
3. sn
4. surname
5. Surname
6. lastname
7. lastName
8. last_name

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.