Test SCIM connectors for on-premises provisioning
Okta provides a utility to test SCIM connectors built with the Okta Provisioning Connector SDK or any custom SCIM connector or SCIM server. You do not have to connect to Okta and the Okta Provisioning Agent to test your connector.
The testing utility is part of the Okta Provisioning Connector SDK package, available on the Okta Downloads page. To obtain the Okta Provisioning Connector SDK package, sign in to the Admin Console and select Settings > Downloads. Then click Download for the Okta Provisioning Connector SDK.
The testing utility is contained in the scim-sdk-test.jar in the tester folder of the Okta Provisioning Connector SDK. Full documentation for the testing utility is located in the tester/README.TXT file. The primary focus of the tests is to validate the response from your SCIM connector or SCIM server.
Test data
Test data is located in the .json files in the tester/data directory. You can use or modify these files to test your connector. All the tests assume that the input data is valid. Edit or create the sample data files carefully.
Running tests
Run the tests by using the scim-sdk-tests.jar file. To see all possible arguments, run the jar without any arguments.
java -jar scim-sdk-tests.jar
Complete testing information including calls, responses, all options, and sample results are shown in the tester/README.TXT file. The following code shows a very typical test call. The minimum number of parameters are passed.
- url: the base URL of the SCIM server
- method: the OKTA provisioning method to test
- file: the input data file
Sample test call
The following is a sample test call:
java -jar scim-sdk-tests.jar -url http://localhost:8080 -method createNewUser -file data/createNewUser.json
Tester usage
To see all possible arguments, run the jar without any arguments.
java -jar scim-sdk-tests.jar
usage: scim-sdk-tests
The following table details the arguments you can pass.
Argument | Description |
-arg <propertyName=propertyValue> | Pass any property name and value pair for your method to use. |
-expectResults <true|false> | Set test expectations on if results should come back from the connector for the current method. This can be used with the following methods: checkUserExists, downloadUsers, downloadGroups, and importUserProfile. |
-file <fileName> | The data file to use as input for the current method. Sample files are provided in data directory of testing utility package. |
-header <headerName=headerValue> | Any additional HTTP header you want sent to the SCIM server. For example, X-Internal-AuthHeader=secret |
-method <methodName> |
createNewUser HTTP requests sent: GET /Users?filter=userName=myemail@domain.com&startIndex=1&count=100 POST /Users If testing connector built using Okta Connector SDK, the tester passes a User object to create a new user using your connector. Tests the connector method SCIMService.createUser createPendingUser Http requests sent: POST /Users If you are testing a connector built using the Okta Connector SDK, the tester passes a User object to create a pending user using your connector. It tests the connector method SCIMService.createUser. downloadUsers HTTP requests sent: GET /Users?startIndex=1&count=100 If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to return the full list of users. It tests the connector method SCIMService.getUsers (without a filter). checkUserExists HTTP requests sent: /Users?filter=userName=myemai@domain.com&startIndex=1&count=100 If you are testing a connector built with the Okta Connector SDK, the tester queries your connector if a specific user already exists. It requires the following additional properties: userIdFieldName and userIdFieldValue. It tests the connector method SCIMService.getUsers (with a filter). importUserProfile HTTP requests sent: GET /Users/<Id> If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to return a single user, passing it the user's ID. It requires the additional property, id. It tests the connector method SCIMService.getUser activateUser HTTP requests sent: PUT /Users/<id> If you are testing connector built with Okta Connector SDK, the tester queries your connector to activate an existing user. It tests the connector method SCIMService.updateUser. deactivateUser HTTP requests sent PUT /Users/<id>: If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to deactivate an existing user. It tests the connector method SCIMService.updateUser. reactivateUser HTTP requests sent: PUT /Users/<id> If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to reactivate an existing user. It tests the connector method SCIMService.updateUser. pushPasswordUpdate HTTP requests sent: PUT /Users/<id> If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to update the password of an existing user. It tests the connector method SCIMService.updateUser pushProfileUpdate – Okta asks your connector to update the properties of an existing user. It tests the connector method SCIMService.updateUser. deleteGroup HTTP requests sent: DELETE /Groups/<id> If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to delete a group. It tests the connector method SCIMService.deleteGroup. updateGroup HTTP requests sent: PUT /Groups/<id> If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to update a group. It tests the connector method SCIMService.updateGroup. createGroup HTTP requests sent: POST /Groups If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to create a group. It tests the connector method SCIMService.createGroup. getGroupById HTTP requests sent: If you are testing a connector built with the Okta Connector SDK, the tester queries your connector to return a group based on the ID. It tests the connector method SCIMService.getGroup. downloadGroups HTTP requests sent: GET /Groups?startIndex=1&count=100 If you are testing a connector built with the Okta Connector SDK, the tester asks your connector to return the full list of groups. It tests the connector method SCIMService.getGroups. getImplementedUserManagementCapabilities HTTP request sent: GET /ServiceProviderConfigs If you are testing a connector built with the Okta Connector SDK, the tester asks your connector to return the list of UserManagementCapabilities your connector has implemented. Tests the connector method SCIMService.getImplementedUserManagementCapabilities |
-url <url> | The URL of the SCIM server to use. Example:http://acme.com:8080 |
Examples
The default implementation provided by Okta assumes that the appname is onprem_app and that the examples below and the input data files in the data folder use the custom schema name (urn:okta:onprem_app:1.0:user) for the App User custom schemas. When you implement the connector you need to use the correct appname.

