Manage users, roles, and capabilities in Splunk Cloud Platform

The Admin Config Service (ACS) API lets you manage users, roles, and capabilities for your Splunk Cloud Platform deployment. You can use the ACS API to implement role-based access controls (RBAC) programmatically without assistance from Splunk Support.

For more information on RBAC in Splunk Cloud Platform, see About configuring role-based user access.

The Terraform Provider for Splunk Cloud Platform supports ACS users and roles operations. To access the Splunk Cloud Platform Terraform Provider (terraform-provider-scp), see the Terraform Registry.

Requirements

To manage users, roles, and capabilities in Splunk Cloud Platform using the ACS API:

• Your role must have the capabilities required to access the ACS API endpoint. The sc_admin role has all required capabilities by default. For a list of required capabilities, see Manage ACS API access with capabilities.
• You must have Splunk Cloud Platform version 8.0.2007 or higher.
• Your deployment must have one or more separate search heads or a search head cluster. ACS is not supported on single instance deployments.

Configure role-based access using the ACS API

This section shows you how to perform ACS API operations that let you configure role-based user access for your Splunk Cloud Platform deployment.

When you create a user in Splunk Cloud Platform, you assign the user one or more roles. Each role contains a set of capabilities that determine which actions a user assigned to that role can perform. You can use the ACS API to create users and roles, add capabilities to roles, and assign users to roles. For more information on roles and capabilities, see Define roles on the Splunk platform with capabilities.

Users and roles apply only on the search head on which you create them. ACS does not replicate users and roles across the search tier. By default ACS user and role operations apply to the first standard search head or search head cluster in your deployment. To create or update users and roles on additional search heads or premium search heads, you must target the specific search head on which you want to create or update the user or role. For more information, see Target a specific search head for ACS operations.

View capabilities

To view a list of capabilities in Splunk Cloud Platform, send an HTTP GET request to the capabilities endpoint. For example:

curl --location 'https://admin.splunk.com/{stack}/adminconfig/v2/capabilities' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'

By default ACS returns both systemCapabities and grantableCapabilities. systemCapabities are all Splunk Cloud Platform capabilities, while grantableCapabilities are only those capabilites the token user is authorized to grant to roles.

{
   "grantableCapabilities": [
       "accelerate_datamodel",
       "accelerate_search",
       "acs_conf",
      ...
   ],
   "systemCapabilities": [
       "accelerate_datamodel",
       "accelerate_search",
       "acs_conf",
       ...
   ]
}

To list grantable capabilities only, specify the grantableOnly=true query parameter in your request. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/capabilities?grantableOnly=true' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'

View existing roles

To view a list of all existing roles, send an HTTP GET request to the roles endpoint. By default, ACS returns a maximum count of 30 roles. To change the count, you can specify a count value up to a maximum of 100. A count value of 0 lists all roles. For example:

curl --location --request GET 'https://admin.splunk.com/{stack}/adminconfig/v2/roles?offset=0&count=3' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'

ACS returns a list of existing roles. Which roles you can see depends on the permissions granted to your assigned role. For example, if you are assigned the "user" role, you can only see your own role, hence ACS only returns one value for you.

For example:

{
    "roles": [
        {
            "cumulativeRTSrchJobsQuota": 400,
            "cumulativeSrchJobsQuota": 200,
            "defaultApp": "",
            "imported": {
                "capabilities": [
                    "accelerate_search",
                    "acs_edit_maintenance_windows",
                    ...
                ],
                "rtSrchJobsQuota": 20,
                "srchDiskQuota": 500,
                "srchFilter": "",
                "srchIndexesAllowed": [
                    "*"
                ],
                "srchIndexesDefault": [
                    "main"
                ],
                "srchJobsQuota": 10,
                "srchTimeEarliest": -1,
                "srchTimeWin": -1,
                "roles": [
                    "power",
                    "tokens_auth",
                    "user"
                ]
            },
            "name": "sc_admin",
            "capabilities": [
                "accelerate_datamodel",
                "acs_conf",
                ...
            ],
            "rtSrchJobsQuota": 100,
            "srchDiskQuota": 10000,
            "srchFilter": "*",
            "srchIndexesAllowed": [
                "*",
                "_*"
            ],
            "srchIndexesDefault": [
                "main"
            ],
            "srchJobsQuota": 50,
            "srchTimeEarliest": -1,
            "srchTimeWin": 0
        }
    ]
}

