Troubleshoot single sign-on

When Hook turns a learner away, their screen names the kind of problem in plain words and shows a reference code. It never shows the detail. The cause is on your settings page or in your provider, and this page matches the screen to it.

Check a learner before they try

Go to Settings, then Single sign-on. The Learner readiness card counts how many of your active learners can sign in today and why the rest can't. Enter an email under Check a learner to walk one person through every check without signing anyone in.

A learner with nothing assigned can still sign in. They see an empty dashboard until you assign training.

A learner can't sign in

"You're not set up as a learner yet." Hook has no learner with the email your provider sent. Signing in never creates one. Check that the person exists in Users and groups with that email; directory sync or a CSV import adds them. Check a learner on the SSO settings page walks the same steps for one address.

The email your provider sends does not match. Hook matches the email in the sign-in against learners in your organization, and also the sign-in name (UPN) your Microsoft Entra directory sync brings in. When that sync covers the same tenant, Hook also recognises the person by their Entra account, whatever address the sign-in carries. Otherwise a provider that sends a personal address, or nothing at all, does not match. On Entra, Hook uses user.mail, or the UPN when user.mail is empty; check that this address is the one the learner is enrolled under. On Okta and Google, set the NameID format to email.

"Your access to training is turned off." The learner was deactivated or removed in Hook, or their earlier sign-in was revoked when a connection was removed. Access ends on the next request, even if your provider still lets them in.

"Your account needs your administrator's attention." Hook could not tell which learner the sign-in belongs to, so it does not guess. There are three causes:

• More than one learner answers to the address your provider sent, usually because it is one person's email and another person's directory sign-in name. Tidy the addresses in your directory; Check a learner shows which learners share one.
• Your Microsoft Entra directory sync matches the person to a different learner than their email does. Fix the email or the sync so both name the same learner.
• The Entra user signing in is not the one this learner first signed in as, for example because a mailbox was given to someone new, or an account was deleted and created again. Hook refuses it so the new person cannot open the previous person's training.

Check a learner cannot see the last two causes. Send support the reference code from the learner's screen; see What to send support.

"We couldn't sign you in." The connection is turned off or still in setup, or your provider rejected the sign-in. A disabled connection refuses every sign-in, and one that was never opened for testing does too. A wrong Entity ID or ACS URL in the provider's application, or a user not assigned to it, fails before Hook is involved; your provider's own sign-in logs show this.

Hook refuses the metadata URL

Metadata URLs must be public HTTPS addresses. Hook refuses plain HTTP, addresses with a username or password in them, and anything that resolves to a private network, because Hook itself fetches the metadata. If your provider only publishes metadata on an internal address, download it and paste the contents instead.

The certificate badge is amber or red

Your provider's signing certificate is within 30 days of expiry (amber), within a week or already expired (red). Once it expires, every sign-in fails.

For providers connected by metadata URL, rotate the certificate at the provider, then use Replace metadata with the same URL. Until you do, sign-ins are checked against the old certificate and fail. For Google Workspace or pasted metadata, download fresh metadata and use Replace metadata. See Manage your SSO connection.

Single sign-on is required and the provider is down

Nobody can open their training until the provider is back, because emailed links route into the provider too. Two ways out:

• Switch the mode to available. Emailed links work again immediately, for emails already sent as well as new ones. Switch back to required when the provider recovers.
• Ask support for recovery access. Hook support can suspend the requirement for a bounded window that ends on its own, which is useful when you would rather not touch the configuration during an incident.

A test sign-in signed me out of Hook

The test signs in at your provider inside whichever browser opens the link, and Hook signs that session out again when it finishes, which takes your admin session with it in the same browser. Sign back in as an admin, copy the test link, and open it in a private window or another browser.

The test says there was no email address

Your provider answered, but with no address in it at all, so Hook could not match any learner and the test does not count. On Entra this means neither user.mail nor the UPN arrived, usually because the name claim was removed or renamed under Attributes & Claims. Add an attribute that carries the user's email address to the SAML application, then run the test again.

The "required" option is unavailable

Required needs a passed test sign-in on the connection, and the connection must be active. Run a test sign-in in a private window, then click Activate. The option opens once both are true.

What to send support

Email support@hooksecurity.co with your organization name, the connection name, which provider you use, the email of the learner who could not sign in, and the reference code from their screen. If your settings page shows a failed check, include the wording of the notice. For provider-side errors, a screenshot of the provider's sign-in log entry is the fastest way to a fix.

Related