Configure SAML SSO with Okta

This tutorial will walk you through setting up an SSO SAML 2.0 Okta app integration with KnowledgeOwl. This feature is available on select plans.

You can also connect Okta using OpenID Connect (OIDC) instead of SAML. Refer to Configure OpenID Connect SSO.

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

Step 1: Create your Okta SAML 2.0 app

To begin, create a SAML 2.0 app in Okta:

1. Log in to the Okta Admin Console.
2. Go to Applications > Applications.
3. Select Create App Integration. The Create a new app integration modal opens.
4. Select SAML 2.0 as the Sign-in method. The Create SAML Integration page opens to the General Settings tab.
5. Enter an App name, like KnowledgeOwl SAML.
   If for some reason you're using Okta without a custom domain, this app name will display at the top of the knowledge base's login page when a user isn't logged in, so you may want to use the name of your knowledge base in that case!
6. Add your knowledge base logo, if desired. You're welcome to save and use this version of Linus:
   
   If you're using Okta without a custom domain, this logo is also displayed on the Okta login page for your knowledge base. Here's where the logo and name show up on the login page without a custom domain:
   Sample Okta login without a custom domain. App logo and name display at the top with the "Connecting to [logo] Sign in with your account to access [App name]" text
7. Select Next. The app's Configure SAML tab loads and you can move on to Step 2.

Step 2: Add the KnowledgeOwl SP info to your Okta app

Now that your Okta app exists, add the KnowledgeOwl Service Provider (SP) information into it. Keep your Okta app open to the Configure SAML tab. Then:

1. In KnowledgeOwl, go to Security and access > Access & SSO.
2. In the Login methods card, select Set up or Manage next to SAML. The SAML setup opens.
3. Expand step 1, Give these details to your identity provider, and copy the SP login (ACS) URL.
4. Paste this into your Okta app as the Single sign-on URL. Leave the box to Use this for Recipient URL and Destination URL checked.
5. In KnowledgeOwl, copy the SP entity ID.
6. Paste this into your Okta app as the Audience URI (SP Entity ID).
7. Make sure these settings are set this way:
   1. Default RelayState should be blank.
   2. Name ID format should be Unspecified.
   3. Update application username on should be Create and update.
8. Set the Application username to Email.
   Your completed screen should look something like this: Sample Okta app SAML Settings
9. Select Next. The Feedback tab opens. No actions are required on this page, though if you feel thorough, copy the URL for this page and add it to the Did you find SAML docs for this app? textbox.
10. Select Finish. The page updates to display the General tab of your application details.
11. If you named your app after your knowledge base and didn't mention KnowledgeOwl, Edit the App Settings to add Application notes for admins to note that this app is For KnowledgeOwl SAML for [knowledge base name]. Future Okta admins will thank you.

You can now continue with Step 3: Add your Okta IdP details into KnowledgeOwl.

If you have questions on setting any of the Okta app fields, refer to Okta's Application Integration Wizard SAML field reference documentation.

Step 3: Add your Okta IdP details into KnowledgeOwl

Now that the KnowledgeOwl info is in Okta, we need to add the Okta details into KnowledgeOwl.

For this step, in the KnowledgeOwl SAML setup, expand step 2, Connect your identity provider:

SAML step 2, Connect your identity provider

From your Okta application details:

1. Open the Sign On tab.
2. In the SAML 2.0 card, select More details.
3. Copy the Sign on URL.
4. In KnowledgeOwl, in SAML step 2, Connect your identity provider, paste the Sign on URL you copied into the IdP login URL.
5. Copy the Okta Sign out URL and paste it into KnowledgeOwl as the IdP logout URL.
6. Copy the Okta Issuer and paste it into KnowledgeOwl as the IdP entity ID.
   Sample More details section in Okta Sign On tab
7. In Okta, Download the Signing Certificate.
8. Find the certificate in your downloads and use your preferred method to change the file extension from .cert to .crt. (in many cases, if you show the file extension in the name, renaming it from .cert to .crt works). 
9. In KnowledgeOwl, still in step 2, drag the .crt file into the drop zone under IdP certificate, or select browse to choose it.
10. The certificate is saved as soon as you upload it, and a message confirms "IdP certificate uploaded." The IdP certificate section then displays the certificate's common name and the dates it's valid.
11. Select Save changes to save the IdP URLs and entity ID.

Now you're set to tackle Step 4: Select Okta attributes to pass to KnowledgeOwl.

Step 4: Select Okta attributes to pass to KnowledgeOwl

Select which attributes you want to pass from Okta over to KnowledgeOwl:

1. In Okta, go to your application detail's Sign On tab.
2. In the Attribute statements section, select Add expression. The Add expression modal opens.
3. Enter a Name for your expression, like email.
4. Enter an expression for your attribute, like user.profile.email.
5. Be sure to Save your changes.

Refer to your Okta Admin Console Directory > Profile Editor > User to view a list of all user attributes and how to reference them.

For a standard Okta setup, we recommend passing along these attributes or their equivalent as a minimum:

user.profile.email

user.profile.firstName

user.profile.lastName

You may want to pass along additional attributes if you're using reader signup custom fields or groups. For example, many authors will pass a profile field like user.profile.department into the Reader groups field. (You'll need to make sure you have your departments already created in KnowledgeOwl as reader groups for this assignment to work.) Refer to Reader Groups for more information; refer to Add custom fields to the reader signup form for more information on using custom fields.

Next, we'll map those attributes in KnowledgeOwl.

