Splunk® SOAR (Cloud)

REST API Reference for Splunk SOAR (Cloud)

Acrobat logo Download manual as PDF


The classic playbook editor will be deprecated soon. Convert your classic playbooks to modern mode.
After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:
Acrobat logo Download topic as PDF

REST System Settings

Update a subset of system settings such as the authentication providers.

/rest/system_settings

Update authentication providers.

Syntax

https://<username>:<password>@<host>/rest/system_settings

POST

Update the authentication provider settings by replacing the entire configuration or by replacing parts of it.

Request parameters
Authentication providers are modified with the following parameters.

Field Required Type Description
auth_settings optional Javascript Object A complex data structure containing all authentication providers.

The entirety of "auth_settings" must be submitted in a single post. Partial updates are not supported.

Each section is modified with the following keys at the top level.

Field Required Type Description
enabled required Boolean Flag indicating if this section is enabled (applies to all of each ldap/saml2/openid sections).
providers required Javascript array of objects An array of the provider configurations. JSON for each provider described below.
type required String Type should match the name of the section. One of saml2, openid or ldap.

LDAP providers are modified with the following keys.

Field Required Type Description
name required String The name of the provider configuration entry.
type required String Type of provider, should match the section. One of saml2, openid or ldap.
id required String ID of the provider, this should be a GUID-like entry.
host required String IP or hostname of the provider.
domain required String LDAP domain.
enabled required String Flag indicating if the provider is enabled.
username required String Username for the service account used to query the provider.
force_ssl optional Boolean If set to true, will only connect using ldaps. Otherwise will use ldap.
password optional String The password for the service account used to query the provider. Required if not using a credential manager to store your password.
use_credential_manager optional Boolean Flag indicating if the service account password should be retrieved from the credential manager.
cm_key optional String Key for identifying the password in the credential manager. Required if using a credential manager.
cm_path optional String Path for identifying the password in the credential manager. Required if using a credential manager.
cm_safe optional String Identifies the Safe that contains the credentails in Cyberark. Required if using Cyberark as a credential manager.
test_username optional String Username for testing LDAP access and queries.
test_group optional String Used to verify the test_username is in the expected group. Requires the test_username to be set.
user_attr_map optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "django_attr" key should have one of the following values.
  • username
  • email
  • first_name
  • last_name
  • title
  • location
  • time_zone

The "external_attr" key should contain the name of the LDAP attribute used to populate the django attribute.

group_role_mappings optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "role" key should contain the numeric ID of the role. The "group" key should contain the name of the LDAP group that translates to the group

SAML2 providers are modified with the following keys.

Field Required Type Description
name required String The name of the provider configuration entry.
type required String Type of provider, should match the section. One of saml2, openid or ldap.
id required String ID of the provider, this should be a GUID-like entry.
issuer_id required String The issuer ID (URI) given by your provider
metadata_url required String The URL to retrieve SAML metadata. This is the preferred method of obtaining provider metadata since it should always be up-to-date.
metadata_xml required String The XML containing the SAML provider metadata. This is used for out-of-band configuration.
single_sign_on_url required String URL used to gain user consent/authorization from the identity provider. Users will be redirected here for login when using SAML2.
enabled required String Flag indicating if the provider is enabled.
phantom_base_url optional String Base URL for the instance. Not required only if the FQDN has been set in Company Settings.
force_ssl optional Boolean Flag indicating if SSL is required (defaults to FALSE).
group_key optional String Used to locate group data in the SAML assertion, treated as a mapping object, e.g. {"groups": ["group1", "group2", "group3"]} (defaults to "groups").
user_attr_map optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "django_attr" key should have one of the following values. Can be used if attributes are not auto-populated correctly.
  • username
  • email
  • first_name
  • last_name
  • title
  • location
  • time_zone

The "external_attr" key should contain the name of the LDAP attribute used to populate the django attribute.

group_role_mappings optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "role" key should contain the numeric ID of the role. The "group" key should contain the name of the LDAP group that translates to the group.

OpenID providers are modified with the following keys.

