Create SCIM connectors for on-premises provisioning

The Okta Provisioning Agent lets you provision users from Okta to on-premises apps that are installed behind a corporate firewall and to import users from corporate apps into your Okta org. Communication between Okta and on-premises apps 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.

The SCIM protocol is used to connect Okta to on-premises apps. No specific knowledge of SCIM is required to build and use a connector. For more information on SCIM, see the SCIM 2.0 and 1.1 specifications.

The connector receives SCIM messages from the Okta Provisioning Agent and integrates with the on-premises app using the app's API interface. You only need to author the Java code that defines the specifications of the on-premises app. You can create multiple connectors to provide connectivity to different on-premises apps, if necessary.

Before you begin

To use the SDK to create a connector, you need the following:

• The SDK package. To download this from Okta, sign in as an administrator and go to SettingsDownloads. Click Download Latest beside Okta Provisioning Connector SDK.
• Minimum Java versions: 1.6 or 1.7
• A web server to run your connector as a WAR file
• An IDE, such as Eclipse or IntelliJ (recommended)

SDK package contents

The SDK package is a compressed file. The following table describes the contents of the decompressed package.

Create your connector

You can create a connector using the Provisioning Connector SDK to integrate on-premises apps with Okta. The connector implements the SCIMService interface.

Step 1: Implement SCIMService

Write a Java connector that implements the SCIMService interface. You can find Javadocs for the SDK in the doc directory.

Selected methods

The following table lists some of the SCIMService methods that you might implement. Based on the features supported by the on-premises app, you can decide which methods to implement.

Capabilities mapping

When you create your connector and the SCIMService interface, you tell Okta which UserManagementCapabilities you implemented in your connector. This dictates which provisioning features are available for the app integration that you create in Okta. See Typical workflow for deploying on-premises provisioning for more details on how to configure an app integration.

The following table maps the provisioning features that you can set on the app integration in Okta to the methods in your SCIMService connector that enable them. These are the UserManagementCapabilities that you can set in the code. They aren't visible when viewing the app instance in Okta.

* Enable OPP_SCIM_INCREMENTAL_IMPORTS if your SCIM connector supports filtering on the meta.lastModified attribute with the gt attribute operator.

Step 2: Build your connector

Build your connector using Maven. See the instructions in the Example connector section.

Step 3: Deploy your connector

Deploy your connector on a web server as a WAR file.

Step 4: Test your connector

Test your connector using the Okta Connector Tester tool in the tester directory.

Step 5: Test your connector with Okta.

See Test SCIM connectors for on-premises provisioning.

Example connector

The SDK package includes a sample connector named example-server. This is a simple connector that uses an in-memory data store. You can also use a file-based data store. This example connector integrates with on-premises provisioning and responds to provisioning instructions from Okta.

Build the example-server

Example code is provided in the package that creates a working connector where users and groups are kept in an in-memory identity store. A completed connector consists of one .war file.

Complete the following steps to build the example-server:

1. Locate /lib/scim-server-sdk-<version>.jar from the SDK package.
2. Install it locally with the following Maven command:

mvn install:install-file -Dfile=<PATH TO THE JAR> -DgroupId=com.okta.scim.sdk -DartifactId=scim-server-sdk -Dpackaging=jar -Dversion=ab.cd.ef, where ab.cd.ef is the version number of the SDK. For complete build instructions for your package that include the correct version number, see the install.bat and install.sh files in the /lib folder.

3. Build the connector:

   mvn package

4. Copy the target/scim-server-example-*.war file to your Tomcat directory and run it.

You can now use the Okta Connector Tester utility to test the connector. To integrate the connector with Okta after testing, see Step 3: Deploy your connector.

Test your connector

The SDK includes the Okta Connector Tester utility to test your SCIM connector. This can test connectors built using the Okta Provisioning Connector SDK or any custom SCIM connector/server, without connecting to Okta and the Okta Provisioning Agent.

See Test SCIM connectors for on-premises provisioning.

Deploy your connector

After you create a connector and copy the .war file to the Tomcat webapps directory, see Connect to a SCIM connector to integrate the new connector. This creates an integration between the agent and the SCIM server that you created using the SDK over https. To complete the process, see Enable SSL.

While you can use http communication between the agent and the SCIM server, as described in Allow HTTP, https is the recommended protocol.

Allow HTTP

1. Edit configure_agent.sh.
2. Find the line that contains echo "Configuring Okta Provisioning agent".
3. The following line registers the provisioning agent. To enable HTTP, add -allowHttp true to the list of command-line arguments. Insert the line continuation character (\) as necessary to include this argument.

Enable SSL

Do the following to support SSL for https connections:

• Generate a key for the SCIM server and export a certificate
• Import the certificate to the trust store of the Okta Provisioning Agent

Complete the following five steps to enable SSL using self-signed certificates. To improve security and use certificates signed by trusted third-parties, you can import that type of certificate into the trust store of the Okta Provisioning Agent in step 5.

Step 1: Generate a key

If your Tomcat server is accessed through the localhost URL, generate a key using the following command:

keytool -genkey -alias scim_tom -keyalg RSA -keystore /root/scim_tomcat_keystore Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: localhost What is the name of your organizational unit? [Unknown]: IT What is the name of your organization? [Unknown]:MyCompany What is the name of your City or Locality? [Unknown]: sf What is the name of your State or Province? [Unknown]: ca What is the two-letter country code for this unit? [Unknown]: us Is CN=K0208, OU=eng, O=okta, L=sf, ST=ca, C=us correct? [no]: yes Enter key password for <scim_tom> (RETURN if same as keystore password):

If your Tomcat Server is accessed through an IP (for example, https://10.11.12.13:8443/), run the following command using keytool from Java 7 or above.

$JAVA_HOME/bin/keytool -genkey -alias scim_tom -ext san=ip:10.11.12.13 -keyalg RSA -keystore /root/scim_tomcat_keystore

Step 2: Enable SSL for HTTPS connections to Tomcat

Configure the HTTPS connector to enable SSL. Edit your Tomcat configuration file, which is normally found at $TOMCAT_HOME/conf/server.xml. The following configuration enables SSL, sets the HTTPS port to 8443, and instructs Tomcat to use the keystore that you created in the previous step (/root/scim_tomcat_keystore).

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="/root/scim_tomcat_keystore"
keystorePass="changeit" />

Step 3: Start Tomcat and verify that you can reach the server over https

Start Tomcat by following the directions for your version and operating system. For example, on Linux you might go to $CATALINA_HOME/bin and run ./catalina.sh start to start Tomcat.

Open a browser tab and enter your server address (for example, localhost). A webpage is shown if Tomcat is running.

Step 4: Export the public certificate

keytool -export -keystore /root/scim_tomcat_keystore -alias scim_tom -file /root/scim_tomcat.cert Enter keystore password: Certificate stored in file </root/scim_tomcat.cert>

Step 5: Import this certificate into the trust store of the Okta Provisioning Agent.

Import the certificate to Tomcat to allow a secure connection between it and the SCIM server. Run the following command on the machine where the Okta Provisioning Agent is installed:

Next steps

Test SCIM connectors for on-premises provisioning

Related topics

Create SCIM connectors for on-premises provisioning using SDK

SCIM messages for on-premises provisioning