How SAML SSO Works
SAML (Security Assertion Markup Language) is a standard that enables secure authentication between applications. With SAML SSO, users can sign in to multiple web applications using one account, without having to manage separate usernames and passwords for each service.
SAML works by securely exchanging authentication data between two parties:
Identity Provider (IdP)
The service that verifies user identities. Common examples include Azure AD, Okta, and OneLogin.Service Provider (SP)
The application requesting authentication. In this case, the service provider is Hudu.
What Users Experience
Once SAML SSO is enabled, everyone signs in to Hudu the same way, regardless of role or authentication method. Users enter their email address on the login page, and Hudu routes them to the right sign-in method.
Users who are required to use SSO are sent to your identity provider. After the identity provider authenticates them, Hudu matches the account by email address and signs them in.
Users who are exempt from SSO, including portal users, are asked for their Hudu password.
There is no option for most users to choose between SSO and a password. If SSO fails for a user who isn’t exempt, they can’t sign in with a password instead. Admins and super admins always have the option to sign in with their Hudu password.
Setup Guides
To set up SAML SSO using common identity providers, please refer to their respective guides below!
How to Enable SSO
The following steps outline how to configure SAML Single Sign On in Hudu. This generic setup works with any identity provider that supports SAML 2.0.
• Log in to Hudu and click the Admin tab in the top toolbar
• Click Security
• Click Configure SAML or SSO
• Enter your SAML configuration details
• Click Enable Single Sign On
• Click Update SAML Details to activate SAML authentication
Configuring the Identity Provider Side
Configure the following values within your identity provider.
Identifier (Entity ID)
Enter your Hudu URL, for example 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
This field can be left blank
Logout URL
Enter a URL where users should be redirected after signing out of Hudu
Make sure to replace docs.mywebsite.com with your actual Hudu URL and subdomain. Do not include a trailing slash at the end of any URL.
Configuring the Hudu Side
Enter the following values in Hudu using the information provided by your identity provider.
SAML Issuer URL
The unique identifier for your identity provider. This may also be labeled as Identity Provider Entity ID, IdP, Issuer, or IdP Metadata URL.
SAML Login Endpoint
The endpoint used to initiate login requests. This may also be called the SSO Endpoint, Sign on URL, Remote Login URL, SAML 2.0 URL, Identity Provider Sign in URL, or Single Sign On Service URL.
SAML Logout Endpoint
The endpoint users are redirected to after signing out. This may also be referred to as the SAML Logout URL, Identity Provider Sign out URL, or Single Sign Out Service URL.
SAML Fingerprint
Provided by your identity provider and sometimes referred to as a thumbprint.
SAML Certificate
A base 64 encoded X.509 certificate provided by your identity provider. Ensure there is no trailing whitespace when pasting the certificate.
SAML ARN
Defines the authentication context that Hudu requests from the identity provider. This specifies how the user was authenticated.
If you do not pass a requested authentication context, the identity provider will authenticate the user without specifying the method used. This option is recommended if your users authenticate using passwordless methods.
If Password is specified, the identity provider will authenticate users using a username and password.
If PasswordProtectedTransport is specified, authentication will occur using a username and password secured with SSL or TLS.
Signing Algorithm
Signing Algorithm Options
Hudu supports both SHA 1 and SHA 256 signing algorithms.
SHA 256 Recommendation
SHA 256 is recommended when supported by your identity provider.
Enabling SHA 256
To use SHA 256, ensure the certificate fingerprint is provided in SHA 256 format and enable Use SHA 256 within Hudu.
Testing SAML
• Open an incognito or private browsing window.
• Navigate to your Hudu URL.
• On the login page, enter the eamil address of a user who is required to use SSO and click Next.
• You should be redirected to your identity provider; if login is successful, your SAML configuration is working.
Please note: Before requiring SSO, make sure every admin account exists in your identity provider with the same email address as their Hudu account. We recommend keeping an existing Hudu session open in another browser until you've confirmed SSO works. If something is misconfigured, you can correct it without being locked out.
Exempt Groups from SSO
Hudu allows specific groups to be exempt from SSO. Members of exempt groups sign in with their Hudu password.
Portal users are always exempt, and admins and super admins always have the option to sign in with their Hudu password.
The exception is an admin whose account isn’t in your SSO tenant when SSO is required. That admin is locked out until they’re added to the tenant.