For full descriptions of the fields returned for each role, see authorization/roles in the REST API Reference Manual.

Describe an individual role

To view details of an individual role, send an HTTP GET request to the roles/{name} endpoint, specifying the name of the role. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/roles/{name}?' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'

ACS returns the details for the individual role. For example:

{
   "cumulativeRTSrchJobsQuota": 400,
   "cumulativeSrchJobsQuota": 200,
   "defaultApp": "",
   "imported": {
       "capabilities": [
           "accelerate_search",
           "acs_edit_maintenance_windows",
           ...
       ],
       "rtSrchJobsQuota": 20,
       "srchDiskQuota": 500,
       "srchFilter": "",
       "srchIndexesAllowed": [
           "*"
       ],
       "srchIndexesDefault": [
           "main"
       ],
       "srchJobsQuota": 10,
       "srchTimeEarliest": -1,
       "srchTimeWin": -1,
       "roles": [
           "power",
           "tokens_auth",
           "user"
       ]
   },
   "name": "sc_admin",
   "capabilities": [
       "accelerate_datamodel",
       "acs_conf",
      ..
   ],
   "rtSrchJobsQuota": 100,
   "srchDiskQuota": 10000,
   "srchFilter": "*",
   "srchIndexesAllowed": [
       "*",
       "_*"
   ],
   "srchIndexesDefault": [
       "main"
   ],
   "srchJobsQuota": 50,
   "srchTimeEarliest": -1,
   "srchTimeWin": 0
}

Create a role

To create a new role, send an HTTP POST request to the roles endpoint. You must specify the name of the role in the request body. You can optionally specify additional parameter values. Any parameter that you do not specify is automatically set to its default value.

For srchJobsEarliest and srchTimeWin a value of -1 means unset, 0 means infinite. Any other value is the amount of time in seconds, for example, 300 would mean 300s.

For cumulativeRTSrchJobsQuota, cumulativeSrchJobsQuota, rtSrchJobsQuota, srchJobsQuota, and srchDiskQuota the value must be a non-negative number.

If imported_roles or capabilities contains the fsh_manage capability, you must specify the Federated_Search_Manage_Ack header set to a value of "Y". This header acknowledges that a role with the fsh_manage capability can send search results outside the compliant environment.

The following example shows default parameter values.

curl --X POST 'https://admin.splunk.com/{stack}/adminconfig/v2/roles' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...' \
--header 'Federated-Search-Manage-Ack: Y' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "my_role",
   "capabilities": [],
   "cumulativeRTSrchJobsQuota": 100,
   "cumulativeSrchJobsQuota": 50,
   "defaultApp": "",
   "importedRoles": [],
   "rtSrchJobsQuota": 6,
   "srchDiskQuota": 100,
   "srchFilter": "",
   "srchIndexesAllowed": [],
   "srchIndexesDefault": [],
   "srchJobsQuota": 3,
   "srchTimeEarliest": 0,
   "srchTimeWin": -1
}

The response shows details of the newly created role. For example:

