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:
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.
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.
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.
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.
|
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 } }
REST Status | REST User |
This documentation applies to the following versions of Splunk® SOAR (Cloud): current
Feedback submitted, thanks!