Create SCIM connectors


The Okta ProvisioningProvisioning is the enterprise-wide configuration, deployment, and management of multiple types of IT system resources. Specifically, provisioning provides users access to equipment, software, or services. This involves creating, maintaining and deactivating required business process automation objects and attributes in systems, directories, and applications. AgentA software agent is a lightweight program that runs as a service outside of Okta. It is typically installed behind a firewall and allows Okta to tunnel communication between an on-premises service and Okta's cloud service. Okta employs several agent types: Active Directory, LDAP, RADIUS, RSA, Active Directory Password Sync, and IWA. For example, users can install multiple Active Directory agents to ensure that the integration is robust and highly available across geographic locations. 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 orgThe Okta container that represents a real-world organization.. Communication between Okta and on-premises applications occurs through the Okta Provisioning Agent and a SCIMSystem for Cross-domain Identity Management (SCIM) is an open standard that allows for the automation of user provisioning. It was created in 2011 as it became clear that the technology of the future would be cloud-based. SCIM communicates user identity data between identity providers (such as companies with multiple individual users) and service providers requiring user identity information (such as enterprise SaaS apps). In short, SCIM makes user data more secure and simplifies the user experience by automating the user identity lifecycle management process. 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 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-domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). 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.

Requirements and installation

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

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

SDK package

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 groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with 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 appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in., 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 Configuring 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 getUsers
  getGroups
IMPORT_PROFILE_UPDATES getUser
GROUP_PUSH deleteGroup
  updateGroup
  createGroup
  getGroup

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 for detailed instructions.

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 tester to run methods against this example SCIM connector.

Note: These steps create a connector and make it available for testing. See the Deploy your Connector section below for information on integrating the connector with Okta after it is tested.

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 for detailed instructions.

Deploy your connector

After you create a connector and have copied the .war file to the Tomcat webapps directory, follow the steps in 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 below.

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:

  1. Generating a key for the SCIM Server and exporting a certificate.
  2. 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, OUAn acronym of Organizational Unit. Organizational units are Active Directory containers into which you can place users, groups, computers, and other organizational units. It is the smallest scope or unit to which you can assign Group Policy settings or delegate administrative authority.=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 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

Top