OKTA Single Sign-On configuration guide by Contractbook

This article describes configuring Okta as the primary Identity provider to facilitate SSO with Contractbook.

This SSO configuration must be completed first to test SCIM (you can find this second configuration step under "OKTA SCIM 2.0 setup by Contractbook" in this article).

Supported Features

• Identity Provider (IDP) - Initiated Authentication (SSO via OpenID Connect) Flow - This authentication flow occurs when your team members attempt to log in to Contractbook from Okta.
• Automatic account creation in Contractbook on initial SSO.

Requirements

Before you start, make sure you have a working Okta setup with the members from the organization you wish to synchronize with Contractbook. 

Here are the requirements for the configuration to succeed:

• Access to an Okta tenant
• Be an Okta administrator to that tenant
• Have an administrator account on Contractbook
• You'll also need the following:
  • Sign-in redirect URIs: https://app.contractbook.com/login/sso/okta
  • Sign-out redirect URIs: https://app.contractbook.com/logout

Create SSO App integration in Okta

We do not have Contractbook’s application in OKTA Integration Network (OIN) yet, meaning it must be created manually.

• To create the App Integration, visit your organization's Okta account and go to the Applications menu section.
• Then, click on Create App Integration:

• Select OIDC - OpenID Connect as a Sign-in method and Single-Page Application as an Application type in the modal:

• Next, you'll be prompted to enter the name of your application and check the Authorization Code as Grand Type. Then, paste the sign-in and sign-out URLs provided at the beginning of this manual. Trusted Origins should be left blank.
• Controlled Access under the Assignments section depends on your company policies. Enable immediate access should be left unchecked:

SSO Configuration

When an application is created, you now need to configure a connection:

• Go to the general settings section of your newly created app and click on Edit:
  

• Next, change Login initiated by to Either Okta or App, update Application visibility, and set Initiate login URI to the same address as the sign-in redirect URI:

• Finally, you will need to send your Okta Organisation ID (the tenant domain in the below picture), Application ID (the Client ID in the below picture), and Issuer URI to your Customer Success Manager for Contractbook to set up the connection for your app. 
  • Those three pieces of information can be found as pointed out in the pictures below:

Note:

• Please ensure that you have access to the settings section API > Authorization server in your Okta account in order to access the Issuer URI.
• At the time of writing this article, this setting might not be available on some lower-tier plans of Okta.

And that's it! You are set, and users assigned to the application can log in to Contractbook using their Okta Dashboard.

Note: Remember to assign groups or members to the SSO app.

OKTA SCIM 2.0 setup by Contractbook

Below are the steps for configuring a SCIM integration with Contractbook’s application in Okta.

Requirements to establish the integration:

Before you start, first make sure that you have the following:

• A working OKTA setup with the members from the organization you wish to synchronize with Contractbook.
• A Secret Token for an admin user. This is provided to you by Contractbook.
• An administrator account on Contractbook.
• Our Tenant URL: https://api.contractbook.com/scim.

Create a SCIM application

• First, go to your organization's Okta account and head to the Applications section.
  
• Then, click on Browse App Catalog, type in “SCIM” and select "SCIM 2.0 Test App (Header Auth)":
  

• Contractbook’s application is currently not present in the Application Gallery, so you will need to create your own app:
  • Click on Add Integration, enter the preferred name, and proceed by clicking on Next:

• Then, choose the “Secure Web Application” option and select the desired username and password setup.
• Under “Credentials Details” select Email for "Application username format."
• After all these steps are finished, click Done to confirm.
• Your application has now been created:

The next step is to configure an API Integration.

Configure API Integration 

The provisioning process, when successful, will keep your organization’s users in sync with Contractbook’s.

For provisioning, you'll need the following:

• Tenant URL: https://api.contractbook.com/scim
• Your secret token

To start, click “Configure API Integration” under “Provisioning.”

• Select the “Enable API integration” checkbox and paste the Tenant URL and your Secret Token.
• Click the Test API Credentials button to make sure your credentials work with Contractbook:
  

Make sure to check the respective provisioning elements. If you are satisfied with your options, Save this configuration:

Provisioning Users

To assign members to applications, head to the tab called Assignments.

There are two ways of assigning members to the app:

• You can assign them one by one 
• You can assign an Okta group

Assigning members one by one

In your SCIM application, within the Assignments tab, press the button Assign -> Assign to People:

• You can now assign as many users as you need by clicking "Assign" to the right side of their name and Done once you are finished:
  

Assigning members using groups (bulk adding)

Instead of manually assigning one by one, you can use groups to bulk add all members belonging to that group.

The process for using a group is the same as assigning users individually, but instead, clicking Assign to Group under Assign.

Provisioning time for users

The provisioning happens within 40 minutes, so any update to your users will not be immediate. In normal cases, this time will be at most 5 minutes.

Provisioning Groups

For now, groups have minimal functionality in our system, but we plan to add more.

• To assign groups to applications in your SCIM application, head to Push Groups, click Push Groups, and select one of the options to find the group.

• After finding the group, click + Create a group on the right side of the modal.
• If you want the synchronization immediately, select "Push group membership immediately."
  • If not, you can change the group list status from inactive to active in the group list.
• Then, press Save or Save & Add Another to assign the next group.