createNewUser passes a SCIM User object in an attempt to create a new user using your connector. It tests the SCIMService.createUser connector SDK method. There are two supplied example data files to test with.
The test below sends the SCIM user defined in the createNewUser.json file to your SCIM connector. Some basic validation is performed on the user returned from your connector.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method createNewUser -file data/createNewUser.json
Response:
[ 04-10-2013 13:23:01.258 ] [ INFO] - making POST request to http://localhost:8080/Users
[ 04-10-2013 13:23:01.449 ] [ INFO] - Okta will use the ID 103 to identify this User in the future.
[ 04-10-2013 13:23:01.450 ] [ INFO] - User returned from connector:
schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0"
phoneNumbers:
value: "123-444-5555"
type: "mobile"
userName: "myemail@domain.com"
name:
familyName: "LastName"
givenName: "FirstName"
active: true
emails:
primary: true
value: "myemail@domain.com"
type: "primary"
primary: false
value: "mypersonalemail@domain.com"
type: "secondary"
password: "verySecure"
id: "103"
[ 04-10-2013 13:23:01.450 ] [ INFO] - OK!

createPendingUser passes a SCIM User object int an attempt to create a pending user using your connector. It tests the SCIMService.createUser connector SDK method. There are two supplied example data files to test with.
createPendingUser is almost identical to createNewUser except that the active field for all users will be false.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method createPendingUser -file data/createPendingUser-withCustomExtension.json

downloadUsers asks your connector to return the full list of users. It tests the SCIMService.getUsers connector method without passing it a filter.
The test below makes a request to your SCIM connector asking for all users and the returned users will be logged to disk. The test could make multiple requests to your connector if multiple pages of users exist.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method downloadUsers
Response:
[ 04-10-2013 14:14:18.888 ] [ INFO] - making GET request to http://localhost:8080/Users?startIndex=1&count=100
[ 04-10-2013 14:14:19.003 ] [ INFO] - downloadUsers: 3 Users returned.
[ 04-10-2013 14:14:19.007 ] [ INFO] - downloadUsers: Users returned from connector logged to downloadUsers-20131004-141419.txt

