Single Sign On With Okta (DocBoss Login)

Do you use the Okta secure identity cloud application? If so – or if you’re considering using it – this article discusses how to enable Single Sign On for DocBoss when you use Okta.

Single Sign On (SSO) is available for DocBoss. If enabled, users with the company domain will be redirected to their identity provider to sign in to access DocBoss. The instructions below outline how to set up SSO with DocBoss when using Okta as the identity provider.

Requirements

Typically, DocBoss Support will provide the following:

• Single Sign-On URL (Recipient URL or Destination URL)
• Audience Restriction URL
• SCIM connector base URL: https://system.docboss.com/scim/v2/ [system2, 3 …]
• Instructions on how to get a token
• The list of fields for creating/updating user requests (only needed if using SCIM protocol)
  • username [required] – This must be an email address within the SSO domain
  • user. givenName [required]
  • user. familyName [required]
  • user.title – This value is saved as the Title field for the user in DocBoss
  • user.timezone – This value is saved as user’s time zone in DocBoss
  • user.userType – This value is saved as the user’s role in DocBoss. Allowed values are Admin, Full, Reviewer, and View. If not included, user’s role will be set to View.

DocBoss Support will need the following information from your IT:

• Metadata URL

Below is an example of how we configured application and setup fields for mapping, but your IT will know how to configure this best for your company’s needs.

Setup

Add application in Okta

In Okta, follow the steps below:

1) Create a new app integration > select SAML 2.0

2) Set the following values on the next slide:

a)	Single sign-on URL	[provided by DocBoss]
b)	Audience URI (SP Entity ID)	[provided by DocBoss]
c)	Name ID format	EmailAddress
d)	Application username	Okta username
e)	Update application username on	Create and update

3) Copy the Metadata URL to send to DocBoss Support:

Set up SCIM provisioning

Next, set up SCIM provisioning to allow adding and updating DocBoss users through Okta.

4) Enable SCIM provisioning and Save.

5) Add the following SCIM Connection settings:

a)	SCIM connector base URL	DocBoss Support will provide. For example, https://system.docboss.com/scim/v2/
b)	Unique identifier field for users	userName
c)	Supported provisioning actions	Import New Users and Profile Updates, Push New Users, Push Profile Updates, Push Groups
d)	Authentication Mode	HTTP Header
e)	Authorization Bearer	Long-term token from DocBoss Security Settings > API Authorization > Tools > Token

6) On the Provisioning > To App tab, enable Create Users, Update User Attributes, and Deactivate Users:

Set up user info fields

Next, set up fields for users. The following fields exist in the Okta by default:

• user. givenName [required]
• user. givenName [required]
• user.title – We used it for title field for the user in the docboss
• user.timezone
• user.userType – we used it for the Role

Note that there is no default field in Okta that matches our “affiliate” field. A custom field can be added for this (see below instructions on adding custom fields). If not included, the user will be given access to the affiliate with the smallest company ID (the original affiliate).

Mapping is set by default. User only should remove mapping for excess fields:

7) Under Provisioning > To App > Attribute Mappings, set to not apply mapping for all fields except the following:

• user.firstName
• user.lastName
• user.title
• user.timezone
• user.userType

This is set so that when a user is assigned to DocBoss in Okta, only the selected fields will be copied and sent to DocBoss.

8) Optionally, you can remove excess fields on the Profile Editor > Application Profile > Attributes to hide it on the assign user to application form:

Or you can add some fields as custom to add more settings for the field.

Custom Fields

Affiliates

This is optional. If included, only one affiliate access can be granted at a time. Additional requests will ADD new affiliate access but not remove the existing affiliate access. The value for this should be the Company Short Name from the company profile in DocBoss.

When configuring the field, External name should be set as “affiliate” and External namespace should be set as “urn:ietf:params:scim:schemas:extension:docboss:2.0:User”.

If Affiliate is not included in a request, the user will be given access to the affiliate with the smallest company ID (the original affiliate).

Limit values for Role type

Configuration example:

Result:

Add this to the Application profile in Okta (Profile Editor > Application User Profile ). It is important to set correct External name (that DocBoss uses in our API):

Additional settings

There are additional settings in Okta which your IT may wish to configure. For example, there is an option to set a default value for fields:

Or you can add some fields as custom to add more settings for the field.

Advanced

Expand to learn more