Problem

We are looking for a REST API endpoint to import the SAML config JSON file, i.e. to adjust the SSO config for a clone from a production system.

Solution

This article refers to our plugin version SAML Single Sign-On 4.x. If you are using an older version, you need to disable the plugin and enable it again, after deleting a configuration via API.

You can use the REST API of the SAML SSO app which allows you to download and upload the SAML Single Sign-On configuration.
Please note that this is our private API, there might be breaking changes in upcoming versions. Please contact our support, if something does not work as expected anymore.

If you want to adjust a config of a cloned instance via UI first and without being redirected to the IdP, use the nosso parameter to login.
If nosso isn't enabled, see here how to enable it as an admin via REST.

Also, if you are using Datacenter, try not to log in directly to a single node, to avoid problems with the SSO config UI not loading,
because of XSRF checks failing (i.e. accessing the node via HTTP only etc.)

GET (Retrieving an existing configuration)

Use the following example to download the configuration to the folder where you executing the command from. You could also use an app like Postman or Paw.
Just use basic authentication and an admin user and password or API token.
Read more about REST API authentication here.

curl -u username:password -X GET https://base-url/rest/samlsso-admin/1.0/config --output saml.json

or add the path to where you want to save it

curl -u username:password -X GET https://base-url/rest/samlsso-admin/1.0/config --output /path/to/saml.json

Verify that the saml.json file contains data and not HTML code because of failed authentication or similar.

Adjusting a configuration

You might have different reasons for updating a configuration via REST, but most of the time it is related to changing a configuration of a cloned instance.
Please refer to the below instructions for some guidance.

Production Clones

If you are cloning a production system into a development or staging system with the same base URL on a regular basis, the best idea is to create the configuration for the clone with the UI for the first time and update it via REST from each subsequent refresh of the clone.
The main reason for that is that the metadata from the identity provider has to be reloaded. That wouldn't happen automatically when uploading the configuration via REST.

Generic Configuration Changes

Usually, you need to change the following fields of a configuration, when using it on another instance.

Identity Provider Independent/ General Settings

Entity ID

This requires a change of the base URL of the Atlassian instance first:
Example for Jira/ Example for Confluence
The easiest way to change the entity ID then is to also use a REST call:

curl -u username:password -X POST https://base-url/rest/samlsso-admin/1.0/reset/entityid

IdP Specific Settings

Each IdP configuration has its own node in the JSON tree.

A single config would look like this:

    {
      "id": 2,
      "weight": 5,
      "name": "TIDP",
      "description": null,
      "postBindingURL": "https://some.idp.com/identifier/",
      "postBindingLogoutURL": null,
      "postBindingLogoutResponseURL": null,
      "redirectBindingURL": null,
      "redirectBindingLogoutURL": null,
      "redirectBindingLogoutResponseURL": null,
      "selectedLoginBinding": "POST",
      "selectedLogoutBinding": "DISABLE",
      "protocolBindingOfResponse": "SAME_AS_REQUEST",
      "nameIdFormatInRequest": "NONE",
      "entityId": "https://some.idp.com/identifier/",
      "certificates": [],
      "denyMessagesSignedWithExpiredCertificates": false,
      "relayStateParameterName": "RelayState",
      "useridAttribute": null,
      "idpType": "OTHER",
      "findByAttributeName": "ATTR_EMAIL",
      "directoryIdForNewUsers": 1,
      "groupsForNewUsers": [],
      "groupsForNewSdCustomers": [],
      "organizationsForNewSdCustomers": [],
      "removeFromGroups": false,
      "addNonExistingGroups": true,
      "addNonExistingOrganizations": true,
      "updateExisting": true,
      "enableUserCreation": true,
      "enableUserReactivation": false,
      "enableUserRenaming": false,
      "signRequests": true,
      "metadataurl": "https://some.idp.com/identifier/metadata",
      "metadataxml": null,

		... and more

Make the changes required and proceed with uploading the configuration.

PUT (Uploading a configuration again)

The following example shows how to upload a configuration again. It uses the file as a source again, see the GET example in the beginning.
You need to execute it from the folder in which the file is located  

curl -u username:password -X PUT https://base-url/rest/samlsso-admin/1.0/config -d @saml.json --header "Content-Type: application/json"

or add the path to it

curl -u username:password -X PUT https://base-url/rest/samlsso-admin/1.0/config -d @/path/to/saml.json --header "Content-Type: application/json"

With Postman, it would work like this:

Verify, that the correct configuration has been imported correctly

DELETE (Deleting Complete Configuration)

You could also delete existing configurations with the call below, i.e. for a simple test of importing a configuration again or to set up the config from scratch.
The SAML SSO configuration menu should then not show any identity provider config anymore. 

curl -u username:password -X DELETE https://base-url/rest/samlsso-admin/1.0/config

Once you open the SAML Single Sign-On configure again, you should see the wizard screen again, indicating that no configuration is present anymore.

This call will only delete the latest configuration version that is currently running in the plugin. In case you have multiple configurations stored in the database, only the latest one will be deleted. You will have multiple configuration versions when you upgrade the plugin to the next major release. 

When you delete the configuration and reload the UI the configuration of the former version will be migrated to your running plugin version and displayed, but it will not be active unless you save the configuration again. 

PATCH

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 
}]

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"

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
}

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"