SAML/SSO with Microsoft Entra ID

One of the SAML identity providers (IdP) you can use is Microsoft Entra ID.

Before you set up Entra ID, read Understanding SAML/SSO for basic concepts and tips.

To set up SSO with Entra ID, you need:

  • Admin permissions in Microsoft Entra ID.
  • The Super Admin role in Hudu.
  • Microsoft Entra ID P1 or P2 (required for non-gallery SAML apps).
  • Matching email addresses: each user's email in Entra must match their Hudu account email exactly (including the Name ID / UPN you send in SAML).
  • If Just-in-Time (JIT) provisioning is not enabled, create users in Hudu before they sign in with SSO. Hudu does not create accounts on SSO login unless JIT is enabled.

Just-in-Time (JIT) Provisioning

Hudu supports Just-in-Time (JIT) provisioning for users who sign in through SSO. On a user's first successful SSO login, Hudu can create their account from the attributes and group memberships sent during authentication.

    Visit Just-in-Time (JIT) Provisioning for additional information on enabling JIT provisioning in Hudu.

How to Enable SSO in Hudu

Open the SAML settings in Hudu first, then configure Entra ID, then return here to paste the IdP values.

  • Sign in to Hudu and open the Admin tab.
  • Go to Security.
  • Next to SAML/SSO, click Configure.
  • Set Single Sign-On to On. (The page saves when you change Off/On.)
  • Leave the IdP fields for now. Complete Configuring Entra ID, then finish Configuring Hudu and click Save.

Configuring Entra ID

Microsoft Entra ID blade in the Azure portal

Enterprise applications in Microsoft Entra ID

  • Click + New application → Create your own application.

New application button in Enterprise applications

Create your own application option

  • Name the application, select Integrate any other application you don't find in the gallery (Non-gallery), then create it.
    • Non-gallery SAML SSO requires Microsoft Entra ID P1 or P2. Without Premium, you may be blocked from creating or configuring this app.

Create a non-gallery enterprise application

  • Open Users and groups and assign users (or groups) to the application. Use + Add user/group as needed.
    • Each assigned user's email in Entra must match their Hudu account email exactly.

Assign users and groups to the enterprise application

  • Open Single sign-on, then select SAML.

Select SAML as the single sign-on method

  • Basic SAML Configuration
    • Click the pencil icon next to Basic SAML Configuration.

Edit Basic SAML Configuration

  • Enter the following values. Replace docs.mywebsite.com with your Hudu hostname. Do not include a trailing slash on these URLs.
    • Identifier (Entity ID): https://docs.mywebsite.com
    • Reply URL (Assertion Consumer Service URL): https://docs.mywebsite.com/saml/consume
    • Sign on URL: https://docs.mywebsite.com
    • Relay State: Leave blank.
    • Logout URL: Leave blank. Hudu does not require an SP logout URL in this field.
  • Attributes & Claims
    • Click the pencil icon next to Attributes & Claims (some tenants still show this as User Attributes & Claims).

Edit Attributes and Claims

  • Open Unique User Identifier (Name ID).

Unique User Identifier Name ID claim

  • Set Source attribute to user.userprincipalname (if it is not already), then click Save.
  • The user's UPN must match their Hudu email when you use this source attribute.

Name ID source attribute set to user.userprincipalname

  • SAML Certificates
    • Click the pencil icon next to SAML Certificates.
    • Enter a notification email for certificate expiration, then click Save.

Edit SAML Signing Certificate

SAML certificate notification email settings

  • Collect IdP values for Hudu
    • In the Set up <application-name> section, copy Login URL, Microsoft Entra Identifier, and Logout URL. You will paste these into Hudu in the next section.

Configuring Hudu

  • In Hudu, as a Super Admin, go to Admin → Security → Configure (next to SAML/SSO).
  • Enter the Identity Provider (IdP) values from Entra:
    • SAML Issuer URL: Entra's Microsoft Entra Identifier. Paste it exactly.
      • This value should include the trailing /.
    • SAML Login Endpoint: Entra's Login URL. Paste it exactly.
    • SAML Logout Endpoint: Entra's Logout URL from the Set up <application-name> section. Paste it exactly. (This is Entra's IdP logout URL, not the optional Logout URL field in Basic SAML Configuration.)
    • SAML Fingerprint: Copy the thumbprint from the SAML Certificates section in Entra and paste it into Hudu.
    • SAML Certificate: Download the PEM certificate from Entra and paste the full contents into Hudu. Do not leave a trailing space after the certificate.
      • To download the PEM certificate: open the pencil icon for SAML certificates, open the three-dot menu, then choose the PEM download option.

Download PEM certificate from SAML Certificates in Entra ID

   The Use SHA-256 checkbox refers to the fingerprint, not the certificate. Entra ID always displays a SHA-1 thumbprint, even when the certificate itself uses SHA-256. If you paste the thumbprint as shown in Entra ID, leave Use SHA-256 unchecked.

