Create and manage roles in Splunk Enterprise using the authorize.conf configuration file

You can create and manage roles in Splunk Enterprise by by editing the authorize.conf configuration file. Because this option is not available in Splunk Cloud Platform, you can instead use Splunk Web to create and manage roles.

Users hold roles that determine their level of access and the tasks that they can perform. For more information about roles and capabilities, see About role-based user access.

When you make changes to the authorize.conf file to edit roles, you must reload authentication or restart Splunk Enterprise for those changes to take effect. If you do not restart or reload, the roles you added do not appear in the Roles list in Splunk Web. See Refresh the authentication scheme in this topic for instructions to refresh authentication without restarting the Splunk platform.

Never edit or delete roles in the default location of $SPLUNK_HOME/etc/system/default/authorize.conf. Making edits to this file can cause problems with administrator capabilities on the instance. Instead, make role edits in the local version at $SPLUNK_HOME/etc/system/local/authorize.conf, or in your own custom application directory in $SPLUNK_HOME/etc/apps/.

For more information about editing configuration files like authorize.conf, see the authorize.conf. specification file and About configuration files in the Splunk Enterprise Admin Manual.

Distributed search configurations have slightly different authorization needs. When you use search head clustering, you must confirm that the search heads and the search peers all use the same set of authorize.conf files. To confirm that your authorization is properly set up for search pooling, see How authorization works in distributed searches.

Create and manage roles

To create a role for your Splunk Enterprise instance, follow these steps:

1. Use a text editor to edit $SPLUNK_HOME\etc\system\local\authorize.conf.
2. Add role stanzas and settings to the file, based on the roles that you want to add to the instance.
3. Confirm that your role stanzas comply with stanza syntax requirements. If you don't do this, your roles may not be created. See Configuration file structure in the Splunk Enterprise Admin Manual.
4. Save the authorize.conf file and close it.
5. Use Splunk Web or the CLI to either restart Splunk Enterprise or reload authentication.

Role creation syntax for the authorize.conf file

The syntax for adding roles using the authorize.conf file is as follows:

[role_<roleName>]
<setting> = <value>
<setting> = <value>
...

• The <roleName> in the stanza header is the name you want to give your role.
• You must include role_ in the stanza name.
• Role names must use lowercase characters only.
• Role names cannot contain spaces, colons, semicolons, or forward slashes.

See the following examples:

Role name	Role stanza name
security	role_security
compliance	role_compliance
ninja	role_ninja

Manage an existing role

Managing a role means editing the authorize.conf file and making the changes that you want to the roles that are in the file. The same syntax rules apply for modifying roles as they do for creating them. The Splunk platform does not see any changes until you save the file and either reload the authentication system or restart the platform.

You can include or change the following settings in the stanza for your role:

