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 don't 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 . 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. Documentation for the testing utility is provided 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 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 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 that 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 the data directory of the testing utility package. |
| -header <headerName=headerValue> | Any additional HTTP header that 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 a connector built using Okta Connector SDK, the tester passes a User object to create a user using your connector. Tests the connector method SCIMService.createUser createPendingUser Http requests sent: POST /Users If you're 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're 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're testing a connector built with the Okta Connector SDK, the tester queries your connector to check if a specific user exists. It requires the following properties: userIdFieldName and userIdFieldValue. It tests the connector method SCIMService.getUsers (with a filter). importUserProfile HTTP requests sent: GET /Users/<Id> If you're 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're testing a 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're 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're 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're 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're 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're 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're 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're 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're 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're 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. The following examples and the input data files in the data folder of the default implementation 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
createNewUser passes a SCIM User object in an attempt to create a user using your connector. It tests the SCIMService.createUser connector SDK method. There are two supplied example data files to test with.
The following test 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
createPendingUser passes a SCIM User object in 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 similar to createNewUser except the active field for all users is false.
$ java -jar scim-sdk-tests.jar -url http://localhost:8080 -method createPendingUser -file data/createPendingUser-withCustomExtension.json
downloadUsers
downloadUsers asks your connector to return the full list of users. It tests the SCIMService.getUsers connector method without passing it a filter.
The following test makes a request to your SCIM connector asking for all users. The returned users are 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.txtcheckUserExists
checkUserExists asks your connector if a specific user exists. It tests the SCIMService.getUsers connector method by passing it a filter. Requires the additional properties: userIdFieldName and userIdFieldValue.
The following test uses the supplied properties to make a request to your SCIM connector. The test assumes that your SCIM connector won't find a user with the userName myemail@domain.com.
The test should return output similar to the sample response.
$ 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 following code (omitting the -expectResults argument from the previous command) 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 finds a user, the user data and some Okta debugging information are output:
$ java -jar scim-sdk-tests.jar -url http://localhost:8080/ -method checkUserExists -arg userIdFieldName=id -arg userIdFieldValue=102Response:
[ 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
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 following test 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=101Response:
[ 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 to find, but no result is 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
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 is always 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
deactivateUser asks your connector to deactivate an existing user. It tests the SCIMService.updateUser connector method.
The following test 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 is always 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
reactivateUser asks your connector to activate a previously deactivated user. It tests the SCIMService.updateUser connector method.
The following test 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
pushPasswordUpdate asks your connector to update the password of an existing user. It tests the SCIMService.updateUser connector method.
The following test 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
pushProfileUpdate asks your connector to update the properties of an existing user. It tests the SCIMService.updateUser connector method.
The following test makes a request to your SCIM connector asking you to update the User. The entire user object is supplied to you, not an object that only contains 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
downloadGroups asks your connector to return the full list of groups. It tests the SCIMService.getGroups connector method.
The following test makes a request to your SCIM connector asking for all groups and the returned groups are logged to disk. The test can 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
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 following test 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 no group is found for the id, then the output is similar to the following response:
$ 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
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!The following example shows the output when the connector throws a DuplicateGroupException when asked to create a group:
$ 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 groupupdateGroup
updateGroup sends a group to the connector so that it can be updated. This tests the SCIMService.updateGroup connector method.
The following test makes 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
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] - OKNext steps
Related topics
Create SCIM connectors for on-premises provisioning using SDK