How to use a SHA-256 fingerprint instead

To use a SHA-256 fingerprint, recalculate it from the PEM certificate:

  • Download the PEM certificate from Entra ID.
  • Open OneLogin's fingerprint calculator and go to Fingerprint → Calculate X.509 Fingerprint.
  • Paste the PEM certificate into the calculator.
  • Select SHA-256, then copy the fingerprint (formatted or unformatted).
  • Paste it into the SAML Fingerprint field in Hudu.
  • Check Use SHA-256.

    If Use SHA-256 is checked but the fingerprint field contains the SHA-1 thumbprint from Entra ID, SSO will fail.

   -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- should be included.

Hudu SAML SSO settings filled with Entra ID values

SAML ARN: Controls the requested authentication context Hudu sends to the IdP (RequestedAuthnContext). This is the method the IdP should use to authenticate the user (for example, password). Many IdPs treat this as optional; choose the option that matches how your users sign in.

Do not pass RequestedAuthnContext

Hudu does not request a specific authentication method. Use this if any users sign in to Entra with passwordless methods.

urn:oasis:names:tc:SAML:2.0:ac:classes:Password

Requests that the IdP authenticate the user with a username and password.

urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

Requests that the IdP authenticate the user with a username and password over SSL/TLS.

  • Click Save. You should see a confirmation that SAML was updated.

Testing SAML

  • Open an incognito or private window and go to your Hudu URL.
  • Enter the email of a user who should use SSO, then click Next. You should be redirected to Microsoft.
  • If you land in Hudu after authenticating, SAML is working.
  • You can also use Test from the SAML single sign-on page for your Hudu app in Entra ID.
  • Before you require SSO for non-admins, confirm every admin exists in your Entra tenant with the same email as their Hudu account and is assigned to the enterprise application.

Additional Settings

Exempt groups from SSO

You can exempt groups from SSO. Members of exempt groups sign in with their Hudu password. Portal users are always exempt. Admins and above are offered a password option if SSO fails, so a broken SAML config does not lock out administrators.

If an admin is not in your Entra tenant and needs to sign in with a password without going through SSO, append /?sso_disabled=true to your instance URL (for example, https://docs.mywebsite.com/?sso_disabled=true). This break-glass page is for admins only.

SSO exempt groups settings in Hudu

Renewing a rotated or expiring signing certificate

Entra signing certificates expire and can be rotated. When that happens, update both Hudu fields together:

  • In Entra ID, download the new PEM certificate from SAML Certificates.
  • In Hudu, go to Admin → Security → Configure (next to SAML/SSO).
  • Paste the new PEM certificate into SAML Certificate.
  • Update SAML Fingerprint with the new certificate's thumbprint from Entra. If you use SHA-256, recalculate the SHA-256 fingerprint from the new certificate instead.
  • Click Save.

    Updating only the SAML Certificate field without also updating the SAML Fingerprint will break SSO. Both fields must reference the same certificate.

FAQ

Why don't I see a Sign in with SSO button anymore?

Hudu routes every user by email. Enter your email on the login page and click Next. Hudu then sends you to your identity provider or asks for your password, depending on how your account is set up.

Entra ID x509 multi-factor error

In Hudu, set SAML ARN to Do not pass RequestedAuthnContext.

Entra is rejecting the requested authentication context. This usually happens when SAML ARN is set to urn:oasis:names:tc:SAML:2.0:ac:classes:Password or urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport, but the user signs in with a passwordless method.

Single Sign-On Authentication Failed

If you see “Single Sign-On Authentication Failed,” the certificate fingerprint is usually wrong. First confirm that Use SHA-256 matches the fingerprint you entered. If you are using the thumbprint as shown in Entra, leave the box unchecked. If that does not fix it:

  • Open the SAML Certificates section of your enterprise application.
  • Click Edit, then open the three-dot menu in the modal.
  • Download the PEM certificate.
  • Use a fingerprint tool to calculate the correct fingerprint.
  • Enter the corrected fingerprint in Hudu SSO settings.
  • Click Save, then test again.
I'm sent to a Microsoft page and can't sign in to Hudu

This usually means the user's email is missing from your Entra tenant or is not assigned to the Hudu enterprise application. Hudu sends the user to Microsoft, and Microsoft may not return an error Hudu can show.

Add the user to Entra with the same email as their Hudu account, assign them to the Hudu application under Users and groups, then have another admin confirm the account in Hudu if needed.

If you are an admin and cannot complete SSO, use https://your-hudu-url/?sso_disabled=true to sign in with your Hudu password, then fix the Entra assignment.

Was this article helpful?
1 out of 1 found this helpful