Setting	Definition	Default	For more information
<capability> = enabled	You can add any number of capabilities to a role. To add a capability to a role, set that capability to enabled. Do not set a capability to disabled explicitly. This has no effect. The capability is only on if its value is equal to enabled.	disabled	See About defining roles with capabilities.
fieldFilter-<fieldname> = <option>	Configures role-based field filtering on roles. Field filtering affects the results of searches run by users that have the role. The field filter can remove specific indexed or default fields from the results, or it can replace values of specific indexed or default fields when those fields appear in the results.	Not set	See Protecting PII and PHI data with role-based field filtering.
fieldFilterLimit = [sourcetype::<sourcetype>::<host>::<source>]	Limits the role-based field filters that are specified for a role to events with a specific host, source, or source type.	Not set	See Limiting role-based field filters to specific hosts, sources, indexes, and source types.
importRoles = <semicolon-separated list>	When this setting has a value, the role that you are defining inherits the capabilities from each role you specify in the value. Members assigned to multiple roles inherit properties from the role with the broadest permissions. If you enter multiple roles, separate them with semicolons.	No roles set.	See How role inheritance works.
srchFilter = <string>	This setting lets you define detailed data access controls. Users with this role have their searches filtered by this expression.	No filters are set.	See Search filter format.
srchTimeEarliest = <integer>	The earliest time, in seconds, from which Splunk Enterprise can return results for a search, from the current time.	Not set. There is no limit to when Splunk Enterprise can return search results.
srchTimeWin = <integer>	The maximum time window, in seconds, that a search run by a user with this role can use.	Not set. There is no limit to the range of search time.
srchDiskQuota = <integer>	The maximum amount of disk space, in megabytes, that search jobs performed by a user with this role can take.	100
cumulativeSrchJobsQuota = <integer>	The maximum number of concurrently running historical searches that all members of this role can have. For this setting to apply, you must also set enable_cumulative_quota = true in the limits.conf file. When a user belongs to multiple roles, the user uses searches from the roles with the largest cumulative search quota first. When the quota for that role is completely used up, roles with lower quotas are used.	Not set.
cumulativeRTSrchJobsQuota = <integer>	The maximum number of concurrently running real-time searches that all members of this role can have. For this setting to apply, you must also set enable_cumulative_quota = true in the limits.conf file. If the user belongs to multiple roles, the user uses searches from the roles with the largest cumulative search quota first. When the quota for that role is completely used up, roles with lower quotas are used.	Not set.
srchJobsQuota = <integer>	The maximum number of concurrently running searches that a user with this role can have.	3
rtSrchJobsQuota = <integer>	The maximum number of concurrently running real-time searches that a user with this role can have.	6
srchIndexesDefault = <string>	A semicolon-delimited list of default indexes to search when the user does not specify an index in the search. The list can include both event indexes and metrics indexes. When the user runs an event search that does not specify an index, the search runs over the default event indexes. When the user runs a metrics search that does not specify an index, the search runs over the default metrics indexes. You can use wildcards in your entries. However, the wildcard character ( * ) does not match internal indexes, which all begin with an underscore ( _ ). To match internal indexes, begin with an underscore and a wildcard character ( _* ).	Not set.
srchIndexesAllowed = <string>	A semicolon-delimited list of indexes that this role can search. The list can include both event and metrics indexes. You can use wildcards in your entries. However the wildcard character ( * ) does not match internal indexes, which all begin with an underscore ( _ ). All internal indexes are represented an underscore and a wildcard character ( _* ).	Not set.
srchIndexesDisallowed = <string>	A semicolon-delimited list of indexes that this role doesn't have permission to search or delete. The list can include both event and metrics indexes. You can use wildcards in your entries. However, the wildcard character ( * ) does not match internal indexes, which all begin with an underscore ( _ ). To match internal indexes, begin with an underscore and a wildcard character ( _* ). This setting takes precedence over srchIndexesDefault, srchIndexesAllowed, and deleteIndexesAllowed. If you specify indexes in this setting and in srchIndexesDefault, srchIndexesAllowed, and deleteIndexesAllowed, users are unable to search on or delete those indexes. Splunk Web index settings overwrite the configuration of the srchIndexesDisallowed setting. That means that if you make any changes in the Indexes settings panel for a role in Splunk Web, the values specified in Splunk Web take precedence over the srchIndexesDisallowed setting. Also, any wildcards you specify in srchIndexesDisallowed are lost.	Not set.
deleteIndexesAllowed = <string>	A semicolon-delimited list of indexes that this role is allowed to delete. This setting must be used in conjunction with the delete_by_keyword capability. You can use wildcards in your entries. However, the wildcard character ( * ) does not match internal indexes, which all begin with an underscore ( _ ). To match internal indexes, begin with an underscore and a wildcard character ( _* ).	Not set.

Search filter format

The srchFilter field can include any of the following search terms:

• source=
• host= and host tags
• index= and index names
• eventtype= and event type tags
• sourcetype=
• search fields
• wildcards
• use OR to use multiple terms, or AND to make searches more restrictive.

The search terms cannot include the following items:

• saved searches
• time operators
• regular expressions
• any fields or modifiers Splunk Web can overwrite

Example of creating a role in the authorize.conf file

For example, say we create a role called ninja, which inherits capabilities from the default user role. The ninja role has almost the same capabilities as the default power role, except it cannot schedule searches. In addition, we set up our example as follows:

• The search filter limits ninja to searching on host=foo.
• ninja can search all public indexes, that do not start with an underscore, and searches the mail and main indexes if a user with the ninja role does not specify an index in the search.
• ninja can run up to 8 search jobs and 8 real-time search jobs concurrently.
• ninja can take up to 500 MB total space on disk for all its jobs.

[role_ninja]
rtsearch = enabled
importRoles = user
srchFilter = host=foo
srchIndexesAllowed = *
srchIndexesDefault = mail;main
srchJobsQuota   = 8
rtSrchJobsQuota = 8
srchDiskQuota   = 500

Refresh the authentication scheme

After you make changes to the authorize.conf file, you must refresh the authentication system to have the changes take effect.

You can do this with either Splunk Web or the CLI. Refreshing the authentication scheme doesn't log users off of the instance.

A restart of the Splunk platform reloads authentication, but it also logs users off of the system. You do not need to restart the platform to refresh authentication.

Refresh the authentication system using Splunk Web

1. From the system bar, click Settings > Access controls > Authentication method.
2. Click Reload authentication configuration. This refreshes the authentication caches but does not log current users off of the system.

Refresh the authentication system using the CLI

1. On the Splunk platform instance where you want to reload authentication, open a shell prompt or PowerShell window.
2. Switch to the $SPLUNK_HOME/bin directory.
3. Use the ./splunk reload auth CLI command. The authentication system cache resets immediately.