checkUserExists asks your connector if a specific user already exists. It tests the SCIMService.getUsers connector method by passing it a filter. Requires the additional properties: userIdFieldName and userIdFieldValue.
The test below uses the supplied properties to make a request to your SCIM connector. The test assumes that your SCIM connector will not find a user with the userName myemail@domain.com.
The output should look similar to this:
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method checkUserExists -arg userIdFieldName=userName -arg userIdFieldValue=myemail@domain.com -expectResults false
Response:
[ 03-10-2013 14:54:16.741 ] [ INFO] - making GET request to http://localhost:8080/Users?filter=userName%20eq%20%22myemail%40dom...
[ 03-10-2013 14:54:16.846 ] [ INFO] - checkUserExists: No users returned from server. This should be expected.
[ 03-10-2013 14:54:16.846 ] [ INFO] - OK!
Usage
Running the code below (leaving off the -expectResults argument) should cause the tests to fail:
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method checkUserExists -arg userIdFieldName=userName -arg userIdFieldValue=myemail@domain.com
Response:
[ 03-10-2013 14:57:41.218 ] [ INFO] - making GET request to http://localhost:8080/Users?filter=userName%20eq%20%22myemail%40dom...
[ 03-10-2013 14:57:41.319 ] [ ERROR] - Expected results from checkUserExists but did not get anything.
When your connector has found a user the user data will be printed out, in addition to some additional Okta debugging information:
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method checkUserExists -arg userIdFieldName=id -arg userIdFieldValue=102
Response:
[ 03-10-2013 15:01:14.095 ] [ INFO] - making GET request to http://localhost:8080/Users?filter=id%20eq%20%22102%22&startInd...
[ 03-10-2013 15:01:14.217 ] [ INFO] - checkUserExists: 1 users returned.
[ 03-10-2013 15:01:14.217 ] [ INFO] - checkUserExists: User returned from Connector:
schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user"
id: "102"
userName: "admin"
name:
formatted: "SCIM firstname2 SCIM lastname2"
givenName: "SCIM first2"
familyName: "SCIM last2"
middleName: "SCIM middle2"
emails:
value: "SCIM_admin@okta.com"
primary: true
type: "work"
active: false
password: "god"
groups:
value: "1002"
display: "secondGroup"
urn:okta:onprem_app:1.0:user:
isAdmin: true
isOkta: false
departmentName: "Administration"
[ 03-10-2013 15:01:14.217 ] [ INFO] - checkUserExists: The ID 102 will be used as the id for this user in Okta
[ 03-10-2013 15:01:14.217 ] [ INFO] - checkUserExists: The user will be returned as INACTIVE
[ 03-10-2013 15:01:14.218 ] [ INFO] - OK!
Use Cases
How to search for a user by first name
java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method checkUserExists -arg userIdFieldName=name.givenName -arg userIdFieldValue="SCIM first"
How to search for a user by a custom schema extension property
java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method checkUserExists -arg userIdFieldName=urn:okta:onprem_app:1.0:user:departmentName -arg userIdFieldValue="Cloud Service"

importUserProfile asks your connector to return a single user by passing it the user's ID. It tests the SCIMService.getUser connector method. Requires the additional property: id.
The test below makes a request to your SCIM connector asking for a user with the id of 101.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method importUserProfile -arg id=101
Response:
[ 04-10-2013 13:57:54.092 ] [ INFO] - making GET request to http://localhost:8080/Users/101
[ 04-10-2013 13:57:54.203 ] [ INFO] - importUserProfile: User returned from Connector:
schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user"
id: "101"
userName: "okta"
name:
formatted: "SCIM firstname SCIM lastname"
givenName: "SCIM first"
familyName: "SCIM last"
middleName: "SCIM middle"
emails:
value: "SCIM_okta@okta.com"
primary: true
type: "work"
active: true
password: "inSecure"
groups:
value: "1001"
display: "firstGroup"
value: "1002"
display: "secondGroup"
urn:okta:onprem_app:1.0:user:
isAdmin: false
isOkta: true
departmentName: "Cloud Service"
[ 04-10-2013 13:57:54.204 ] [ INFO] - importUserProfile: The ID 101 will be used as the id for this user in Okta
[ 04-10-2013 13:57:54.204 ] [ INFO] - OK!
Use Cases
The following shows how to search for a user that you expect not to exist:
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method importUserProfile -arg id=invalidExternalId -expectResults false
Response:
[ 04-10-2013 14:00:01.081 ] [ INFO] - making GET request to http://localhost:8080/Users/invalidExternalId
[ 04-10-2013 14:00:01.245 ] [ WARN] - error status of 404 received from http://localhost:8080/Users/invalidExternalId
[ 04-10-2013 14:00:01.245 ] [ INFO] - importUserProfile: No users returned from server. This should be expected.
[ 04-10-2013 14:00:01.246 ] [ INFO] - OK!
The following shows how to search for a user that you expect but nothing is actually returned:
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method importUserProfile -arg id=103
Response:
[ 04-10-2013 14:00:52.096 ] [ INFO] - making GET request to http://localhost:8080/Users/103
[ 04-10-2013 14:00:52.191 ] [ WARN] - error status of 404 received from http://localhost:8080/Users/103
[ 04-10-2013 14:00:52.191 ] [ ERROR] - Expected results from importUserProfile but did not get anything.

