If your school district has created its own OpenID Connect app in ClassLink, you can connect it to your knowledge base so readers log in with their ClassLink accounts. This setup works best for a single district that manages its own ClassLink app and credentials.
Only available on some plans
This feature is available on select plans.
Don't have your own ClassLink app?
If your districts add the KnowledgeOwl app from ClassLink's app library instead, there's nothing to register. Refer to Set up KnowledgeOwl's ClassLink app. That option also works for knowledge bases shared by many districts.
For a general introduction to OpenID Connect in KnowledgeOwl, refer to OpenID Connect (OIDC) SSO overview.
Before you begin
You'll need:
- Someone who can create and manage apps in your district's ClassLink account.
- Your district's ClassLink tenant ID. This is a number, such as
2187. If you don't know it, ask your district's ClassLink administrator. - The Editor role in KnowledgeOwl, or a custom role with the Update security settings permission.
Using a reverse proxy?
OpenID Connect logins use paths that start with /reader-sso. If your knowledge base is behind a proxy that only passes your knowledge base's path, add /reader-sso to it too.
How to configure ClassLink SSO with your district's own app
The setup has seven steps on the OpenID Connect (OIDC) page in KnowledgeOwl, plus a few in ClassLink. The steps don't block each other, so you can come back to any of them.
Step 1: Choose ClassLink
- In KnowledgeOwl, go to Security and access > Access & SSO.
- In the Login methods card, select Set up (or Manage) next to OpenID Connect (OIDC).
- In Choose your identity provider, select ClassLink.
Pick ClassLink in the Choose your identity provider step - If KnowledgeOwl's ClassLink app is available, ClassLink starts on KnowledgeOwl's app. Select Use your district's app instead to switch to your own app. The step summary then shows ClassLink · your own app.
Picking ClassLink fills in what KnowledgeOwl knows about it:
- The issuer,
https://tokens-public.apis.classlink.com. - The scopes,
openid profile email. - Client authentication set to Form post (client_secret_post), which ClassLink's token endpoint requires.
- Also read claims from the userinfo endpoint turned off. ClassLink sends what KnowledgeOwl needs in the ID token.
- A login restriction on
classLink_tenant_id, which you finish in Step 4. - The reader attribute map, including a locked SSO ID. Refer to Step 5.
Step 2: Register KnowledgeOwl with ClassLink
The Register KnowledgeOwl with ClassLink step shows two values to copy into your ClassLink app:
- Redirect URI:
https://<your-kb-domain>/reader-sso/oauth2/callback. Add it exactly as shown. - Login link (optional):
https://<your-kb-domain>/reader-sso/oauth2/login. Use this as the app's launch or login URL so readers can open your knowledge base from a tile on their ClassLink LaunchPad.
Both use your knowledge base's own domain, including your custom domain if you have one. Select Copy next to each one.
Then, in ClassLink:
- In ClassLink's developer or OAuth console, create an OpenID Connect app for your knowledge base.
- Add the Redirect URI from KnowledgeOwl as an allowed redirect URI.
- Optional: If ClassLink asks for a launch URL or login URL, enter the Login link from KnowledgeOwl.
- Copy the app's client ID and client secret. You'll enter them in Step 3.
- Assign the app to the people who should read your knowledge base.
Step 3: Connect ClassLink
- Open the Connect ClassLink step. The Setting up ClassLink callout reminds you about the login restriction.
- Check that Issuer URL is
https://tokens-public.apis.classlink.com. KnowledgeOwl also recognizes ClassLink's older issuer,https://launchpad.classlink.com, if your app uses that one. - Paste your app's client ID into Client ID.
- Paste your app's client secret into Client secret.
- Select Save changes in the bar at the bottom of the page.
- Select Test connection. When it works, you'll see Connected to your identity provider with the endpoints KnowledgeOwl found.
Once saved, the client secret shows as dots with "Saved and encrypted. It can't be shown again." To change it, select Replace.
Step 4: Restrict who can log in
ClassLink logs in users from every district, so KnowledgeOwl requires a login restriction on your ClassLink tenant ID. Without it, anyone with a ClassLink account could read your knowledge base, and KnowledgeOwl won't let you turn OpenID Connect on.
- Open the Restrict who can log in step. A row for the Claim
classLink_tenant_idis already there, with Match set to Is one of. - Enter your ClassLink tenant ID in Allowed values.
- Optional: To narrow it further, select Add restriction. For example, add the claim
classLink_rolewith the allowed valueTeacherto only let teachers log in. - Select Save changes.
Readers must match every restriction. Within a row, separate allowed values with commas: a reader who matches any one of them passes.
Step 5: Map reader attributes
The Map reader attributes step is filled in for ClassLink:
| Reader field | Claim |
|---|---|
| SSO ID | {classLink_tenant_id}:{classLink_sourcedId} (locked) |
| Username / email | email |
| First name | given_name |
| Last name | family_name |
| Reader groups | classLink_role |
The SSO ID combines your tenant ID with ClassLink's user ID, which is only unique within a district. It's locked "so each ClassLink user is matched to a single reader," and you can't change it. If a login doesn't include both claims, it fails rather than risk matching the wrong reader.
Reader groups uses each reader's ClassLink role. Group names must match your reader groups exactly, so create groups named after the roles you want to use, change the claim, or remove the field. To assign groups conditionally, use Set reader fields with rules.
Select Save changes after any change.
Step 6: Test login
- Open the Test login step.
- Select Run a test login. A window opens to log in with ClassLink. Log in as yourself. You won't be logged in to the knowledge base.
- When the window says Test login finished, go back to your settings. The step shows Test login passed or Test login failed, and Recent logins shows what ClassLink sent.
Select Show claims on the login to check that ClassLink sent classLink_tenant_id, classLink_sourcedId, and email. If the test fails, refer to Troubleshoot OpenID Connect logins.
If you change your settings after a test, run the test again. You need a passing test with your current settings to turn OpenID Connect on.
Step 7: Turn on OpenID Connect
- Open the Turn on OpenID Connect step.
- Choose one:
- Available: Readers can log in with the login link or from your identity provider. Restricted content on a public knowledge base can send them here too.
- Required for all readers: Anyone who isn't logged in is sent straight to ClassLink.
- Select Save changes.
For more on these choices, refer to Configure OpenID Connect SSO.
How readers log in
There's no ClassLink button on the reader login page. Once OpenID Connect is on, readers reach ClassLink in any of these ways:
- From the tile for your app on their ClassLink LaunchPad, if you entered the Login link in ClassLink.
- With the Login link from Step 2, which you can add to your own website, emails, or LMS.
- With the Log in link in your knowledge base header, when it goes to OpenID Connect.
- By being sent to ClassLink automatically when OpenID Connect is Required for all readers, or when Send readers who aren't logged in to on the overview is set to OpenID Connect login.
Readers who log in for the first time get a new reader account, matched by their SSO ID on later logins.