Step 5: Map Okta SAML attributes to fields in KnowledgeOwl

Now that you've made these user profile attributes available to your Okta KnowledgeOwl SAML app, map these attributes to the correct fields in KnowledgeOwl:

1. In the KnowledgeOwl SAML setup, expand step 3, Map reader attributes.
2. Map the fields in your Okta attribute list to the corresponding fields in KnowledgeOwl using the exact same names you used in Okta. For example, if you used the default setup above, enter email for both SSO ID and Username / email, firstName for First name, and lastName for Last name.
   To fill these in for you, select Okta under Identity provider, then select Fill in Okta settings. This also fills in groups for Reader groups; if you don't send groups from Okta, remove that field with its trash icon.

   SSO ID and email address are required
   To successfully log a reader in through SAML SSO, you must map a unique ID (SSO ID) and an email address. The reader's email address can be used as both the SSO ID and their email address.

   1. If you cannot directly map an IdP attribute to a KnowledgeOwl reader attribute, use Custom attribute map rules to do some mappings or logic for you.
3. Be sure to select Save changes.

Now we're ready to enable SAML SSO in KnowledgeOwl and test the setup!

Step 6: Enable SAML SSO in KnowledgeOwl

Congratulations, the moment has arrived: we can now enable SAML SSO:

1. In the KnowledgeOwl SAML setup, expand step 5, Turn on SAML.
2. Select Available. Readers can then log in with the SAML Login link or from Okta.
   SAML step 5, Turn on SAML
3. Be sure to select Save changes.
4. You can now test the SAML SSO setup. In your Okta app, assign individual users or groups of users to your Okta app in its Assignments tab. Refer to Okta Support's How to Assign Users to Applications for more detailed instructions.
5. Then open a new incognito or private browser window and open the SP login (ACS) URL (the same URL as the SAML Login link). Log in using one of the user accounts you assigned to the app. Make sure you can access what you expect.
6. In KnowledgeOwl, go to Account > Readers and be sure that the reader account you logged in to now exists and that all the attributes came through properly.

If you run into any issues, refer to the Troubleshooting section below.

Step 7: Optional settings

With your SAML SSO login working, you can now review a few additional options:

1. To make it so that SAML SSO is the main access method for your knowledge base:
   1. In the KnowledgeOwl SAML setup, expand step 5, Turn on SAML.
   2. Select Required for all readers.
   3. Select Save changes.
      Anyone who isn't logged in is sent straight to SAML. This overrides the Who can read this knowledge base? selection in Security and access > Access & SSO. Other login methods set to Available still work through their login links.
   4. Refer to SSO options for different knowledge base setups for more information.
2. To use the SAML SSO as your primary reader authentication mechanism without requiring it:
   1. Go to Security and access > Access & SSO.
   2. In the Login methods card, set Send readers who aren't logged in to to SAML login. (This option isn't shown when Who can read this knowledge base? is set to Logged-in readers only.)
   3. Select Save changes.
      This sends readers who aren't logged in to SAML when they open restricted content or select the Log in link.
   4. Refer to SSO options for different knowledge base setups for more information
3. To make logging out from the knowledge base log your reader out of Okta entirely:
   1. In the KnowledgeOwl SAML setup, expand step 5, Turn on SAML.
   2. Check the box to Also log readers out of the IdP when they log out. This needs the IdP logout URL from Step 3.
   3. Select Save changes.
      When a reader selects Logout in your knowledge base, they'll be fully logged out of Okta and redirected to your Okta login screen.
   4. Refer to SSO Advanced options for more information on this change and other tweaks you can make to the SAML SSO behavior.
4. To manually set authors to use SAML SSO to login to your knowledge base, too, refer to Set up SAML SSO for authors.

Troubleshooting

Here are troubleshooting steps for some of the most common issues you'll run into.

No SSO ID mapped

In Security and access > Access & SSO, the SAML row in the Login methods card displays this warning:

No SSO ID mapped, so readers won't be created

If you see this warning, it means that you didn't add an attribute mapping for the SSO ID in SAML step 3, Map reader attributes.

To fix it, add a valid attribute name to that field and select Save changes.

SP login URL page doesn't load

If you try to open the SP login (ACS) URL and the page doesn't load, make sure that the IdP login URL is correct, that it uses HTTPS, and that you can resolve the page by going to the IdP login URL directly.

All other issues

For all other issues, including if you can successfully log into your IdP but you get redirected to your knowledge base No Access page:

1. In the KnowledgeOwl SAML setup, expand step 4, Test login.
2. Check Debug mode.
3. Select Save changes. Readers can still log in normally while debug mode is on.
4. Now open the SP login (ACS) URL again and log in.
5. Within five minutes, go back to step 4 and select Load last login attempt.
   • If you see "Login failed" with an error, or "No attributes were read, because the response was rejected first":
     • You may have an issue with the IdP certificate you uploaded, or 
     • Your IdP may require one of the Advanced Options in the SAML setup.
   • If you see the attributes your IdP sent:
     • Make sure that the IdP attribute names listed match the values in step 3, Map reader attributes. To pick from these names, select the arrow at the right end of a field in step 3.
     • Make sure that step 3 has values entered for the SSO ID and Username / email fields. SAML SSO won't work without these entries.
6. Once you're done troubleshooting, be sure to uncheck Debug mode and select Save changes.
7. If you're still having trouble after trying all of the above steps, contact our support team and we will try to help figure out what the issue is.