Create SCIM connectors for on-premises provisioning

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

SCIM is used to connect Okta to on-premises applications. No specific knowledge of SCIM is required to build and use a connector. For more information on SCIM, refer to this specification.

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.

Before you begin

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

• The SDK package. It's available in Okta on the Downloads page. To obtain the package, sign in as an Administrator in Okta and go to Settings > Downloads. Click Download next to the Okta Provisioning Connector SDK in the Admin Downloads section.
• 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)

Note: Maven is used in the examples to build the SDK.

SDK package contents

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

Create your connector

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

Step 1: Implement SCIMServer Interface using SDK

Write a java connector that implements SCIMService interface. Details about these methods are documented in the Javadoc.

Selected methods

UserManagementCapabilities[ ] getImplementedUserManagementCapabilities()

This method returns the User management/provisioning capabilities implemented by the connector. You must implement this method since it informs the Okta provisioning feature that your connector is implemented.

SCIMUser createUser(SCIMUser user)

This method is invoked when Okta sends an instruction to create a user in an on-premises application.

SCIMUser updateUser(String externalId, SCIMUser user)

This method is invoked when Okta sends an instruction to update an existing user in an on-premises application.

SCIMUser getUser(String externalId)

This method is invoked when Okta sends an instruction to get a particular user from an on-premises application.

SCIMUserQueryResponse getUsers(PaginationProperties pageProperties, SCIMFilter filter)

This method is invoked when Okta sends an instruction to get a set of users from an on-premises application.

SCIMGroup createGroup(SCIMGroup group)

This method is invoked when Okta sends an instruction to create a group in an on-premises application.

SCIMGroup updateGroup(String externalId, SCIMGroup group)

This method is invoked when Okta sends an instruction to update a group in an on-premises application.

SCIMGroupQueryResponse getGroups(PaginationProperties pageProperties)

This method is invoked when Okta sends an instruction to get all of the groups in an on-premises application.

void deleteGroup(String externalId)

This method is invoked when Okta sends an instruction to delete a particular group in an on-premises application.

Based on the features supported by the on-premises application, you can decide on the methods to implement.

Capabilities Mapping

When implementing your connector and the SCIMService interface, you tell Okta what UserManagementCapabilities you implemented in your connector. This manifests as provisioning features available for the app integration 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 those provisioning features you can set on the app integration in Okta to the methods in your SCIMService connector that enable them. These are the UserManagementCapabilities you can set in the code. They aren't visible in Okta on the App Instance page.

* 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 connectors 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 Okta Connector Tester tool.

Step 5: Test your connector with Okta.

See Test SCIM connectors for on-premises provisioning.

Example connectors

There are two example connectors provided as part of the SDK package.

example-server

The example-server 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 the /lib/scim-server-sdk jar file from the SDK root directory.
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 SDK version number. For complete build instructions that include this command with 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

Okta provides Okta Connector Tester utility to test your SCIM Connector, built using Okta 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 have copied the .war file to the Tomcat webapps directory, see Connect to a SCIM connector to integrate the new connector. The five steps listed under the Create your Connector section create an integration between the agent and the SCIM Server you created with 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 Using http, https is the recommended protocol.

Using http

The use of http is not recommended. Okta highly recommends the more secure option of https.

1. From the configure_agent.sh file, search for Configuring Okta Provisioning Agent.
2. Add the command line argument -allowHttp true \ to the list of commands.

Enable SSL

Supporting SSL for https connections requires the following two steps:

• Generating a key for the SCIM Server and exporting a certificate.
• Importing the certificate that was exported in step 1 into the trust store of the Okta Provisioning Agent.

The following detailed instructions for enabling SSL are also located in the example-server/README.txt file.

The following five steps enable you 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

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):

Note: The answer to the first question, "What is your first and last name?", should be localhost if your Tomcat server is accessed through the localhost URL.

If your Tomcat Server is accessed through an IP, such as https://10.11.12.13:8443/, execute the following command to generate the key instead of the preceding command. This command should be executed from a Java 7 installation. The option -ext san to specify IPs in the SubjectAltNames is available only in Java 7.

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

Important: If the environmental variable on your system isn't $JAVA_HOME, substitute the correct variable, such as $JAVA_7_HOME, or similar.

Step 2: Go to $TOMCAT_HOME/conf/server.xml and enable SSL

Use the following configuration to have Tomcat use the keystore /root/scim_tomcat_keystore that was generated from the preceding commands.

1
2
3
4
5
<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.

Step 4: Export the public certificate out of the keystore generated in step 1.

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 so that it can trust the Tomcat server and so that the connection is secure. You must execute this 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