Once you have the SP info added to your IdP and the IdP info and certificate added to KnowledgeOwl, you'll need to map SAML attributes. This allows KnowledgeOwl to properly create / update readers in your account when they log in, and ensures they see the correct content when they do.
Use step 3 of the SAML setup, Map reader attributes, to directly map an attribute coming from your IdP to an existing KnowledgeOwl field. This works well for one-to-one fields like your reader's email address, first, and last names, or arrays of products or departments that might become reader groups in KnowledgeOwl.
To add these mappings:
- Go to Security and access > Access & SSO.
- In the Login methods card, select Set up or Manage next to SAML.
- Expand step 3, Map reader attributes.
- Optional: Under Identity provider, select your provider (AD FS, Google Workspace, JumpCloud, Microsoft Entra ID (Azure AD), Okta, or OneLogin) and select its fill-in button (for example, Fill in Okta settings) to fill in the attribute names it usually sends. Check them against your IdP. If you've already mapped an SSO ID, select Fill in attribute names from a provider first to see the providers.
- For each attribute you would like mapped between your IdP and KnowledgeOwl, enter the name of the attribute as your IdP sends it in the IdP attribute column next to the corresponding Reader field. KnowledgeOwl saves the value just as it arrives.
- SSO ID, Username / email, First name, and Last name are always listed. To map Reader icon, Reader groups, or Custom field 1 through Custom field 5, select Add field.
- For Reader groups, the names must match your reader groups exactly. A list or a comma separated string assigns several.
- If you map a custom field, you can also check Store incoming lists as comma separated values under Custom field values.
- After you load a debug-mode test login, each field shows its value from that login, and the arrow at the right end of each field lists the attribute names your IdP sent, so you can pick one instead of typing it. Refer to Use a test login to find attribute names below.
Minimum required info
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. - If you cannot use a direct mapping like this, consider using Custom attribute map rules instead. For SAML, a mapped attribute always replaces the value a custom rule sets for the same field. If you're using custom rules to set the value for a field, leave that field unmapped.
- Select Save changes.
Here's a sample attribute map:
Sample attribute map in Map reader attributesA map like this would enter the incoming values from my IdP like this:
- The IdP
uidattribute will be entered into the KnowledgeOwl SSO ID field. - The IdP
emailattribute will be entered into the KnowledgeOwl Username / email field. - The IdP
firstNameattribute will be entered into the KnowledgeOwl First name field. - The IdP
lastNameattribute will be entered into the KnowledgeOwl Last name field. - The IdP
productsattribute will be entered into the KnowledgeOwl Reader groups field. - The IdP
companyattribute will be entered into the KnowledgeOwl Custom field 1 field.
Refer to Create a reader for more information on what these reader fields mean and where you can see them.
Use a test login to find attribute names
If you don't know the attribute names your IdP sends, use debug mode:
- In the SAML setup, expand step 4, Test login.
- Check Debug mode and select Save changes.
- In a private or incognito browser window, log in at your SP login (ACS) URL. The attributes your IdP sent are kept for five minutes.
- Back in step 4, select Load last login attempt to see the attributes your IdP sent.
- In step 3, select the arrow at the right end of a field and pick from the attribute names your IdP sent. Each one shows its value from that login.
- When you're done, uncheck Debug mode and select Save changes.
Using OpenID Connect?
OpenID Connect (OIDC) has its own Map reader attributes step, where you enter claim names instead of attribute names. Refer to Configure OpenID Connect SSO.