This tutorial explains how to download (export) an existing User Sync connector configuration, how to upload (import) it back again and how to modify (if needed) it and upload it back again.

That way you could re-use parts of existing configurations, i.e. on a staging server, without creating everything again by hand.
Normally this only makes sense, if you've added a lot of transformation rules across the config.

In our tutorial, we will show you two solutions. You can use REST API or a cheat code to get access to the JSON configuration file directly.

The steps below are intended for users who are familiar with REST and JSON, please contact our support, if you have any doubts.

Changing a configuration that way should be done with good care.

REST API

Export Configuration - REST

  1. Find the User Sync connector ID by clicking on the edit button first, and then scroll down to the Connector ID field of the first tab.



cURL

GET the connector configuration. The URL to retrieve the config looks like this, with the connector ID at the end:

curl -u user:password -X GET https://<baseurl>/rest/samlsso-admin/1.0/usersync/connector/<connector-ID>
CODE

You could also directly create a JSON file with the content of the connector configuration. In our example, we will create a JSON file called 'usersync_export.json' in the directory '~/Downloads/'

curl -u user:password -X GET https://<baseurl>/rest/samlsso-admin/1.0/usersync/connector/<connector-ID> --output ~/Downloads/usersync_export.json
CODE


Postman

  1. GET the connector configuration. The URL to retrieve the config looks like this, with the connector ID at the end:

    https://<basurl>/rest/samlsso-admin/1.0/usersync/connector/68e7f826-af8d-43f3-b303-4d3a28e83993
    CODE
  2. Use a local user and password (or API Token) with admin permissions for the Basic Auth. REST doesn't work with SAML.

Modify Configuration - REST

  1. Extract the configuration from the response
    1. not everything in the response from the call above is the configuration, you only need to preserve the configuration node of the JSON response
    2. We recommend pasting the response to a config.json file and open it in a text editor like Notepad++ or any other editor which highlights opening and closing brackets
    3. the below example shows the part which requires to be extracted, the value of the configuration field, including the curly brackets
      1. some child nodes have been collapsed for better readability

  2. Copy that part, paste it to a new file and edit it as required
    1. in the sample below, I've changed the connector name and added a transformation

Import Configuration - REST

cURL

PUT (import) the edited configuration back to your instance. If you import a modified configuration it is important that your JSON file only contains the configuration node of the connector.

curl -u user:password -X PUT https://<baseurl>/rest/samlsso-admin/1.0/usersync/connector/<connector-id> -d @usersync_import.json --header "Content-Type: application/json"
CODE


Postman

  1. Copy the edited configuration and paste it back to Postman...
    1. ... into the Body tab with the radio button at "raw" and As JSON
    2. change the request method to PUT and press send



    3. you should get a 200 OK Result and see the complete response again 

    4. checking the User Sync connector via the UI after refreshing the page should reflect the changes

JSON

Export Configuration - JSON

  1. Open the User Sync connector, you want to export, by clicking on the edit button first.

us_json_export_edit

  1. Just type the cheat code 'godmode' to open a new dialog with the JSON-data.

us_json_export_cheat-code

  1. Extract the configuration from the response
    1. We recommend pasting the response to an us-export.json file and open it in a text editor like Notepad++ or any other editor which highlights opening and closing brackets

us_json_export_json-file

Modify Configuration - JSON

  1. Open the us-export.json file in a text editor like Notepad++ or any other editor which highlights opening and closing brackets.
  2. Not everything in the file is the configuration, you only need to preserve the configuration node of the JSON response
  3. Edit the file as required
    1. in the sample below, I've changed the connector name and added a transformation

us_json_modify_json-file

Import Configuration - JSON

  1. Just create a new connector

us_json_import_create-new-connector

  1. You don't need to start any configuration, just type the cheat code 'godmode' again.

us_json_import_cheat-code

  1. Delete the current configuration, which you see in the current connector configuration dialog.
  2. Copy & Paste your saved (or modified) configuration into the dialog.
  3. Apply the dialog (just press Close)
  4. Save and Return the User Sync Connector configuration.
  5. Checking the User Sync connector via the UI after refreshing the page should reflect the changes

Patch a connector configuration

It's possible to update specific parts of the configuration using HTTP PATCH. This can be done either using JSON Merge Patch (RFC 7686) or JSON Patch (RFC 6902).

JSON  Patch

To update specific values, send a JSON patch (see https://jsonpatch.com/) as HTTP Patch with content-type application/json-patch+json

[{ 
	"op": "replace",
 	"path": "/redirectToSso", 
	"value": true 
}]
CODE 
curl -u username:password -X PATCH https://base-url/rest/samlsso-admin/1.0/config -d @patched_json.json --header "Content-Type: application/json-patch+json"
CODE


JSON Merge Patch

JSON Merge patch allows to just specify the JSON-fragment that should be changed (see https://datatracker.ietf.org/doc/html/rfc7386). To use this syntax, send the JSON as HTTP Patch with content-type application/merge-patch+json.

{
	"redirectToSso" : true
}
CODE 


curl -u username:password -X PATCH https://base-url/rest/samlsso-admin/1.0/config -d @patched_json.json --header "Content-Type: application/merge-patch+json"
CODE