Create SCIM connectors for on-premises provisioning

The Okta Provisioning Agent enables you to 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 SCIM server or a provisioning connector built using Provisioning Connector SDK.

The connector receives SCIM messages from Okta Provisioning Agent and integrates with 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.

SCIM

SCIM is the System for Cross-domain Identity Management. 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.

Before you begin

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

  • The SDK package. It is 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 Okta Provisioning Agent SDK in the Admin Downloads section.
  • Java version 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 zip file. Simply unzip it to begin. The table below describes the contents.

File Description
README.TXT Package contents description. It contains the same information as this table.
LICENSE.TXT All licenses for referenced libraries.
lib/scim-server-sdk-*.jar SCIM Server Connector SDK library. See the example-server for usage.
example-server An example SCIM Server implementation using the Connector SDK. See its README.TXT for full details.
tester A stand-alone console application 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 connector SDK to integrate on-prem Apps 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. It is required that you 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 new user in on-prem application.

SCIMUser updateUser(String externalId, SCIMUser user)

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

SCIMUser getUser(String externalId)

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

SCIMUserQueryResponse getUsers(PaginationProperties pageProperties, SCIMFilter filter)

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

SCIMGroup createGroup(SCIMGroup group)

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

SCIMGroup updateGroup(String externalId, SCIMGroup group)

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

SCIMGroupQueryResponse getGroups(PaginationProperties pageProperties)

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

void deleteGroup(String externalId)

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

Based on the feature supported by on-prem app, 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 on-prem App instance you create on Okta. See Connect to your SCIM connector for more details on how to configure an app.

The following table maps those Provisioning features you can set on the app instance on Okta to the methods in your SCIMService connector that enable them. These are the UserManagementCapabilities you can set in the code. They are not visible in Okta on the AppInstance page.

Provisioning feature SCIMService Method
PUSH_NEW_USER 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 instruction in the Example Connector section below.

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 which 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.
  3. mvn install:install-file -Dfile=<PATH TO THE JAR> -DgroupId=com.okta.scim.sdk -DartifactId=scim-server-sdk -Dpackaging=jar -Dversion=01.00.xx

    where is the SDK version number. For complete build instructions the contain this command with the correct version number, see the install.bat and install.sh files in the /lib folder.

  4. Build the example, with the following command.

    mvn package

  5. 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 on-premises 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 your 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.

For http communication between the agent and the SCIM Server, see Using http below. Please note that https is the recommended protocol.

Using http

Before choosing this method, note that 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 detailed instructions listed below for enabling SSL are also located in the example-server/README.txt file.

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

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 &lt;scim_tom&gt;

(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 in the place of the above command to generate the key. Note that the command below 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 is not $JAVA_HOME, substitute the correct variable, such as $JAVA_7_HOME, etc.

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

Use the configuration below which asks Tomcat to use the keystore /root/scim_tomcat_keystore that was generated in the commands listed above.

<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.

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

See also