Set up SAML SSO with Okta

Connect Okta to Document360 with SAML so your users sign in to the knowledge base portal, and your readers to the knowledge base site, with their Okta credentials instead of a Document360 password. You can also turn on SCIM so that Okta adds, updates, and deactivates users and readers in Document360 for you.

When to use Okta with SAML SSO

Use this setup when:

• You manage identities in Okta and want users to sign in to the knowledge base portal, and readers to the knowledge base site, with their Okta credentials.
• You want people to open Document360 directly from the Okta dashboard (IdP-initiated sign-in).
• You want Okta to add, update, and deactivate users and readers in Document360, and sync Okta groups, through SCIM.
• You manage several Document360 projects and want a new project to inherit SCIM settings from an SSO configuration in a parent project.

Before you begin

• You need an Okta account with administrator access. If you don't have one, create an Okta developer account.
• You need the Owner or Admin role in your Document360 project.
• Open Document360 and the Okta Admin Console in two browser tabs. You switch between them during setup.
• If you plan to set up SCIM, have a secure place ready, such as a password manager, to store two secret tokens.

How to set up SAML SSO with Okta

Step 1: Start the SSO configuration in Document360

1. Go to Settings () > Users & Permissions > Enterprise SSO.

2. Select Create SSO, and then select SAML.

3. Select Okta as your identity provider.

   

The Configure SP step opens and shows the values you enter in Okta: Callback path, Service provider entity ID, and Signed out callback path. Keep this tab open.

Step 2: Create the SAML app in Okta

Create the app integration

1. Sign in to Okta, and then select Admin in the top-right corner to open the Admin Console.

2. In the left navigation, expand Applications and Resources, and then select Applications.

   

3. Select Create App Integration.

4. Select SAML 2.0, and then select Next.

   

Enter general settings

1. On the General Settings tab, enter an App name, such as Document360 SSO.

2. (Optional) Upload a logo and set app visibility.

3. Select Next. The Configure SAML tab opens.

   

Enter the Document360 values

1. On the Configure SAML tab, copy these values from the Document360 Configure SP step:

   Copy from Document360	Paste into Okta
   Callback path	Single sign-on URL
   Service provider entity ID	Audience URI (SP Entity ID)

2. Set Name ID format to EmailAddress.

3. Set Application username to Email.

4. Select Show Advanced Settings, turn on Enable Single Logout, and then paste the Signed out callback path from Document360 into Single Logout URL.

5. Select Next.

   

Complete the Feedback page

1. Select This is an internal app that we have created.

2. Select Finish.

   

Okta creates the app and opens it.

Add attribute statements

Attribute statements tell Okta which details about a person to send to Document360.

1. In the app, select the Sign On tab, and then scroll to Attribute statements.

   

2. Expand Show legacy configuration, and then select Edit next to Profile attribute statements.

   

3. Add these three attribute statements. Select Add Another to add the second and third rows.

   Name	Name format	Value
   urn:oasis:names:tc:SAML:2.0:nameid	URI Reference	user.email
   name	Unspecified	user.email
   email	Unspecified	user.email

4. Select Save.

Step 3: Enter the Okta details in Document360

Get the setup values from Okta

On the app's Sign On tab, select View SAML setup instructions. The values you need open in a new page.

Complete the Configure IdP step

1. Switch to the Document360 tab, and then select Next. The Configure IdP step opens.

2. (Optional) To reuse SCIM settings from a parent project, select that project's SSO configuration in Configure an existing connection. Only configurations with SCIM turned on appear. Your new configuration becomes a child configuration: it inherits the parent's SCIM settings, and you can't change them in the child. To learn more, read Inherit from another application. Otherwise, leave this field empty.

3. Copy these values from the Okta setup instructions:

   Copy from Okta	Paste into Document360
   Identity Provider Single Sign-On URL	Sign on URL
   Identity Provider Issuer	Entity ID

4. Leave Binding type set to Httppost, which matches Okta's default.

5. Download the X.509 Certificate from Okta, and then upload it in SAML certificate. You can upload a PEM, CRT, or CER file of up to 10 MB.

6. To let people open Document360 from the Okta dashboard, turn on Allow IdP initiated sign in. To learn more, read Let people sign in from your IdP dashboard.

   

7. Select Next. The SCIM step opens.

Step 4: (Optional) Set up SCIM provisioning

With SCIM, the users and readers you add, update, or deactivate in Okta are added, updated, or deactivated in Document360. You set up SCIM in both tabs now, and test the connection in Step 6, after you create the configuration.

If you don't need SCIM, leave Enable SCIM provisioning off, select Next, and go to Step 5.

Turn on SCIM in Document360

