OKTA Single Sign-On configuration guide by Contractbook
This article describes how to configure Okta as the primary Identity Provider to facilitate SSO with Contractbook. This SSO configuration must be completed first, in order to proceed to test SCIM (you can find this second configuration step under "OKTA SCIM 2.0 setup by Contractbook" in this article).
- 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
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:
Create SSO App integration in Okta
We do not have Contractbook’s application in OKTA Integration Network (OIN) yet, which means that it has to 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 URL’s 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:
When an application is created, you now need to configure a connection:
- Go to 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 us the Organisation id, Application id, and user URL in order for Contractbook to set up a connection for your app
- These identifiers can be found in the sections below:
And that's it! Now the members who are 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 you can find 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:
- 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 get started, click “Configure API Integration” under the “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:
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 as same as for assigning users one by one, 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 not exceed 5 minutes.
For now, groups have very limited functionality in our system but we are planning to add more in the future.
- To assign groups to applications in your SCIM application, head to Push Groups, click the 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 to be immediate, 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 if you wish to assign the next group