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

On Splunk Enterprise, you can create and manage roles by editing the authorize.conf configuration file. This option is not available in Splunk Cloud, 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 platform 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

• authorize.conf
• About configuration files in the Admin Manual.

Distributed search configurations have slightly different authorization needs. When you use search head clustering, you must make sure 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

The general procedure for creating a role to your Splunk Enterprise instance is as follows:

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 roles stanzas comply with stanza syntax requirements. Failure to do this can result in the platform not creating your roles.
4. Save the authorize.conf file and close it.
5. Use either 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 the 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:

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

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:

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

Example of creating a role in the authorize.conf file

The following example creates the "ninja" role, 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:

• The search filter limits ninja to searching on host=foo.
• ninja can search all public indexes, that do not start with _, and will search the indexes mail and main 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 500MB 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 boot current users from 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 CLI command ./splunk reload auth:

./splunk reload auth

The authentication system cache resets immediately.