Create SCIM connectors for on-premises provisioning using SDK

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

Use the information provided here to build a customized SCIM connector for on-premises provisioning using the Provisioning Connector SDK. This information compliments the instructions for creating and testing SCIM connectors and modifying sample code found in Create SCIM connectors for on-premises provisioning.

Build process

Complete this procedure to develop a SCIM implementation. The bulk of coding and testing occurs in steps 7-8.

Copy the scim-server-example directory to a location of your choice. Perform the rest of the steps inside of the new directory.
Delete the src/main/java/com directory to remove the Store implementation.
Delete the src/test/java/com directory to remove the Store implementation tests.
Open your IDE and edit pom.xml and rename groupId and artifactId as desired.
Edit the MANIFEST.MF file and rename as needed.
Add your own class (connector) that implements the com.okta.scim.server.service.SCIMService interface.
Create and add tests for your new connector.
Open webapps/WEB-INF/dispatcher-servlet.xml and change the com.okta.scim.server.example.SCIMServiceImpl to the class that you wrote to implement the SCIMInterface.
Run the command mvn verify.
Run the .war file in Tomcat and validate it using the scim-sdk-tests tool.

Javadoc

The Javadoc is the primary technical resource for building SCIM connectors.

Example code

The file Store.java is an example to show how to integrate with the SDK. This class is not performant, concise, or complete. It shows how to work with the data model of the SDK. The Javadoc for Store contains detailed technical information and is the primary resource for your code.

SCIMInterface methods

The following methods are available in the SCIMInterface to build a connector. For detailed information, see the Javadoc or the comments in the file SCIMService.java.

Method	Use
createGroup(SCIMGroup group)	Create a group. All the standard attributes of the SCIM group can be retrieved by using the getters on the GroupResource member of the SCIMGroup object. If there are custom schemas in the SCIMGroup input, you can retrieve them by providing the name of the custom property. (Example : SCIMGroup.getStringCustomProperty("schemaName", "customFieldName")), if the property is of String type. This method is invoked when a POST is made to /Groups with a SCIM payload representing a group to create. Note: Implementation of this method requires that you implement the getGroups method as well.
createUser(SCIMUser user)	Create a user. All the standard attributes of the SCIM User can be retrieved by using the getters on the UserResource member of the SCIMUser object. If there are custom schemas in the SCIMUser input, you can retrieve them by providing the name of the custom property. (Example : SCIMUser.getStringCustomProperty("schemaName", "customFieldName")), if the property of string type. This method is invoked when a POST is made to /Users with a SCIM payload representing a user to be created.
deleteGroup(java.lang.String id)	Delete a particular group. This method is invoked when a DELETE is made to /Groups/{id}.
getGroup(java.lang.String id)	Get a particular group. This method is invoked when a GET is made to /Groups/{id}.
getGroups(PaginationProperties pageProperties)	Get all the groups. This method is invoked when a GET is made to /Groups In order to support pagination (So that the client and the server) are not overwhelmed, this method supports querying based on a start index and the maximum number of results expected by the client. The implementation is responsible for maintaining indices for the SCIM groups.
getImplementedUserManagementCapabilities()	Get all the User Management capabilities implemented in this SCIM Service.
getUser(java.lang.String id)	Get a particular user. This method is invoked when a GET is made to /Users/{id}.
getUsers(PaginationProperties pageProperties, SCIMFilter filter)	Get all the users. This method is invoked to support pagination and when a GET is made to /Users (to avoid overwhelming the client and the server). This method supports querying based on a start index and the maximum number of results expected by the client. The implementation is responsible for maintaining indices for the SCIM Users. This method also supports querying based on a filter. This method also supports querying based on a filter. If incremental imports are supported, then this method should support filtering based on the meta.lastModified attribute.
updateGroup(java.lang.String id, SCIMGroup group)	Update a group. This method is invoked when a PUT is made to /Groups/{id} with the SCIM payload representing a group to update.
updateUser(java.lang.String id, SCIMUser user)	Update a user. This method is invoked when a PUT is made to /Users/{id} with the SCIM payload representing a user to update.

Exceptions

The following exceptions are thrown from the methods in the SCIMInterface.

EntityNotFoundException	When an update, delete, or get request is received for /Users or /Groups, but the resource with the ID is not found.
DuplicateGroupException	When a create request for /Groups is received, but a duplicate group exists.
OnPremUserManagementException	If there is any other exceptional condition that you have defined.

For EntityNotFoundException and DuplicateGroupException the SDK associates an error code and a message with the exception automatically.

For OnPremUserManagementException you can create the exception with any of the following four different properties.

Internal Code - Any arbitrary code to associate with the exception.
Description - Description for the exception.
Helper URL - If there is any URL for referral to help fix the issue.
Exception - Any associated exception.

Note: For all exceptions described above, if the code throws the exception while processing a UM operation, the exception is serialized into a json string that is visible in Okta UI, as shown below.

"Failed on 11-24-2013 11:15:25PM UTC: Unable to delete Group Push mapping target App group ogroup-1: Error while deleting user group ogroup-1: The Provisioning Agent call to deleteGroup failed. Error code: 404, error: Not Found. Errors reported by the connector : {"errors":[{"statusCode":404,"internalCode":"E0000048","description":"Cannot delete the group - Cannot find the group with the id [1004]","help_url":null}]}"

Next steps