Skip to content

Single sign-on (SSO)

SSO lets the people in your organization sign in to the console with their identity provider (IdP) credentials. It is configured per tenant, under Settings › Security and access › SSO, and the tenant's own administrator sets it up, without going through support. Once it is switched on, the person types their email on the sign-in screen and the console sends them to their provider.

What it supports

  • OpenID Connect (OIDC) and SAML 2.0. Each tenant has a single SSO configuration, using one of the two protocols.
  • Templates for Google Workspace, Microsoft Entra ID, Okta and OneLogin. A template only fills in the form; afterwards the provider behaves like one typed in by hand. Any other provider that speaks OIDC or SAML 2.0 is configured with Manual.
  • When an SSO sign-in fails, the person sees a message on the sign-in screen that names the reason (for example, an unverified domain or an expired certificate). When the reason is the account (it does not exist, does not belong to this tenant or is deactivated), the message is the same in all three cases and asks them to contact whoever administers their organization. If the reason is not one of the known ones, a generic message appears.

Who can configure it

Only the tenant Administrator and the Organization administrator. The Viewer does not see this screen and, if they try to use it, the console sends them back to their profile. Roles are explained in Roles and permissions.

Setting it up, step by step

  1. Choose the protocol and the template.
    • For OIDC, enter the Issuer URL (the console reads the configuration the issuer publishes and never accepts an issuer that does not match it), the Client ID and the Client secret. The secret is stored encrypted and never shown again; when editing, leave it blank to keep the current one.
    • For SAML, provide the IdP metadata, either as an XML file or from a URL (exactly one of the two sources). The entity ID, the sign-on URL and the signing certificate come from it.
  2. Paste into your provider the two values the console shows: the Reply URL (ACS / callback) and the Service identifier (entity ID / audience).
  3. Enter your organization's email domain and, if needed, additional domains (up to 20 besides the main one, one per line). Sub-domains are not included automatically. A domain already used by another tenant is rejected.

  4. Verify the domain through DNS. Click Generate the record and publish the TXT record shown in the DNS of every allowed domain, named _hodeishield-sso.<domain> and with the same value in all of them. Then click Check now. The record value expires after 7 days. Until every domain is verified nobody can sign in through SSO.

    The verification holds for the domain and for the provider it was made with. You have to generate a new record, verify again and switch SSO back on (it is switched off automatically) when:

    • you add or change a domain (removing one does not require verifying the others again);
    • you change identity provider: for OIDC, the issuer or the endpoints it publishes; for SAML, the entity ID or the signing certificate, for example when you upload new metadata.

    Changing the display name, the role mapping or the client secret does not require verifying again. 5. Test the connection. With Test the connection: - For OIDC, the console re-reads the configuration your issuer publishes and checks that it answers. - For SAML there is nothing to call (the IdP only talks to the console by sending a signed assertion), so the test only checks that the signing certificate is still valid. Anything beyond that needs a real sign-in.

    The console stores the result and the date of the last test, and clears them every time you save the configuration. 6. Switch SSO on with Switch SSO on. It can only be switched on once the domain is verified. You can switch it off at any time. Remove the configuration sends everyone back to password sign-in and removes the accounts' links to that provider (since version 2.48.0).

Saving the configuration, verifying the domain, switching SSO on or off and removing it are recorded in the audit log. A change of identity provider also leaves its own entry.

Who can sign in

The console refuses an SSO sign-in when:

  • SSO is configured but not switched on;
  • the domain is not verified, or the email is not on the authorized domains (the domain has to match exactly; the email is compared without regard to upper or lower case);
  • the provider that signed the login is not the configured one;
  • the IdP's SAML certificate has expired;
  • the account is deactivated or banned, or its organization is inactive (deactivating a person also cuts their SSO access);
  • the person does not have a HodeiShield account yet (SSO never creates accounts: invite them first from Team);
  • the account exists but does not belong to this tenant, even if it is an organization administrator.

Roles

An external directory can only grant the same two roles an invitation can: Tenant administrator or Read-only. Never organization or platform roles.

  • Default role. What a person gets when they carry no mapped group. It starts as Read-only.
  • Mapping by group. Maps groups in your IdP to one of the two roles. The console looks for groups in the roles, groups, memberOf, Role and Group claims. A role outside those two is rejected when you save the mapping; it is never quietly downgraded. If a person carries several mapped groups, the first one that matches applies, not the highest role.
  • Group changes arrive at the next sign-in, because the role is computed on every sign-in.
  • The person must already have access to this tenant. SSO signs them in but never changes the role of someone with an organization role or of someone with access to more than one tenant.

SAML certificate expiry

In SAML, the IdP's signature is checked against a certificate that expires.

  • The SSO screen shows a warning when 30 days or fewer remain, and another once it has expired.
  • A daily check also leaves an entry in the audit log for tenants whose certificate expires within those 30 days or has already expired. It is not sent by email: somebody has to look at the screen or the log.
  • With the certificate expired, nobody can sign in through SSO until you upload fresh metadata. The connection test reports it too.
  • A new certificate counts as a change of provider: after uploading the metadata you have to verify the domain again and switch SSO back on (see step 4).

MFA and SSO

If your tenant requires MFA (under Settings › Security and access › Security, see tenant security policies), a session created by that tenant's SSO is exempt only when the provider vouches for a second factor at that sign-in:

  • SAML: never exempt. The console does not read from the provider which methods the person used.
  • OIDC: exempt only if the id_token of that sign-in carries an amr claim indicating several factors: mfa, otp, hwk, fido, or two factors of different kinds (for example, a password and a software key). The id_token must belong to the sign-in in progress (issued at most 10 minutes earlier).

If the session is not exempt, the console's own second factor applies:

  • If the person already has a TOTP code set up in the console, it is asked for after the SSO sign-in. This happens even if the tenant does not require MFA.
  • If they do not have one and the tenant requires MFA, the console takes them to set it up before they continue.

What is not available today

  • SCIM provisioning is not available yet.
  • There is no "SSO only" mode. Password and second-factor sign-in is not switched off, so an outage at your provider does not lock you out of the console.