SAML SSO with Okta

Okta is an Identity Provider (IdP) that simplifies user access management by allowing users to sign in to multiple applications with a single set of credentials. This article demonstrates how to configure SSO between Okta and Document360, enabling your users to access Document360 using their Okta credentials. Please note that only users with Owner or Admin as the Project role can configure SSO in Document360.

PRO TIP

It is recommended to open Document360 and Okta in two separate tabs/browser windows, since configuring SSO in Document360 will require you to switch between Okta and Document360 multiple times.

Sign up for Okta

Access to an Okta account is a prerequisite for configuring single sign-on in Document360 with Okta. To sign up for Okta,

1. Navigate to https://developer.okta.com/signup/ and complete the signup process.

2. After signing up, you will receive an email with your login credentials and an account activation link at your registered email.

3. Once you click on the activation link, you will be redirected to the Okta Domain login page.

4. Log in with your credentials.

5. Once you log in, you will be redirected to the Okta developer console.

Adding an application in Okta

To create a Document360 SSO configuration using Okta, you must create a new application on Okta. To create a new application on Okta,

1. Log in to Okta using the credentials used while creating an Okta account.

2. Switch to the admin user role by clicking on Admin at the top right next to your profile name.

3. From the left navigation list page, expand the Applications dropdown, and click Applications.

4. In the Applications page, click the Create App Integration button.

5. In the Create a new app integration dialog, select SAML 2.0 as the Sign-in method and click Next.

Creating a SAML integration in Okta

Next, you will be redirected to the Create SAML Integration page.

General Settings

1. In the General Settings tab, enter the name of your new application in the App name field.

2. Browse and upload a logo for your application in the Add logo field if required.

3. Next, you can check the App visibility checkbox if required.

4. Click on the Next button to navigate to the Configure SAML tab.

Configure SAML

In the Configure SAML tab, you will require the parameters provided on the Configure the Service Provider (SP) page in Document360.

1. To access the Configure the Service Provider (SP) page, navigate to Settings > Users & permissions > SSO Configuration in Document360.

2. Click the Create SSO button, select Okta in the Choose your Identity Provider (IdP) page.

3. This will redirect you to the Configure the Service Provider (SP) page, which will display the parameters required to complete the SAML configuration on Okta.

4. Enter the parameters from Document360 to Okta based on the below table.

   Document360	Okta
   Callback path	Single sign-on URL
   Service provider entity id	Audience URI (SP Entity ID)

5. Select EmailAddress from the Name ID format dropdown menu

6. Select Email from the Application username dropdown menu.

NOTE

Email and name parameters are case sensitive.

Feedback

The feedback page is for providing information to Okta about how you configure the application. Select the This is an internal app that we have created checkbox and click Finish.

4. Click Save.

Document360 to Okta SAML SSO configuration

SAML setup instructions on Okta

1. On the Okta dashboard, click on the Applications dropdown and select Applications.

2. On the Applications page, select the active application you want to configure on Document360.

3. Click the Sign On tab.

4. Click the View SAML setup instructions button

The parameters needed to be configured will open in a new webpage.

SSO configuration on Document360

1. Switch to the Document360 page you had opened, displaying the Configure the Service Provider (SP) page.

2. In Configure an existing connection field, you can inherit from an already created SSO configuration that has SCIM enabled in the parent project. By selecting and inheriting this connection, the current SSO configuration will be set as the child inherited SSO configuration and will automatically inherit the SCIM configuration from the parent.

 NOTE

For more information on inheritance, go to Managing Users and Readers with SCIM in Okta

3. Complete the fields in the Configure the Identity Provider (IdP) page using the setup instructions from Okta.

4. Download the X.509 Certificate from Okta and attach the downloaded okta_cert file in the SAML certificate field on Document360.

   Document360	Okta
   Sign on URL	Identity Provider Single Sign-On URL
   Entity ID	Identity Provider Issuer
   SAML certificate	X.509 Certificate

5. Next, turn on/off the Allow IdP initiated sign in toggle as per your project requirements.

6. Once done, click the Next button to navigate to the SCIM provisioning page.

SCIM Provisioning with Okta

If SCIM provisioning is required,

1. Turn on the Enable SCIM Provisioning toggle.

2. A confirmation dialog will appear outlining the terms for enabling SCIM. Review the terms, select the checkbox, and click Agree.

3. The parameters required to complete the SCIM configuration in Okta will then be displayed.

Navigate to Okta to enable SCIM provisioning

1. In the Okta Admin Console, expand the Applications dropdown from the left navigation bar and click Applications.

2. Select the application where you want to enable SCIM provisioning.

3. Navigate to the General tab and click Edit under App Settings.

4. Select the SCIM Provisioning radio button and click Save.

Provision SCIM in Okta with Document360

1. Go to the Provisioning tab and under the SCIM Connection section, click Edit. 

2. Enter the SCIM Base URL from Document360 into Okta’s SCIM connector base URL field.

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

4. Under Supported provisioning actions, select only the options supported by Document360:

   1. Push New Users

   2. Push Groups

5. From the Authentication mode dropdown, choose HTTP Header.

6. Go to Document360, and in the SCIM provisioning page, copy the Primary secret token.

7. Paste the Primary secret token into the HTTP Header Authorization field.

 NOTE

The primary and secondary tokens are generated once and displayed only at the time of creation. You can choose to copy the primary or the secondary secret token. Ensure you copy and store them in a secure location before saving the configuration. Once the SSO configuration is saved, the tokens will appear masked when you return to edit it and cannot be retrieved. To obtain a new token, you must regenerate it. Regenerating a token invalidates the existing one, you will need to update the new token in your Okta configuration to continue syncing without interruption.

 NOTE

Do not click Test Connector Configuration yet. At this stage, SCIM provisioning will not work with Document360 as the SSO configuration set up in Document360 is not completed.

Navigate to Document360 to assign default role

1. Go to the SCIM provisioning page in Document360 and turn on the Enable group sync toggle if required. This automatically assigns users and readers based on your IdP group mappings.

2. In the Default role field, the role is set to Contributor by default. You can change this from the dropdown if needed.

3. In the User groups and Reader groups fields, select the groups you want to add. Multiple groups can be added, and they will inherit the default role you selected earlier.

4. Click Next to navigate to the More settings page.

More settings

To customize SSO settings, follow the steps below,

1. In the More settings page, enter a name for your SSO configuration in the SSO name field.

2. Enter the text you want displayed on the login button in the Customize login button text field.

3. Enable Sign out idle SSO user if needed, and set the duration after which an idle SSO user will be automatically logged out.

4. Choose whether to invite all users or selected users using the Convert existing team and reader accounts to SSO radio buttons.

Navigate to Okta to complete SCIM provisioning with Document360

After the SSO configuration has been successfully created in Document360, SCIM provisioning can now be completed in Okta.

1. Navigate back to Okta Admin Console, ensure all the necessary details have been filled.

2. Then, click Test Connector Configuration to verify the connection between Okta and Document360.

3. A confirmation dialog will appear, indicating that the test was successful.

4. Click Save to finalize the configuration.

 NOTE

For further details on how to add User, Readers, and User and Reader groups, go to Managing Users and Groups with SCIM in Okta.

The SSO configuration based on the SAML protocol has been configured using Okta successfully.

FAQ