Create SAML app for SSO
- Create your own custom SAML app in G Suite.
In G SuiteAdmin Console, go to Apps > SAML Apps and click on Add a service/App to your domain. If you already have existing SAML Apps, click on the yellow circle with the plus symbol to Enable SSO for a SAML Application. Choose Setup my own custom app.
- Plug your Google IdP Information into KnowledgeOwl.
In KnowledgeOwl, go to Settings > Security, click on Enable SAML SSO, and:
- Copy and paste the Google Apps SSO URL into the KnowledgeOwl Login URL.
- Copy and paste the Google Apps Entity ID into the KnowledgeOwl iDP entityID.
- Download the Certificate and upload it to the KnowledgeOwl x509 Certificate.
- Click the green Save button in KnowledgeOwl and click NEXT in G Suite.
- Set the basic information for your custom app in G Suite.
Provide an Application Name for the Custom App, such as KnowledgeOwl SSO. You can optionally add a description and upload a logo for the app. Click NEXT.
- Insert your Service Provider Details from the security settings page into G Suite.
- Copy and paste the SP Login URL into the ACS URL field.
- Copy and paste the SP Entity ID into the Entity ID field.
- Select EMAIL in the Name ID Format and click NEXT.
- Map your G Suite attributes to KnowledgeOwl.
Click Add New Mapping to set up each required and optional attribute:
- Enter "ssoid" as the application attribute and choose Basic Information and Primary Email.
- Enter "username" as the application attribute and choose Basic Information and Primary Email.
- Repeat for desired optional attributes (see below).
- Click FINISH and OK.
- Click on SAML Apps and turn your Custom APP ON for everyone.
Map Reader Fields in KnowledgeOwl
- Under Settings > Security in KnowledgeOwl, click on the Map SAML Attributes link.
- Map the SSO ID, Username / Email, and any optional attributes to the corresponding attributes from G Suite using the names chosen in step 5 above.
- Click Save.
In addition to mapping the SSO ID and the Login / Username to the primary email, you can optionally pass over the following reader attributes:
- First Name
Enter "first_name" as the application attribute and choose Basic Information and First Name.
- Last Name
Enter "last_name" as the application attribute and choose Basic Information and Last Name.
- Picture / Icon
Enter "icon" as the application attribute and choose the category and attribute containing the picture or icon. The attribute should contain the URL to the user icon.
Enter "reader_roles" as the application attribute and choose the category and attribute containing the group or groups.
- Group names must exactly match the reader group names in KnowledgeOwl to map.
- To assign a user to multiple reader groups, put a comma-separate list of groups in the attribute with no spaces after the comma.
- Custom Fields 1-5
Enter "custom_1" the application attribute and choose the category and attribute containing the attribute you want to map. Repeat for each desired custom field.
|Error app_not_configured_for_user when trying to log in||This can mean you have the wrong Entity ID in your SAML app for SSO. It should literally be "https://app.knowledgeowl.com/sp-map" – no need to replace anything.|
|Redirected to the KnowledgeOwl login screen after authentication||This can mean you have the wrong ACS URL in your G Suite SAML app for SSO. It should look like the URL below, with the highlighted section replace with your KnowledgeOwl subdomain. You can view and customize your subdomain under Settings > Basic, or quickly check your subdomain by clicking View KB:|
|Redirected to the Google login screen after authentication||This can mean you have an incomplete ACS URL. It might be missing "/help/saml-login". It should look like the link below, with the highlighted portion replaced with your KO subdomain.|
Set up and test SSO
In order to test SAML SSO in KnowledgeOwl, you must first configure your SSO integration. View our list of available setup instructions.
|Restrict entire kb to SSO||Under Settings > Security choose:||Inside the application:|
|Restrict only some content to SSO (part public and part private)||Under Settings > Security choose:|
Under Settings > Basic choose:
Under Settings > Style
|Inside the application:|
|Restrict entire kb but allow both SSO and reader logins||Under Settings > Security choose:|
Note: The default login page is where readers will go if they try to access the site without being logged in or click on the logout button in the kb.
|Inside the application:|