Field Required Type Description
name required String The name of the provider configuration entry.
type required String Type of provider, should match the section. One of saml2, openid or ldap.
id required String ID of the provider, this should be a GUID-like entry.
client_id required String Client ID given by the identity provider.
enabled required String Flag indicating if the provider is enabled.
service_discovery_url required String URL where the issuer provides service information.
phantom_base_url optional String Base URL for the instance. Not required only if the FQDN has been set in Company Settings.
force_ssl optional Boolean Username for the service account used to query the provider.
client_secret optional String The client_secret. Required if not using a credential provider and token_endpoint_auth_method is set to client_secret_post.
use_credential_manager optional Boolean Flag indicating if the service account password should be retrieved from the credential manager.
cm_key optional String Key for identifying the password in the credential manager. Required if using a credential manager (Cyberark/Hashicorp/Thycotic).
cm_path optional String Path for identifying the password in the credential manager. Required if using a credential manager (Cyberark/Hashicorp/Thycotic).
cm_safe optional String Identifies the Safe that contains the credentials in Cyberark. Required only if using Cyberark as a credential manager.
cm_mapping optional String The fieldName in the Thycotic secret which has the credential. Required only if using Thycotic as a credential manager.
scope optional String Comma delimited list of scopes.
resource optional String Used to identify the protected resource which contains user claims, information about the user. Leave blank to use the Userinfo endpoint
user_attr_map optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "django_attr" key should have one of the follwoing values.
  • username
  • email
  • first_name
  • last_name
  • title
  • location
  • time_zone
The "external_attr" key should contain the name of the LDAP attribute used to populate the django attribute.
group_role_mappings optional JSON Array of JSON Objects Each entry of the array should contain two key-value pairs. The "role" key should contain the numeric ID of the role. The "group" key should contain the name of the LDAP group that translates to the group.
group_key optional String Used to locate group data in the data returned by the OpenID identity provider, treated as a mapping object, e.g. {"groups": ["group1", "group2", "group3"]} (defaults to "groups").


Example request
Completely replace the authentication settings by doing the following:

curl -k -u username:password https://localhost/rest/system_settings \

	"auth_settings": {
		"ldap": {
			"enabled": true,
			"providers": [{
				"cm_key": "value",
				"cm_path": "secret/ldap",
				"domain": "example.com",
				"enabled": true,
				"group_role_mappings": [],
				"host": "1.1.1.1",
				"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
				"name": "LDAP Provider 1",
				"password": "<password>",
				"test_group": "HR",
				"test_username": "alice",
				"type": "ldap",
				"use_credential_manager": true,
				"user_attr_map": [],
				"username": "ldap-service-account"
			}],
			"type": "ldap"
		},
		"openid": {
			"enabled": true,
			"providers": [{
					"client_id": "<client id>",
					"client_secret": "<client secret>",
					"enabled": true,
					"force_ssl": false,
					"group_key": "role",
					"group_role_mappings": [{
						"group": "HR",
						"role": "31"
					}],
					"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
					"name": "OpenID - ADFS",
					"phantom_base_url": "http://example.com",
					"resource": "companyresource",
					"scope": "openid",
					"service_discovery_url": "https://example.com",
					"token_endpoint_auth_method": "private_key_jwt",
					"type": "openid",
					"user_attr_map": [{
						"django_attr": "username",
						"external_attr": "given_name"
					}]
				},
				{
					"client_id": "<client id>",
					"client_secret": "<client secret>",
					"enabled": true,
					"group_role_mappings": [{
						"group": "special group",
						"role": "31"
					}],
					"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
					"name": "OpenID - Okta",
					"phantom_base_url": "http://example.com",
					"service_discovery_url": "https://example.com",
					"type": "openid",
					"user_attr_map": []
				}
			],
			"type": "openid"
		},
		"saml2": {
			"enabled": true,
			"providers": [{
				"enabled": true,
				"group_key": "role",
				"group_role_mappings": [{
					"group": "HR",
					"role": "31"
				}],
				"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
				"issuer_id": "http://example.com/provider",
				"metadata_url": "https://example.com/federationmetadata/2007-06/federationmetadata.xml ",
				"metadata_xml": "",
				"name": "SAML2 Provider 1",
				"phantom_base_url": "https://example.com",
				"single_sign_on_url": "https://example.com",
				"type": "saml2",
				"user_attr_map": []
			}],
			"type": "saml2"
		}
	}
}'

Example response
A successful POST returns a success or failure indicator and a message for each command.

    },
    "message": "At least one update operation succeeded. See individual responses.",
    "success": true,
    "auth_settings": {
        "failed": true,
        "message": "ID for ldap provider \"LDAP Provider 1\" does not appear to be a GUID"
    }
}

Example request
Modify parts of the auth settings list without replacing the entire thing. If "contents" is given, other operations are ignored. If the individual "cells" of the table are not strings, they are coerced to strings.

