Building SCIM Connectors Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka0f0000000ay3fkaw&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2f30504778-building-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.
Building SCIM Connectors
Published: Jan 10, 2015   -   Updated: Jun 22, 2018

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.

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 article contains technical information on how to build a customized SCIM connector using the SDK. It builds on the information on creating and testing SCIM connectors and modifying sample code found in Creating SCIM Connectors.

Build Process

The following ten steps outline the process to develop a SCIM implementation. The bulk of coding and testing occurs in steps 7-8.
  1. Copy the scim-server-example directory to a location of your choice. Perform the rest of the steps inside of the new directory.
  2. Delete the src/main/java/com directory to remove the Store implementation.
  3. Delete the src/test/java/com directory to remove the Store implementation tests.
  4. Open your IDE and edit pom.xml and rename groupId and artifactId as desired.
  5. Edit the MANIFEST.MF file and rename as needed.
  6. Add your own class (connector) that implements the com.okta.scim.server.service.SCIMService interface.
  7. Create and add tests for your new connector.
  8. 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.
  9. Run the command mvn verify.
  10. Run the .war file in Tomcat and validate it using the scim-sdk-tests tool.

Javadoc

The Javadoc is available at http://developer.okta.com/docs/sdk/opp/javadoc/index.html. 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 Overview

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 when a GET is made to /Users 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 Users. This method also supports querying based on a filter.
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. 

Exception
 
When Thrown
EntityNotFoundExceptionWhen an update, delete, or get request is received for /Users or /Groups, but the resource with the ID is not found.
DuplicateGroupExceptionWhen 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}]}"