Understanding SAML/SSO

Hudu supports authentication through a central identity provider using single sign-on (SSO). SSO is a secure, time-saving sign-in method that lets users access multiple applications with a single set of credentials and sign out instantly with one click.

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 managing 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 Microsoft Entra ID, 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 sign-in 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.

Most users can't 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 are offered a password option if SSO fails, and they can also sign in with their Hudu password at any time from a separate sign-in page, described below.

Setup guides

To set up SAML SSO with a common identity provider, refer to its guide below.

Google Admin Console	Entra ID	JumpCloud
Okta	AuthAnvil (Passly)	OneLogin

How to enable SSO

The following steps outline how to configure SAML SSO in Hudu. This generic setup works with any identity provider that supports SAML 2.0.

1. Sign in to Hudu and click the Admin tab in the top toolbar.
2. Click Security.
3. Click Configure SAML or SSO.
4. Enter your SAML configuration details.
5. Click Enable Single Sign On.
6. Click Update SAML Details to activate SAML authentication.

Configuring the identity provider side

Configure the following values in your identity provider.

Identifier (Entity ID)
Your Hudu URL, for example https://docs.mywebsite.com

Reply URL (Assertion Consumer Service URL)
Your Hudu URL followed by /saml/consume, for example https://docs.mywebsite.com/saml/consume

Sign on URL
Your Hudu URL, for example https://docs.mywebsite.com

Relay state
This field can be left blank.

Logout URL
The URL users should be redirected to after signing out of Hudu.

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 sign-in 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 called the SAML Logout URL, Identity Provider Sign out URL, or Single Sign Out Service URL.

SAML Fingerprint
Provided by your identity provider and sometimes called a thumbprint.

SAML Certificate
A base64-encoded X.509 certificate provided by your identity provider. Make sure there is no trailing whitespace when pasting the certificate.

SAML ARN
Defines the authentication context Hudu requests from the identity provider, which specifies how the user was authenticated.

• None: The identity provider authenticates the user without specifying the method used. This option is recommended if your users authenticate with passwordless methods.
• Password: The identity provider authenticates users with a username and password.
• PasswordProtectedTransport: Authentication uses a username and password secured with SSL or TLS.

Signing algorithm

Hudu supports both SHA-1 and SHA-256 signing algorithms. We recommend SHA-256 when your identity provider supports it. To use SHA-256, make sure the certificate fingerprint is provided in SHA-256 format and enable Use SHA 256 in Hudu.

Testing SAML

1. Open an incognito or private browsing window.
2. Navigate to your Hudu URL.
3. On the sign-in page, enter the email address of a user who is required to use SSO and click Next.
4. You should be redirected to your identity provider. If sign-in is successful, your SAML configuration is working.

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. Admins and super admins are offered a password option if SSO fails, and can sign in with their Hudu password from the password sign-in page below.

Signing in with a password when SSO is enabled

Admins and super admins can sign in with their Hudu email and password from a separate sign-in page. This is useful when an admin's account isn't in your identity provider, when your identity provider is unavailable, or when your SSO configuration has an error. To open it, add /?sso_disabled=true to the end of the URL you normally use for Hudu.

For example: https://docs.mywebsite.com/?sso_disabled=true

Things to know

• Only admins and super admins can sign in from this page. Any other role will see "Incorrect email/password combination," even if the password is correct.
• Admins created through just-in-time (JIT) provisioning can't sign in from this page.
• If 2FA or Duo is required on your instance, you'll still be asked to complete it after entering your password.
• If you don't know your password, use the forgot password link on the page to reset it.
• If SSO isn't enabled on your instance, this URL takes you to the standard sign-in page.