{
   "cumulativeRTSrchJobsQuota": 400,
   "cumulativeSrchJobsQuota": 200,
   "defaultApp": "",
   "imported": {
       "capabilities": [
           "accelerate_search",
           "acs_edit_maintenance_windows",
           ...
       ],
       "rtSrchJobsQuota": 20,
       "srchDiskQuota": 500,
       "srchFilter": "",
       "srchIndexesAllowed": [
           "*"
       ],
       "srchIndexesDefault": [
           "main"
       ],
       "srchJobsQuota": 10,
       "srchTimeEarliest": -1,
       "srchTimeWin": -1,
       "roles": [
           "power",
           "tokens_auth",
           "user"
       ]
   },
   "name": "sc_admin",
   "capabilities": [
       "accelerate_datamodel",
       "acs_conf",
      ..
   ],
   "rtSrchJobsQuota": 100,
   "srchDiskQuota": 10000,
   "srchFilter": "*",
   "srchIndexesAllowed": [
       "*",
       "_*"
   ],
   "srchIndexesDefault": [
       "main"
   ],
   "srchJobsQuota": 50,
   "srchTimeEarliest": -1,
   "srchTimeWin": 0
}

By default ACS creates the new role on your deployment's first regular search head or search head cluster only. If you want to add the role to a premium search head or additional regular search head, you must explicitly target the search head by including the search head prefix in the request URL. For example, the following shows the request URL for a premium search head with the prefix "sh-i-0910d0dfdb9ed913a":

curl -X POST 'https://admin.splunk.com/sh-i-0910d0dfdb9ed913a.{stack}/adminconfig/v2/roles'

When targeting a search head, you must provide an authentication token created on the target search head.

For more information on targeting search heads, see Target a specific search head for ACS operations.

Update a role

To update a role, send an HTTP PATCH request to the roles/{name} endpoint, specifying the name of the role. When updating a role, you must specify at least one parameter in the request body, or ACS will return a 400 error.

For parameters that accept a list of values, such as capabilities, you must include any existing values that you want to keep, as the request will overwrite the original values.

If imported_roles or capabilities contains the fsh_manage capability, you must specify the Federated_Search_Manage_Ack header set to a value of "Y".

curl --location --request PATCH 'https://admin.splunk.com/{stack}/adminconfig/v2/roles/{name}' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...' \
--header 'Federated-Search-Manage-Ack: Y' \
--header 'Content-Type: application/json' \
--data-raw '{
   "capabilities": [fsh_manage],
   "cumulativeRTSrchJobsQuota": 100,
   "cumulativeSrchJobsQuota": 50,
   "defaultApp": "",
   "importedRoles": [],
   "rtSrchJobsQuota": 6,
   "srchDiskQuota": 100,
   "srchFilter": "",
   "srchIndexesAllowed": [],
   "srchIndexesDefault": [],
   "srchJobsQuota": 3,
   "srchTimeEarliest": 0,
   "srchTimeWin": -1
}'

Delete a role

To delete a role, send an HTTP DELETE request to the roles/{name} endpoint, specifying the name of the role. For example:

curl --location --request DELETE 'https://admin.splunk.com/{stack}/adminconfig/v2/roles/{name}?' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'

ACS does not support editing or deleting default roles, including admin, sc_admin, power, user, and can_delete.

View existing users

To view a list of existing users, send an HTTP GET request to the users endpoint. By default, ACS returns a maximum count of 30 roles. To change the count, you can specify a count value up to a maximum of 100. A count value of 0 lists all roles. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/users?offset=0&count=3' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'

ACS returns a list of existing users. Which users you can see depends on the permissions granted to your assigned role. For example, if you are assigned the "user" role, you can only see your own role, hence ACS only returns one value for you.

{
   "users": [
       {
           "capabilities": [
               "accelerate_datamodel",
               "accelerate_search",
              ...
           ],
           "defaultApp": "launcher",
           "defaultAppSource": "system",
           "email": "",
           "fullName": "",
           "lastSuccessfulLogin": "2023-03-15T23:42:39Z",
           "lockedOut": false,
           "name": "kezia",
           "roles": [
               "sc_admin"
           ]
       }
   ]
}

For full descriptions of the fields returned for each user, see authentication/users in the REST API Reference Manual.

Describe an individual user

To describe an individual user, send an HTTP GET request to the users/{name} endpoint, specifying the user name. For example:

curl 'https://admin.splunk.com/{stack}/adminconfig/v2/users/{name}' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'

