SAML/SSO with Microsoft Entra ID

• Administration abilities within Microsoft Entra.
• Super-admin user role within Hudu.
• All users are provisioned in Entra with the same exact email address. We don't create new user accounts with SSO.
• Microsoft Account with Entra ID Premium activated.
• If JIT Provisioning is not enabled, ensure that the users have already been created in Hudu before starting this process.

Just-in-Time (JIT) Provisioning

Hudu supports Just-in-Time (JIT) provisioning for users signing in through SSO. When a user logs in for the first time via your identity provider, their account will be automatically created based on the attributes and group memberships passed during authentication.

How to Enable SSO

• Login to Hudu and click the Admin tab on the top toolbar.
• Click Security.
• Click Configure SAML/SSO.
• Turn Single Sign-On to On.
• Enter SAML details. See the relevant section below on how to fill this information out.
• Click Save.

Configuring Entra ID

• In Microsoft Azure:
  • Navigate to Microsoft Entra ID → Enterprise Applications.

• Click to add a + New Application → Create your own application.

• On the next screen, give your application a name, and click on Integrate any other application you don't find in the gallery (Non-gallery).
  • If you don't have Entra Premium, you won't be able to add a name.

• Click Users and Groups and assign users to this application. Click + Add User to add users.
  • Remember, users must have the same exact e-mail address as their Hudu account e-mail address.

• Then, click Single sign-on to configure SSO. Click SAML.

• Basic SAML Configuration:
  • Click the Pencil Icon next to Basic SAML Configuration.

• Enter the following in the fields:
  • Identifier (Entity ID): Enter your Hudu URL, e.g. https://docs.mywebsite.com
  • Reply URL (Assertion Consumer Service URL): Enter https://docs.mywebsite.com/saml/consume
  • Sign-on URL: Enter https://docs.mywebsite.com
  • Relay State: You can skip filling this in.
  • Logout URL: Enter a URL where Hudu can redirect users after they sign out.
  • Make sure to replace docs.mywebsite.com with your URL and subdomain. There is also no trailing slash at the end of the URL.

• User Attributes & Claims:
  • Click the Pencil Icon next to the User Attributes & Claims box.

• Click on Unique User Identifier (Name ID).

• If it's not already, set the Source attribute to user.userprincipalname and click Save.
• Please note that the user's UPN must match their email to use this source attribute.

• SAML Signing Certificate:
  • Click the Pencil Icon next to the SAML Signing Certificate box.

• Enter an e-mail to receive notifications and click Save.

• Final Setup:
  • Finally, the 4th box that says Set up <application-name> will contain the information that needs to be inputted into your Hudu admin area → Security → SSO Settings.

Configuring Hudu

• In Hudu, with a user role of Admin or Super Admin:
  • Navigate to your Hudu admin area → Security → SAML/SSO Configure.
• Provide Identity Provider (IdP) information:
  • This is the information from the final setup step above.
  • SAML Issuer URL: This is what Entra ID calls their "Microsoft Entra Identifier." Copy this exactly into Hudu.
    • This SHOULD include the trailing "/".
  • SAML Login Endpoint: This is what Entra ID calls their "Login URL." Copy this exactly into Hudu.
  • SAML Logout Endpoint: This is what Entra ID calls their "Logout URL." Copy this exactly into Hudu.
  • SAML Fingerprint:
    • Download and copy the PEM certificate and paste it into the SAML Certificate field. Make sure there is no extra space trailing at the end!
      • To locate the PEM certificate download, select the pencil icon for SAML certificates and click the three dots in the corner. Select PEM certificate download.

• SAML Certificate: This is provided by Entra ID, and should be the same certificate used to configure the fingerprint; copy this exactly.

SAML ARN: This signifies the authentication context Hudu provides to the IdP. AuthnContext is the method a user signs in with (for example, password or passwordless). Requested authentication context may be required by your IdP, but it is typically optional.

• Click Enable Single Sign-On.
• Hit Update SAML Details and SAML should now be activated.

Testing SAML

• Open an incognito or private browsing window and navigate to your Hudu URL.
• Enter the email address of a user who is required to use SSO and click Next. You should be redirected to Microsoft.
• If you're signed in to Hudu after authenticating, your SAML configuration is working.
• You can also click Test SAML from within your Hudu SAML app in Entra ID.
• Before requiring SSO, make sure every admin account exists in your Entra tenant with the same email address as their Hudu account.

Additional Settings

FAQ