SCIM Integration with OKTA, on-premises provisioning architecture (new)

Owned by Yuriy Shpek
Jul 10, 2023
7 min read

Here is a quick demo of how it works with OKTA, on-premises provisioning.

You can use on-premises provisioning to provision users between Okta and applications that are installed behind your corporate firewall. Communication between Okta and on-premises applications occurs through the Okta Provisioning Agent and a System for Cross-domain Identity Management (SCIM) server or a provisioning connector built using the Provisioning Connector SDK. In the case we are considering, Atlassian Jira/Confluence/Bitbucket with the pre-installed SCIM User Provisioning plugin from Luxplugins will act as a SCIM server.

You can also use Active Directory, LDAP or web services APIs to manage application user accounts.

1. Architecture

The on-premises provisioning architecture consists of the following components: Okta, the Okta Provisioning Agent, a SCIM server or custom connectors, and your on-premises applications.

The figure below shows a scheme from Okta, on which the functional blocks (components) that will be used in our example are highlighted with red rectangles:

On-premises provisioning architecture

As shown in this illustration, all components except Okta are located inside your firewall. This is a classic scheme, but of course, this is not mandatory, each component can be placed in different locations.

How it works in a nutshell. The Okta Provisioning Agent polls Okta and finds the provisioning events (more exactly reads the queue of actions). The Okta Provisioning Agent translates the provisioning event to a SCIM request, making an HTTP request to the /Users or /Groups endpoint of your SCIM server (e.g. Jira/Confluence/Bitbucket) or Connectors. The agent also reads the connection parameters to the SCIM Servers/Connectors. You do not need to set up special rules for incoming connections on the firewall, since the connection is established by the agent (outcoming connection).

If your application does not support the SСIM protocol, you should use (develop) a SСIM connector. The connector receives SCIM messages from the Okta Provisioning Agent and integrates with the on-premises application using the API interface provided by that application. You only need to author the Java code that defines the specifications of the on-premises application. You can create multiple connectors to provide connectivity to different on-premises applications, if necessary. For development questions, please contact our support.

On-premises provisioning only supports the SCIM 1.1 specification.

Now let's look at the steps for creating our example integration (the components are highlighted in red rectangles in the figure above).

2. Install the Okta Provisioning Agent

  1. In the Okta Admin Console, go to Settings > Downloads.

  2. Click Download Latest for the Okta Provisioning Agent. We'll install Okta Provisioning Agent on the Windows Server.

Note: In order for the Okta Provisioning Agent to be available in the download list, you should register at least a 30-day trial account like trial-xxxxxxx.okta.com. Free accounts like dev-xxxxxxx.okta.com do not allow you to download the Okta Provisioning Agent (not in the download list).

  1. Launch the installer, and then click Next.

  2. In the License Agreement dialog box, click Next.

  3. Enter your Okta Customer Domain URL, and then click Next:

  1. Then your browser window will be opened, sign in to your org.

  2. Grant permission to access the Okta API by clicking Allow Access:

  1. Return to the installer, and then click Finish.

  2. In the Admin Console, go to Dashboard > Agents. Verify Okta Provisioning Agent is listed with a green circle. The green circle indicates the agent is connected:

3. Create an instance of your app in Okta

First of all, we need to create a single sign-on integration that supports the SCIM provisioning option. Once this integration is available, we can enable the SCIM option and configure settings specific to our SCIM application. So, using the OKTA Admin Console App Integration Wizard, create a new custom SSO integration. We used for demo SAML based new web app. We are not using SSO here, so the corresponding settings will be mock, only for tests.

  1. In the Admin Console, go to Applications → Applications.

  2. Click Create App Integration.

  3. Select SAML 2.0 as the Sign-in method.

  4. Click Next.

  1. Specify the App name and click Next

  1. Then enter test data into Single sign-on URL and Audience URI fields for SAML (it’s just for demo) and click Next:

  1. The last step of the SAML integration creation:

3. SCIM provisioning settings for on-premises architecture

3.1. Enable on-premises provisioning

After completing the app creation in the previous step, do the following:

  1. Сlick the General tab.

  2. In the App Settings area, click Edit.

  3. Select the Enable on-premises provisioning check box.

  4. Click Save.

3.2. Connect to a SCIM connector

A SCIM connector acts as a SCIM server and an intermediary between Okta and the on-premises application. Thus, in our case, the plugin SCIM User Provisioning for Jira (Confluence/Bitbucket) installed in Jira acts as a SCIM connector (or a SCIM server). Recall that on-premises provisioning only supports the SCIM 1.1 specification.

  1. Before proceeding, we need to get parameter values from the target Atlassian app that points Okta Provisioning Agent to your SCIM API server. So, get SCIM API URL and Bearer token on the Jira/Confluence/Bitbucket side, for example:

  1. From the integration's settings page, choose the Provisioning tab. Your system should detect the presence of the Okta Provisioning Agent and instruct you to configure the SCIM connector.

  2. Click Configure SCIM Connector:

  1. Fill in the following fields:

    • SCIM connector base URL — Enter the URL of the SCIM connector to which the Okta Provisioning Agent forwards SCIM data.

    • Authorization type — Select HTTP Header.

    • HTTP header name and value — HTTP header name = “Authorization“, Value = “Bearer xxxxxxxxxxxxxx“, where xxxxxxxxxxxxxx is bearer token value.

    • Unique user field name — userName.

    • Accept user updates — Select this check box to update a user's application profile using data returned by the connector or SCIM server directly.

    • Timeout for API calls — Select the duration for a provisioning call to timeout when the SCIM endpoint does not respond.

    • Connect to the these agents — Select the Okta Provisioning Agents with which you want to connect to.

  1. Click Test Connector Configuration:

  1. If the test passes, click Save to save your settings. If the test fails, change your settings and try again.

After clicking the Save or Test Connector Configuration buttons, you can notice that in the Audit Log of our plugin in Jira there are entries about the requests received:

Note that the Agent does not have its own UI, but it keeps its own log. Let's take a look at the log file and see what the Agent recorded into the log after clicking the button Test (or Save):

So, your on-premises system is now connected to Okta, and you can provision users and perform provisioning tasks.

3.3. Choose provisioning options

  1. Currently, from the Settings column on the left side of the screen, we have selected provisioning configuration option: To App. Click Edit, choose the provisioning options under Provisioning to App section and click Save:

  1. Below, in the section for Attribute Mappings reduce the number of attributes for SCIM integration on the OKTA side, because Jira/Confluence/Bitbucket doesn’t support all of them:

3.4. Assign application to users and groups

1. Assign to Users

From the integration's settings page, choose the Assignments tab, then Assign → Assign To People/Assign To Groups:

2. Assign to Groups

3.5. Push groups to app

From the integration's settings page, choose the Push Groups tab, then Push Groups → Find Groups By Name:

3.6. Check the Jira (Confluence/Bitbucket) info

In conclusion, let's try to deactivate the user in Okta:

Jira info: