Creating SCIM Connectors Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka0f0000000ay3ykaw&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2f30093436-creating-scim-connectors
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Creating SCIM Connectors
Published: Jan 9, 2015   -   Updated: Feb 15, 2018

SDK Overview
Requirements and Installation
SDK Package
Creating your Connector
Example Connectors
Testing your Connector
Deploying your Connectors

Note: This document describes a component of the On-Premise Provisioning solution. This component cannot be added as a provisioning integration between Okta and a cloud service within the Okta Application Network. For that function, please contact Developers Support to learn more.

SDK Overview

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.  

This document provides information about how to build a connector using the Okta 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. The diagram below shows the data flow with a connector.

Data Flow Using Connector

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, the specification is located at http://tools.ietf.org/html/draft-scim-api-01
 

top

Requirements and Installation

There are three requirements to use the SDK to create a connector.

  1. 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.
  2. Java version 1.6 or 1.7.
  3. An IDE such as Eclipse or IntelliJ is strongly recommended.
  4. Maven is used in the examples to build the SDK.
  5. A web server to run your connector as a war file.
  6. MySQL to run example-mysql-server. [Optional]

top

SDK Package

The SDK package is a zip file. Simply unzip it to begin. The table below describes the contents.

FileDescription
README.TXTPackage contents description. It contains the same information as this table.
LICENSE.TXTAll licenses for referenced libraries.
lib/scim-server-sdk-*.jarSCIM Server Connector SDK library. See the example-server for usage.
example-serverAn example SCIM Server implementation using the Connector SDK. See its README.TXT for full details.
example-mysql-serverAn example connector for a MySQL database. See its README.TXT file for full details.
testerA 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.

 

top

Creating 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 Configuring Your SCIM connector for more details on how to configure an app.

The following table maps those Provisioning features to the methods in your 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 features you can set on App instance on Okta. This App instance represents the on-prem App that your connector integrates with.

Methods in SCIMService

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

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 Testing your SCIM Server or SCIM Connector for detailed instructions. 

top

Example Connectors

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

Example 1: 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.  

Example 2: example-mysql-server  

This is an example connector that integrates with MySQL server. MySQL in this example acts as an on-prem App that you want to integrate with Okta for the purpose of managing provisioning of users into MySQL.

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

  3. Build the example, with the following command

    mvn package

  4. Copy the target/scim-server-example-*.war file to your Tomcat directory and run it.
  5. 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 Deploying your Connector section below for information on integrating the connector with Okta after it is tested.

top

 

top

Testing 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 Testing your SCIM Server or SCIM Connector for detailed instructions. 

top

Deploying your Connector

After you create a connector and have copied the .war file to the Tomcat webapps directory, follow the steps in Configuring Your SCIM Connector to integrate the new connector. The five steps listed under the Creating 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 Enabling 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, please 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.

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

Detailed Instructions

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

 

Post a Comment

Comments

  • Ashish Agrawal on December 28, 2017

    For step 5, the default password for cacerts keystore is "changeit"

  • Maria Hernandez on December 17, 2017

    Kinda getting it finally sinking in.