Skip to content
Hawzu Docs

Single Sign-On Setup

6 min read

This page walks through connecting a specific identity provider. For what single sign-on does once it is connected — enforcement, automatic joining, and SCIM — see Security & Access.

Single sign-on is available on every plan. You need a workspace manager or owner role, and a verified email domain.

Before you start

Section titled “Before you start”

  1. Verify your company’s email domain in Settings → Security & Access. A provider may only sign in addresses on a domain the workspace has verified.

  2. Decide which protocol to use. If your provider offers both, OpenID Connect is simpler: no certificate to rotate. Google Workspace custom apps are SAML.

  3. Have a second way in while you configure. An owner with two-factor authentication keeps password access even once single sign-on is required.

Okta (OpenID Connect)

Section titled “Okta (OpenID Connect)”

  1. In Hawzu, open Settings → Security & Access → Single sign-on, choose OpenID Connect, and copy the Redirect URI.

  2. In the Okta Admin Console, create an app integration: OIDC — OpenID Connect, application type Web Application.

  3. Paste Hawzu’s redirect URI into Sign-in redirect URIs, and set Login initiated by to App only. Sign-in always starts at Hawzu, so an Okta dashboard tile would have nowhere to go.

  4. Assign the app to the people or groups who should reach this workspace.

  5. From the app’s General tab, copy the Client ID and Client secret. Your issuer is your Okta domain, https://your-org.okta.com — or the custom authorization server you use, such as https://your-org.okta.com/oauth2/default.

  6. Paste the issuer, client ID and client secret into Hawzu and save.

  7. Choose Test sign-in, then Switch on.

Hawzu reads the ID token your provider returns and does not call the userinfo endpoint, so the token itself has to carry the person’s email address. Okta’s org authorization server sends it with the email scope; a custom authorization server sends whatever claims you have configured on it. If the test comes back saying no email address was sent, add an email claim to that authorization server, or use the org one.

Microsoft Entra ID (OpenID Connect)

Section titled “Microsoft Entra ID (OpenID Connect)”

  1. In Hawzu, choose OpenID Connect and copy the Redirect URI.

  2. In the Entra admin center, go to App registrations → New registration. Add the redirect URI under platform Web.

  3. Under Certificates & secrets, create a client secret and copy its value — Entra shows it once.

  4. Your issuer is https://login.microsoftonline.com/<tenant-id>/v2.0, using your own tenant id. The shared /common, /organizations and /consumers endpoints aren’t accepted, because they let in users from any Microsoft tenant.

  5. Paste the issuer, application (client) ID and client secret into Hawzu, save, test, and switch it on.

If Entra sends no email claim, Hawzu falls back to the user principal name when it is an address. Make sure the people you assign have a mail address or a UPN that matches your verified domain.

SAML: which order to do it in

Section titled “SAML: which order to do it in”

Every SAML provider asks for Hawzu’s ACS URL and audience, and both contain the connection’s own id — so they do not exist until the connection does. Hawzu, in turn, will not create one without the provider’s entity ID, sign-in URL and certificate. Break the circle with placeholders:

  1. In the provider, create the application with a placeholder ACS URL and audience. Anything will do; they are replaced in step 3.

  2. Copy the provider’s entity ID, sign-in URL and signing certificate into Hawzu’s SAML form and save. Paste the certificate, or use Upload certificate file for the one it downloaded — PEM, Base64 and raw DER downloads are all understood.

  3. Copy the ACS URL and service provider entity ID the card now shows over the placeholders in the provider.

Hawzu takes the address from an email attribute and falls back to the NameID when that is an address, so send an email attribute, set the name ID format to the email address, or both. First and last name attributes are optional and only fill in a display name.

Get step 3 wrong and the test says the response went to a different connection’s address — every connection has its own ACS URL.

Google Workspace (SAML)

Section titled “Google Workspace (SAML)”

Google Workspace custom apps use SAML, so they follow the order above.

  1. In the Google Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app, using placeholders for the service provider details for now.

  2. Download or copy the SSO URL, Entity ID and Certificate Google shows, and put them into Hawzu’s SAML form.

  3. Copy Hawzu’s ACS URL and entity ID back into Google’s service provider details. Set the name ID format to EMAIL.

  4. Add attribute mappings so Google sends the primary email, first name and last name.

  5. In Hawzu, test and switch it on. Turn the app ON for everyone — or for the right organizational units — in Google, or sign-in fails with an access denial.

Any other provider

Section titled “Any other provider”

Hawzu works with any provider that speaks OpenID Connect or SAML 2.0.

For OpenID Connect, Hawzu needs an issuer URL that publishes /.well-known/openid-configuration, a client ID and a client secret, and uses the authorization code flow with PKCE. ID tokens must be signed with RS256, PS256 or ES256.

For SAML 2.0, Hawzu is the service provider. It sends the sign-in request; sign-in started from the identity provider (IdP-initiated) isn’t supported. Assertions must be signed, SHA-1 signatures are refused, and encrypted assertions are not supported; turn assertion encryption off, since they are signed either way.

Troubleshooting

Section titled “Troubleshooting”

The test says the record or configuration could not be read. Check the issuer URL is exactly what your provider publishes, with no trailing path of your own.

The test says the identity provider refused the client. The client ID, client secret or redirect URI does not match what the provider has. Re-copy the secret: most providers show it once.

The test says the address is not on a verified domain. The person who tested signed in with an address on a domain this workspace has not verified. Verify that domain, or test with an address on one you have.

The test says no email address was sent. For OpenID Connect, the ID token carried no address: add the email scope, or the email claim, to the application or authorization server — Hawzu does not fall back to the userinfo endpoint. For SAML, the assertion had neither an email attribute nor a NameID that is an address: add an email attribute statement, or set the name ID format to the email address.

The test says the address is unverified. Your provider marked the address email_verified: false — usually an account that was created but never activated. Activate it there, or test with somebody who has.

Sign-in works but says the address is not a member. Single sign-on proves who somebody is; it does not by itself grant membership. Either invite them, or turn on automatic joining in the single sign-on card.

Somebody is signed in as the wrong person. The identity provider decides which account it asserts, and one with a session already open answers with that person whatever address was typed in Hawzu — the address is only a hint, and the provider ignores it rather than showing a sign-in form.

Hawzu notices: when the account that comes back is not the one that was typed, it names the account before going anywhere and offers to sign in as the address that was asked for, which makes the provider authenticate again.

A SAML sign-in says the response could not be verified. The signing certificate is usually the cause — providers rotate them. Paste the current one, or upload the file your provider downloaded; you can hold several during a rollover.

A SAML sign-in says the response went to a different connection’s address. The sign-on URL in your identity provider is not this connection’s ACS URL — usually a placeholder left over from setup, or the address of a connection that was deleted and made again. Copy the ACS URL from the single sign-on card and paste it over the one in the provider. Every connection has its own.

Next Steps

Section titled “Next Steps”