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 admin:changeme 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 admin:changeme 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

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 admin:changeme 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 admin:changeme 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
  }
}