The response shows information about the individual user. For example:

{
   "users": [
       {
           "capabilities": [
               "accelerate_datamodel",
               "accelerate_search",
              ...
           ],
           "defaultApp": "launcher",
           "defaultAppSource": "system",
           "email": "",
           "fullName": "",
           "lastSuccessfulLogin": "2023-03-15T23:42:39Z",
           "lockedOut": false,
           "name": "kezia",
           "roles": [
               "sc_admin"
           ]
       }
   ]
}

Create a user

To create a new user, send an HTTP POST request to the users endpoint. You must specify user name and password in the request body.

To force a change of password on the user's first login, set forceChangePass to "true" in the request body. forceChangePass defaults to "true".

To create a new role for the user, set createRole to "true" in the request body. If set to "true", ACS creates a new role user-<name> and assigns it to the user. The new role will have all default field values assigned to a new role.

If createRole is set to "false", you must specify at least one existing role using the roles parameter in the request body. createRole defaults to "false".

If any role contains the fsh_manage capability you must specify the Federated_Search_Manage_Ack header set to a value of "Y". This header acknowledges that a role with the fsh_manage capability can send search results outside the compliant environment.

For example:

curl -X POST 'https://admin.splunk.com/{stack}/adminconfig/v2/users' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'
--header 'Federated-Search-Manage-Ack: Y' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "test-user",
   "password": "mock-password",
   "createRole": true,
   "defaultApp": "launcher",
   "email": "mock-email@splunk.com",
   "forceChangePass": true,
   "fullName": "User full name",
   "roles": []
}'

The response shows information about the newly created user. For example:

{
   "users": [
       {
           "capabilities": [
               "accelerate_datamodel",
               "accelerate_search",
              ...
           ],
           "defaultApp": "launcher",
           "defaultAppSource": "system",
           "email": "",
           "fullName": "",
           "lastSuccessfulLogin": "2023-03-15T23:42:39Z",
           "lockedOut": false,
           "name": "kezia",
           "roles": [
               "sc_admin"
           ]
       }
   ]
}

By default ACS creates the new user on your deployment's first regular search head or search head cluster only. If you want to add the user to a premium search head or additional regular search head, you must explicitly target the search head by including the search head prefix in the request URL. For example, the following shows the request URL for a premium search head with the prefix "sh-i-0910d0dfdb9ed913a":

curl -X POST 'https://admin.splunk.com/sh-i-0910d0dfdb9ed913a.{stack}/adminconfig/v2/users'

When targeting a search head, you must provide an authentication token created on the target search head.

For more information on targeting search heads, see Target a specific search head for ACS operations.

Do not log in to your deployment as a user that is assigned to a role with no capabilities. This can cause you to become locked out of the system.

Update a user

To update a user, send an HTTP PATCH request to the users/{user-name} endpoint, specifiying the name of the user. You must edit at least one parameter in the request body, or ACS will return a 400 error.

To update a password, you must specify the both the new password using the password parameter and the old password using the oldPassword parameter.

When updating a password, if the user was originally created or updated with forceChangePass set to "true", you must explicitly set forceChangePass to "false" in the request body, to avoid subsequent password change requirements.

For parameters that accept a list of values, such as roles, you must include any existing values that you want to keep, as the request will overwrite the original values.

If any role contains the fsh_manage capability you must specify the Federated_Search_Manage_Ack header set to a value of "Y".

Delete a user

To delete a user, send an HTTP DELETE request to the users/{user-name} endpoint, specifying the name of the user.

curl -X DELETE 'https://admin.splunk.com/{stack}/adminconfig/v2/users/{user-name}' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu...'

ACS does not support deleting or updating these default system users: admin, index-manager, cmon_user, internal_monitoring, and app-installer.

ACS does not support deleting SAML users. You can configure your deployment for automated deletion of SAML users using the SCIM protocol. For more information, see Configure the Splunk platform to remove users on Okta.