activateUser asks your connector to activate an existing user. It tests the SCIMService.updateUser connector method.
The test below makes a request to your SCIM connector asking you to update the User. Since this is a test to activate the user, the active field will always be true.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method activateUser -file data/activateUser.json
Response:
[ 10-10-2013 14:29:00.211 ] [ INFO] - making PUT request to http://localhost:8080/Users/101
[ 10-10-2013 14:29:00.598 ] [ INFO] - activateUser: will return to Okta that the user's active state is: true
[ 10-10-2013 14:29:00.598 ] [ INFO] - OK!

deactivateUser asks your connector to deactivate an existing user. It tests the SCIMService.updateUser connector method.
The test below makes a request to your SCIM connector asking you to update the User. Since this is a test to deactivate the user, the active field will always be false.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method deactivateUser -file data/deactivateUser.json
Response:
[ 10-10-2013 14:32:51.211 ] [ INFO] - making PUT request to http://localhost:8080/Users/101
[ 10-10-2013 14:32:52.171 ] [ INFO] - NOTE: deactivateUser does not send the user returned from the connector back to Okta. Okta assumes that a non-error response from your connector means the deactivateUser methods was successful.
[ 10-10-2013 14:32:52.598 ] [ INFO] - OK!

reactivateUser asks your connector to activate a previously deactivated user. It tests the SCIMService.updateUser connector method.
The test below makes a request to your SCIM connector asking you to update the User. Since this is a test to reactivate the user, the active field will always be true.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method reactivateUser -file data/reactivateUser.json
Response:
[ 10-10-2013 14:35:04.704 ] [ INFO] - making PUT request to http://localhost:8080/Users/101
[ 10-10-2013 14:35:04.828 ] [ INFO] - NOTE: reactivateUser does not send the user returned from the connector back to Okta. Okta assumes that a non-error response from your connector means the reactivateUser methods was successful.
[ 10-10-2013 14:35:04.828 ] [ INFO] - OK!

pushPasswordUpdate asks your connector to update the password of an existing user. It tests the SCIMService.updateUser connector method.
The test below makes a request to your SCIM connector asking you to update the User. Even though on the password has changed, the entire user object will be supplied to you.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method pushPasswordUpdate -file data/pushPasswordUpdate.json
Response:
[ 10-10-2013 14:36:52.029 ] [ INFO] - making PUT request to http://localhost:8080/Users/101
[ 10-10-2013 14:36:52.124 ] [ INFO] - NOTE: pushPasswordUpdate does not send the user returned from the connector back to Okta. Okta assumes that a non-error response from your connector means the pushPasswordUpdate methods was successful.
[ 10-10-2013 14:36:52.124 ] [ INFO] - OK!

pushProfileUpdate asks your connector to update the properties of an existing user. It tests the SCIMService.updateUser connector method.
The test below makes a request to your SCIM connector asking you to update the User. The entire user object will be supplied to you, not an object containing only the changed fields.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method pushProfileUpdate -file data/pushProfileUpdate.json
Response:
[ 10-10-2013 14:39:44.693 ] [ INFO] - making PUT request to http://localhost:8080/Users/101
[ 10-10-2013 14:39:44.785 ] [ INFO] - NOTE: pushProfileUpdate does not send the user returned from the connector back to Okta. Okta assumes that a non-error response from your connector means the pushProfileUpdate methods was successful.
[ 10-10-2013 14:39:44.786 ] [ INFO] - OK!

downloadGroups asks your connector to return the full list of groups. It tests the SCIMService.getGroups connector method.
The test below makes a request to your SCIM connector asking for all groups and the returned groups will be logged to disk. The test could make multiple requests to your connector if multiple pages of groups exist.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method downloadGroups
Response:
[ 10-10-2013 14:40:55.598 ] [ INFO] - making GET request to http://localhost:8080/Groups?startIndex=1&count=100
[ 10-10-2013 14:40:55.816 ] [ INFO] - downloadGroups: 2 Groups returned.
[ 10-10-2013 14:40:55.819 ] [ INFO] - downloadGroups: Groups returned from connector logged to downloadGroups-20131010-144055.txt
[ 10-10-2013 14:40:55.820 ] [ INFO] - OK!

