Configure SAML SSO with the KnowledgeOwl app in Okta

Use the KnowledgeOwl app in the Okta Integration Network (OIN) to set up SAML SSO for your readers without building the Okta app by hand.

Pending Okta review

KnowledgeOwl's SAML SSO app for the Okta Integration Network is pending Okta review. Until it appears in your Okta app catalog, refer to Configure SAML SSO with Okta to create the app manually.

Only available on some plans
This feature is available on select plans.

If you're looking for ways to use Okta provisioning for authors, refer to Okta SCIM provisioning for authors.

How to set up SAML SSO with the KnowledgeOwl app in Okta

Setting up SAML SSO with Okta takes a few steps in Okta and a few in KnowledgeOwl. All of the KnowledgeOwl steps happen in the SAML setup: go to Security and access > Access & SSO and, in the Login methods card, select Set up or Manage next to SAML.

Step 1: Add the KnowledgeOwl app in Okta

Log in to the Okta Admin Console.
Go to Applications > Applications.
Select Browse App Catalog.
Search for KnowledgeOwl and select the KnowledgeOwl app. Don't choose KnowledgeOwl Author Provisioning with SCIM 2.0, which is for author provisioning.
Select Add Integration. The General Settings page opens.
If desired, edit the Application label.
In KB domain, enter your knowledge base's domain without https://. For example, mykb.knowledgeowl.com or your private domain.
In KB path, enter the path your knowledge base uses, such as help, docs, or home. In KnowledgeOwl, the SP login (ACS) URL in SAML step 1, Give these details to your identity provider, ends with /<kb-path>/saml-login, so you can copy the path from there.
Select Done. The app opens to the Assignments tab.

Step 2: Get your Okta details

From your Okta application details:

Open the Sign On tab.
In the SAML 2.0 card, select More details.
Copy the Sign on URL, the Sign out URL, and the Issuer. You'll paste these into KnowledgeOwl in Step 3.
Download the Signing Certificate. Find the certificate in your downloads and change the file extension from .cert to .crt. In many cases, showing the file extension in the name and renaming it works.

Step 3: Add your Okta details into KnowledgeOwl

In the KnowledgeOwl SAML setup, expand step 2, Connect your identity provider.
Paste the Issuer into IdP entity ID.
Paste the Sign on URL into IdP login URL.
Optional: paste the Sign out URL into IdP logout URL.
Under IdP certificate, drag the .crt file into the drop zone, or select browse to choose it. The certificate is saved as soon as you upload it.
Select Save changes.

Step 4: Map Okta attributes in KnowledgeOwl

The KnowledgeOwl app in Okta sends these attributes. Map them in KnowledgeOwl using exactly the same names:

In the KnowledgeOwl SAML setup, expand step 3, Map reader attributes.
Enter ssoid in SSO ID.
Enter email in Username / email.
Enter firstName in First name.
Enter lastName in Last name.
Select Save changes.

Don't use Fill in Okta settings for this app

The Okta option under Identity provider in step 3 fills in names for an Okta app you build yourself (email as the SSO ID). The KnowledgeOwl app in Okta sends ssoid instead, so enter the names above by hand.

Refer to SAML attribute map for the other fields you can map.

Step 5: Enable SAML SSO in KnowledgeOwl

In the KnowledgeOwl SAML setup, expand step 5, Turn on SAML.
Select Available or Required for all readers.
Select Save changes.

Trial accounts need a restricted knowledge base

On a trial account, choosing Public under Who can read this knowledge base? blocks every reader, including readers who log in through SAML SSO. Select Required for all readers in SAML step 5, Turn on SAML, and select Save changes. Refer to SSO options for different knowledge base setups for more information.

Step 6: Assign users in Okta

In your Okta app, open the Assignments tab.
Select Assign, then Assign to People or Assign to Groups. Groups may not be available on every Okta plan.
Select Assign next to each user or group, then Save and Go Back.
Select Done.

Step 7: Test the login

To test from Okta, log in to your Okta dashboard as an assigned user and select the KnowledgeOwl tile. Okta logs you in to the knowledge base.
To test from KnowledgeOwl, open a private browser window and go to your SP login (ACS) URL. Okta asks you to log in, then returns you to the knowledge base.

In KnowledgeOwl, go to Account > Readers and make sure the reader account you logged in with exists and its name and email came through.

Logging in as an Okta administrator

If you're logged in to Okta as an administrator, Okta may open the Admin Console instead of your dashboard. Open the apps menu in the Admin Console and choose Okta Dashboard, then select the KnowledgeOwl tile.

Next steps

To make SAML SSO the only way into your knowledge base or change other behavior, refer to SSO options for different knowledge base setups and SSO Advanced options.
To let authors log in with SAML SSO too, refer to Set up SAML SSO for authors.
For an overview of SAML SSO for readers, refer to SAML SSO setup overview.

Troubleshooting

If the SAML row in the Login methods card displays the warning "No SSO ID mapped, so readers won't be created", you haven't mapped the SSO ID in Step 4. Refer to Missing SSO ID mapping warning.

For other problems, including a failed login after Okta, refer to the troubleshooting section of Configure SAML SSO with Okta, which also applies to this app.

If you run into any issues setting up the KnowledgeOwl app in Okta, please contact us.