When an OpenID Connect (OIDC) login doesn't work, KnowledgeOwl tells you why. Every login attempt is recorded in Recent logins, with a plain-language reason when it fails and the claims your identity provider (IdP) sent. There's no debug mode to turn on. This feature is available on select plans.
Authors with the default Editor role, or a custom role with the Security and access permission Update security settings, can view OpenID Connect login history.
When a reader's login fails, the reader sees your knowledge base's no access page. The reason only appears in your settings, so start there.
Test the connection
If you're connecting your own identity provider app, first check that KnowledgeOwl can reach your identity provider:
- Go to Security and access > Access & SSO and select Manage on the OpenID Connect (OIDC) row.
- Open step 3, Connect {provider}.
- Save any changes, then select Test connection.
If it works, you'll see Connected to your identity provider with the endpoints and signing keys KnowledgeOwl found. If not, you'll see one of the configuration messages in the table below.
Run a test login
A test login checks the whole login, from your identity provider back to KnowledgeOwl, without logging you in to the knowledge base.
- Open the Test login step. If you use KnowledgeOwl's ClassLink app, expand Recent logins below the steps instead.
- Select Run a test login. A new window opens to your identity provider.
- Log in as yourself. When you see Test login finished, you can close that window.
- Back in KnowledgeOwl, the result appears at the top of Recent logins.
Test login with Recent logins
A few things to know:
- Run a test login needs a saved connection (an issuer, client ID, and client secret, or for KnowledgeOwl's ClassLink app, an active district) and no unsaved changes.
- If the test doesn't finish within 10 minutes, you'll see The test login didn't finish. Try again, and complete the login in the window that opens.
- A test login passes even if you don't match your own login restrictions. You'll see Test login passed with a note that you don't match the login restrictions yourself. Readers who don't match them can't log in.
- For your own identity provider app, you need a passed test login before you can turn OpenID Connect on. If you change the issuer, client ID, or SSO ID mapping before turning it on, run the test again.
Recent logins
Recent logins lists login attempts from the past 14 days, up to 50. It's in the Test login step for your own identity provider app, and in the collapsed Recent logins panel below the steps for KnowledgeOwl's ClassLink app. Select the refresh icon next to the heading to load the latest attempts.
Use the filters to narrow the list:
- All: Every attempt.
- Logged in: Readers who logged in.
- Failed: Failed logins, including failed test logins.
- Test logins: Test logins run from your settings.
- District approvals: ClassLink Tenant Administrators who logged in to approve your knowledge base (KnowledgeOwl's ClassLink app).
Each row shows the outcome (Logged in, Test login passed, District approval, or the reason the login failed, in red) and the time. Failed test logins also say Test login. To see older attempts, select the Show more button below the list (it shows how many more, like Show 10 more).
Check the claims
Select Show claims on a row to see exactly what your identity provider sent for that login. Use the claim names to set up your Map reader attributes and Restrict who can log in steps. If a failed row says No claims read, the login failed before KnowledgeOwl got any claims, so the problem is in the connection, not the mapping.
Refused logins keep claim names only
When a login is refused because of who the person is (they don't match your login restrictions, or their ClassLink district isn't approved or wasn't sent), KnowledgeOwl doesn't keep their claim values. You'll only see the claim names, which is enough to set up a restriction. Very large claims, like a long groups list, are also kept as names only.
Failure messages
Here's each reason a login can show in Recent logins, and what to do about it.
Configuration
| Message | What to do |
|---|---|
| OpenID Connect is turned off for this knowledge base. | In the Turn on OpenID Connect step, choose Available or Required for all readers and save. |
| The issuer or client ID is missing. | Enter the issuer and Client ID in step 3 and save. |
| Logins are blocked because this identity provider serves many organizations and there is no restriction to yours. Add one under "Restrict who can log in". | Add a restriction on your tenant ID, district ID, or Workspace domain claim, with your own value. Refer to Configure OpenID Connect SSO. |
| The client secret is missing. Enter it again and save. | In step 3, select Replace next to Client secret, enter the secret from your identity provider app, and save. |
| The IdP's discovery document names a different issuer. Check the issuer URL exactly, including any trailing slash. | Copy the issuer from your identity provider's discovery document (/.well-known/openid-configuration) and select Use a different issuer URL to enter it exactly. For example, Auth0 needs the slash at the end. |
| The issuer must be an https URL. | Use an issuer URL that starts with https://. |
| An IdP endpoint is missing or is not an https URL. | Check your identity provider's endpoints. In OAuth 2.0 mode, check the Authorization endpoint, Token endpoint, and Userinfo endpoint. |
| IdP URLs must use https. | Change every identity provider URL to https://. |
| The IdP's key set has no usable signing keys. | Check your identity provider app's signing key settings, then select Test connection to confirm keys are found. |
| Could not reach the IdP. Check the issuer URL and that the IdP is publicly reachable. | Check the issuer URL for typos. Your identity provider must be reachable from the internet, not only from your internal network. |
The identity provider's answer
| Message | What to do |
|---|---|
| The identity provider refused the login, for example because the reader cancelled or the app isn't assigned to them. | Check that the reader is assigned to your app in your identity provider. If they cancelled, they can try again. |
| The identity provider sent the reader back without a login code. | Readers should start again from the knowledge base or the login link. If it keeps happening, check your identity provider app's settings. |
| The identity provider's token response was invalid. Check the client ID, client secret and redirect URI. | Compare the Client ID and Client secret with your identity provider app, and check that the Redirect URI from step 2 is added exactly. You can also try the other Client authentication option in Advanced options. |
| The ID token is signed with an algorithm we don't accept. | Change your identity provider app to sign ID tokens with a standard asymmetric algorithm, like RS256. |
| The ID token's signature didn't verify. | Check that the issuer is right for this app. If your identity provider recently changed its signing keys, try again shortly. |
| The ID token couldn't be read. | Check that your identity provider app is set up for OpenID Connect. Contact our support team if it keeps happening. |
| The ID token wasn't issued for this login. Readers should start again from the knowledge base. | The reader should go back to the knowledge base and log in again. |
| The ID token was issued to a different app. Check the client ID. | Make sure the Client ID in step 3 matches the identity provider app readers log in with. |
| The ID token is expired, not for this app, or from a different issuer. Check the client ID and the server clocks. | Check the Client ID and issuer. If they're right, check that your identity provider's server clock is correct. |
| The userinfo endpoint described a different user than the ID token. Turn off "Also read claims from the userinfo endpoint" if your IdP's userinfo isn't standard. | In Advanced options, clear Also read claims from the userinfo endpoint, save, and run a test login. |
The reader
| Message | What to do |
|---|---|
| The reader didn't match the login restrictions under "Restrict who can log in". | If the reader should have access, check your restrictions: the claim name, the allowed values, and that you haven't added two rows for the same claim. Select Show claims to see which claim names arrived. |
| The claims had no SSO ID. Check the SSO ID mapping under "Map reader attributes". | Map SSO ID to a claim your identity provider sends, or leave it blank to use sub. Select Show claims to see what was sent. |
| This reader is disabled in KnowledgeOwl. | If they should have access, re-enable the reader on the Readers page. |
| The reader belongs to a different account. | Contact our support team. |
The login itself
| Message | What to do |
|---|---|
| The login expired or was already used. Readers should start again from the knowledge base. | The reader should go back to the knowledge base and log in again, without using the browser's back button or a bookmarked identity provider page. |
| The login was finished in a different browser than it started in. | The reader should start and finish the login in the same browser. |
| The login was finished on a different knowledge base address than it started on. | Readers should use your knowledge base's main address, or the login link exactly as KnowledgeOwl shows it. |
| Logins are temporarily unavailable. Try again shortly. | Try again in a few minutes. Contact our support team if it continues. |
| The test login link expired or was already used. Start a new test from your settings. | Select Run a test login again. |
| Too many failed logins from one network, so they were paused for a while. | Wait a while and try again. Fix the cause of the earlier failures first. |
KnowledgeOwl's ClassLink app
| Message | What to do |
|---|---|
| ClassLink didn't say which district the reader is from. | Contact our support team. |
| The reader's ClassLink district isn't approved for this knowledge base. Add it, and ask its Tenant Administrator to approve it. | In Add KnowledgeOwl to your districts, add the district's ClassLink tenant ID and send its Tenant Administrator the approval instructions. If the district is listed as inactive, make it active. Refer to Set up KnowledgeOwl's ClassLink app. |
| The login took too long to reach the knowledge base, or was already used. Readers should start again. | The reader should open the KnowledgeOwl app in ClassLink again. |
If you see The login failed followed by a code in parentheses, contact our support team and include the code.
Still stuck?
If you've tried the steps above and logins still fail, contact our support team. Let us know what Recent logins shows, and when the login was tried.