getGroupById asks your connector to return a group based on the supplied ID. This tests the SCIMService.getGroup connector method. Requires the additional property: id.
The test below makes a request to your SCIM connector asking you to return the Group. All the properties of the group will be printed.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method getGroupById -arg id=1002
Response:
[ 17-10-2013 18:03:17.270 ] [ INFO] - making GET request to http://localhost:8080/Groups/1002
[ 17-10-2013 18:03:17.381 ] [ INFO] - getGroupById : Group returned from connector:
schemas: "urn:scim:schemas:core:1.0", "urn:okta:custom:group:1.0"
id: "1002"
members:
value: "User-001"
display: "First User"
value: "User-002"
display: "Second User"
displayName: "AppGroup-Changed"
urn:okta:custom:group:1.0:
description: "This is the changed first group"
[ 17-10-2013 18:03:17.381 ] [ INFO] - OK!
If a group is not found for the id, then you would see the output like below :
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method getGroupById -arg id=3455
Response:
[ 18-10-2013 10:22:40.733 ] [ INFO] - making GET request to http://localhost:8080/Groups/3455
[ 18-10-2013 10:22:40.833 ] [ WARN] - error status of 404 received from http://localhost:8080/Groups/3455
[ 18-10-2013 10:22:40.833 ] [ ERROR] - Expected results from getGroupById but did not get anything.

createGroup sends a group to the connector so that it can be created. This tests the SCIMService.createGroup connector method.
If the same group exists on your system, you should throw a DuplicateGroupException.
The test below makes a request to your SCIM connector asking you to create the group and return it. All the properties of the group will be printed.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method createGroup -file data/createGroup.json
Response:
[ 17-10-2013 18:09:02.457 ] [ INFO] - making POST request to http://localhost:8080/Groups
[ 17-10-2013 18:09:02.564 ] [ INFO] - Okta will use the ID 1004 to identify this Group in the future.
[ 17-10-2013 18:09:02.564 ] [ INFO] - Group returned from connector:
schemas: "urn:scim:schemas:core:1.0", "urn:okta:custom:group:1.0"
id: "1004"
members:
value: "User-003"
display: "Third User"
value: "User-004"
display: "Fourth User"
value: "User-005"
display: "Fifth User"
displayName: "AppGroup-02"
urn:okta:custom:group:1.0:
description: "This is the second group"
[ 17-10-2013 18:09:02.565 ] [ INFO] - OK!
If the connector throws a DuplicateGroupException when asked to create a group, you would see the following output:
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method createGroup -file data/createGroup.json
Response:
[ 18-10-2013 10:29:49.473 ] [ INFO] - making POST request to http://localhost:8080/Groups
[ 18-10-2013 10:29:49.576 ] [ WARN] - error status of 409 received from http://localhost:8080/Groups
[ 18-10-2013 10:29:49.577 ] [ ERROR] - Cannot create the group [{
"schemas": ["urn:scim:schemas:core:1.0", "urn:okta:custom:group:1.0"],
"displayName": "AppGroup-02",
"id": "1004",
"members" : [{"value": "User-003", "display": "Third User"},{"value": "User-004", "display": "Fourth User"},{"value": "User-005", "display": "Fifth User"}],
"urn:okta:custom:group:1.0":{
"description":"This is the second group"
}
}]. It already exists
[ 18-10-2013 10:29:49.577 ] [ ERROR] - Duplicate group found. Cannot create the group

updateGroup sends a group to the connector so that it can be updated. This tests the SCIMService.updateGroup connector method.
The test below will make a request to your SCIM connector asking you to update the group and return it.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method updateGroup -file data/updateGroup.json
Response:
[ 17-10-2013 18:11:11.842 ] [ INFO] - making PUT request to http://localhost:8080/Groups/1002
[ 17-10-2013 18:11:11.939 ] [ INFO] - NOTE: updateGroup does not send the group returned from the connector back to Okta. Okta assumes that a non-error response from your connector means the updateGroup methods was successful.
[ 17-10-2013 18:11:11.939 ] [ INFO] - OK!

deleteGroup sends an ID to the connector so that the group with that ID can be deleted. This tests the SCIMService.deleteGroup connector method. Requires the additional property: id.
An EntityNotFoundException should be thrown if a group with that id does not exist.
The test below makes a request to your SCIM connector asking you to delete the group.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method deleteGroup -arg id=1003
Response:
[ 17-10-2013 18:16:27.553 ] [ INFO] - making DELETE request to http://localhost:8080/Groups/1003
[ 17-10-2013 18:16:27.646 ] [ INFO] - NOTE: deleteGroup does not send any data back to Okta. Okta assumes that a non-error response from your connector means the deleteGroup was successful and the group with the Id 1003 was deleted
[ 17-10-2013 18:16:27.646 ] [ INFO] - OK!
Next steps
Related topics
Create SCIM connectors for on-premises provisioning using SDK