curl -k -u username:password https://localhost/rest/system_settings \
-d '{
	"ldap": {
		"enabled": true,
		"providers": [{
			"cm_key": "value",
			"cm_path": "secret/ldap",
			"domain": "example.com",
			"enabled": true,
			"group_role_mappings": [],
			"host": "1.1.1.1",
			"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
			"name": "LDAP Provider 1",
			"password": "<password>",
			"test_group": "HR",
			"test_username": "alice",
			"type": "ldap",
			"use_credential_manager": true,
			"user_attr_map": [],
			"username": "ldap-service-account"
		}],
		"type": "ldap"
	},
	"openid": {
		"enabled": true,
		"providers": [{
				"client_id": "<client id>",
				"client_secret": "<client secret>",
				"enabled": true,
				"force_ssl": false,
				"group_key": "role",
				"group_role_mappings": [{
					"group": "HR",
					"role": "31"
				}],
				"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
				"name": "OpenID - ADFS",
				"phantom_base_url": "http://example.com",
				"resource": "companyresource",
				"scope": "openid",
				"service_discovery_url": "https://example.com",
				"token_endpoint_auth_method": "private_key_jwt",
				"type": "openid",
				"user_attr_map": [{
					"django_attr": "username",
					"external_attr": "given_name"
				}]
			},
			{
				"client_id": "<client id>",
				"client_secret": "<client secret>",
				"enabled": true,
				"group_role_mappings": [{
					"group": "special group",
					"role": "31"
				}],
				"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
				"name": "OpenID - Okta",
				"phantom_base_url": "http://example.com",
				"service_discovery_url": "https://example.com",
				"type": "openid",
				"user_attr_map": []
			}
		],
		"type": "openid"
	},
	"saml2": {
		"enabled": true,
		"providers": [{
			"enabled": true,
			"group_key": "role",
			"group_role_mappings": [{
				"group": "HR",
				"role": "31"
			}],
			"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
			"issuer_id": "http://example.com/provider",
			"metadata_url": "https://example.com/federationmetadata/2007-06/federationmetadata.xml ",
			"metadata_xml": "",
			"name": "SAML2 Provider 1",
			"phantom_base_url": "https://example.com",
			"single_sign_on_url": "https://example.com",
			"type": "saml2",
			"user_attr_map": []
		}],
		"type": "saml2"
	}
}'

Example response
A successful POST returns a success or failure indicator and a message for each command.

  {
    "message": "At least one update operation succeeded. See individual responses.",
    "success": true,
    "auth_settings": {
        "failed": true,
        "message": "ID for ldap provider \"LDAP Provider 1\" does not appear to be a GUID"
    }
}

/rest/system_settings/features

This API is deprecated.
The /rest/system_settings/features API is deprecated as of version 6.2.1. Although this feature continues to function, it might be removed in a future version. Use the new /rest/feature_flag API instead.


In the version 6.2.1 Release Notes, see Deprecated features.

Enable or disable system settings features.

Syntax

https://<username>:<password>@<host>/rest/system_settings/features

Usage details
The system setting edit permissions are required to change this setting.

POST

Enable system settings features.

Request parameters
Features are modified with the following parameters.

Field Required Type Description
feature required String The feature: clickable_url, multi_tennancy, indicators.
set_feature_enabled required Boolean True or False.

Example request
Enable indicators as follows:

curl -k -u username:password https://localhost/rest/system_settings/features \
-d '{
	"feature": "indicators",
	"set_feature_enabled": "True"
}'

Example response
A successful POST returns a success or failure indicator and a message for each command.

{
	"message": "Updated feature enabled state",
	"enabled": "True",
	"feature": "indicators",
	"success": true
}

/rest/system_settings/events

Create or delete custom labels.

Syntax

https://<username>:<password>@<host>/rest/system_settings/events

Usage details
The system setting edit permissions are required to change this setting.

POST

Create a label.

Request parameters
Labels are created with the following parameters.

Field Required Type Description
add_label required Boolean Whether or not the label is added. Available options are "true" or "false".
label_name required String The name for the label.

Example request

curl -k -u username:password https://localhost/rest/system_settings/events\
-d '{

    "add_label": true,
    "label_name": "test label"
}
}'

Example response
A successful POST returns a success or failure indicator and a message.

{
    "message": "Added label",
    "success": true
}

POST

Delete a label.

Request parameters
Labels are deleted with the following parameters.

Field Required Type Description
remove_label required Boolean Whether or not the label is deleted. Available options are "true" or "false".
label_name required String The name for the label.

Example request

curl -k -u username:password https://localhost/rest/system_settings/events\
-d '{

    "remove_label": true,
    "label_name": "test label"
}
}'

Example response
A successful POST returns a success or failure indicator and a message.

{
    "message": "Removed label",
    "success": true
}

/rest/system_settings optional query parameters

/rest/system_settings?sections

Get the status of feature system settings sections.

Syntax

https://<username>:<password>@<host>/rest/system_settings?sections

GET

Get the status of system settings.

Example request
Get the status of the mobile system setting.

curl -k -u username:password https://localhost/rest/system_settings?sections=["mobile"] -G -X GET

Example response
A successful GET will return back a JSON formatted list of key names and their data.

{
  "mobile": {
    "enabled": false
  }
}
Last modified on 27 March, 2024
PREVIOUS
REST Status
  NEXT
REST User

This documentation applies to the following versions of Splunk® SOAR (Cloud): current


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters