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.

Okta Provisioning Agent supports provisioning capabilities using SCIM 2.0, such as entitlement discovery, user creation/read/update/delete, and lifecycle management. It doesn't support push groups.

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)

The following examples use Maven to build the sample connector.

SDK package contents

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

File Description
README.TXT Describes the contents of the SDK package.
LICENSE.TXT All licenses for referenced libraries.
doc The Javadoc documentation for the Okta Provisioning Agent SDK.
lib/scim-server-sdk-*.jar SCIM Server Connector SDK library. See example-server for usage.
example-server An example SCIM server implementation using the Connector SDK. See its README.TXT for full details.
tester Okta Connector Tester. A standalone console app that mimics Okta provisioning commands to test a SCIM server and connector implementation in isolation. See its README.TXT for full details.

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.

Method

Description

UserManagementCapabilities[ ] getImplementedUserManagementCapabilities() This method returns the user management (provisioning) capabilities implemented by the connector.

This method is required, as 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 app.
SCIMUser updateUser(String externalId, SCIMUser user) This method is invoked when Okta sends an instruction to update an existing user in an on-premises app.
SCIMUser getUser(String externalId) This method is invoked when Okta sends an instruction to get a particular user from an on-premises app.
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 app.
SCIMGroup createGroup(SCIMGroup group) This method is invoked when Okta sends an instruction to create a group in an on-premises app.
SCIMGroup updateGroup(String externalId, SCIMGroup group) This method is invoked when Okta sends an instruction to update a group in an on-premises app.
SCIMGroupQueryResponse getGroups(PaginationProperties pageProperties) This method is invoked when Okta sends an instruction to get all groups from an on-premises app.
void deleteGroup(String externalId) This method is invoked when Okta sends an instruction to delete a particular group in an on-premises app.

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.

Provisioning feature SCIMService method
PUSH_NEW_USERS createUser
getUsers
PUSH_PASSWORD_UPDATES updateUser
PUSH_PENDING_USERS createUser
updateUser
getUsers
PUSH_PROFILE_UPDATES updateUser
PUSH_USER_DEACTIVATION updateUser
REACTIVATE_USERS updateUser
IMPORT_NEW_USERS

OPP_SCIM_INCREMENTAL_IMPORTS*

getUsers
getGroups
IMPORT_PROFILE_UPDATES getUser
GROUP_PUSH deleteGroup
updateGroup
createGroup
getGroup

* 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

The use of HTTP isn't recommended. The more secure option of HTTPS is highly encouraged.

  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

This command must be run from a Java 7 installation or above. If your environment variable for Java isn't JAVA_HOME, such as JAVA_7_HOME, substitute it in place of JAVA_HOME in the preceding command.

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 $CATALINA_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).

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

/opt/OktaProvisioningAgent/jre/bin/keytool -import -file /root/scim_tomcat.cert -alias scim_tom -keystore /opt/OktaProvisioningAgent/jre/lib/security/cacerts

Next steps

Test SCIM connectors for on-premises provisioning

Related topics

SCIM messages for on-premises provisioning