1. On the SCIM step, turn on Enable SCIM provisioning.

   

2. In the confirmation dialog, review the terms, select the checkbox, and then select Agree. The SCIM base URL and the primary and secondary secret tokens appear.

   

3. Copy both secret tokens and store them securely.

Turn on SCIM in the Okta app

1. In the Okta Admin Console, expand Applications and Resources, select Applications, and then open your Document360 app.

2. On the General tab, select Edit next to App Settings.

3. Under Provisioning, select SCIM, and then select Save. The Provisioning tab appears.

   

Connect Okta to Document360

1. On the Provisioning tab, select Edit next to SCIM Connection.

   

2. Copy these values from the Document360 SCIM step:

   Copy from Document360	Paste into Okta
   SCIM base URL	SCIM connector base URL
   Primary secret token	Authorization (under HTTP Header)

3. In Unique identifier field for users, enter userName.

4. Under Supported provisioning actions, select only Push New Users, Push Profile Updates, and Push Groups.

5. In Authentication mode, select HTTP Header, and then paste the primary secret token into Authorization.

   

6. Select Save.

Set the default role and groups in Document360

1. Switch to the Document360 tab. To assign users and readers to groups based on their Okta groups, turn on Enable group sync.

2. In Default role, keep Contributor or select another role.

3. In User groups and Reader groups, select the groups to add new people to. Users in the selected user groups get the default role. Readers in the selected reader groups always get read-only access.

   

4. Select Next. The More settings step opens.

Step 5: Name the configuration and create it

1. In SSO name, enter a name for this configuration.

2. In Login button text, enter the text people see on the SSO sign-in button. By default, the button reads Login with SSO.

3. (Optional) To sign out SSO users after a period of inactivity, turn on Idle session SSO timeout, and then set the Timeout duration (HH:MM). To learn more, read Sign out idle SSO user.

4. (Optional) To switch existing Document360 users and readers to Okta sign-in now, turn on Convert existing team and reader accounts to SSO. Then, under Send invite to, select All users or Selected users. Their existing accounts are converted to SSO accounts; no second account is created. Review the warning in Before you begin first. You can also convert accounts later. To learn how, read Convert user to SSO and Convert reader to SSO.

   

5. Select Create.

The configuration appears in the Enterprise SSO list.

Step 6: (Optional) Finish SCIM setup in Okta

Skip this step if you didn't set up SCIM in Step 4.

1. In the Okta Admin Console, open your Document360 app, and then select the Provisioning tab.

2. Select Edit next to SCIM Connection, and then select Test Connector Configuration. A dialog confirms that the test succeeded and lists the provisioning features Okta detected.

   

3. Select Close, and then select Save.

4. To send user creation, changes, and deactivation from Okta to Document360, turn on the Provisioning to App actions. To learn how, read Provision Okta to Document360.

Step 7: Assign people and test sign-in

Only people assigned to the app in Okta can sign in to Document360 through Okta.

1. In the Okta Admin Console, open your Document360 app, and then select the Assignments tab.
2. Select Assign, and then select Assign to People or Assign to Groups.
3. Select Assign next to each person or group who should sign in to Document360, select Save and Go Back, and then select Done.

Each person also needs an SSO account in Document360. If SCIM is on, Okta creates it when you assign them. Otherwise, convert their existing account (Step 5) or invite or add them as SSO users.

To test sign-in:

1. In a private browser window, open the Document360 login page.
2. Enter the email address or subdomain of an SSO account assigned to the app, and then select Login with SSO, or the text you set in Login button text.
3. Sign in on the Okta page.

You land in the knowledge base portal. To learn more about how people sign in, read Log in using SSO - Knowledge base portal. If sign-in fails, read SSO login issues and SAML SSO issues.

Manage users and readers with SCIM

With SCIM on, you manage people in Okta, not in Document360. In Okta, you set how each person is provisioned (as a user, reviewer, or reader) with the userType attribute, create users, readers, and groups, push groups, and deactivate people. In Document360, you can only manage their content access.

To learn how, read Managing users and readers with SCIM in Okta.

Limits and limitations

Best practices

• Test with a small group first. Before you roll out SSO to everyone, assign a few test accounts and sign in with them to catch attribute mapping or access issues.
• Store both secret tokens like passwords. Keep them in a password manager or secrets vault, never in plain text files or code repositories.
• Match the idle timeout to your security policy. Set Timeout duration (HH:MM) to your organization's session rules.
• Renew the SAML certificate before it expires. When the certificate expires, SSO sign-in stops working. To learn more, read Managing SSO certificates.

Related articles

More on SSO configurations:

• SAML
• Mapping an existing SSO configuration to other projects
• Remove a configured SAML SSO

FAQ