How to work with users, roles, and secret storage using the Splunk Enterprise SDK for Python

With the Splunk SDKs, you can manage who can access your Splunk Enterprise system and control what they can do by setting up users and assigning them roles. You can also manage secure credentials, or secret storage.

 Users, roles, and secret storage

This section provides a brief overview of users, roles, and secret storage in Splunk Enterprise.

 Users

Splunk has a single default user ("admin"), and if you are running Splunk Enterprise, you can add more users (Splunk Free doesn't support user authentication). For each new user you add to your Splunk Enterprise system, you can specify:

• A username and password
• A full name
• An email address
• A default time zone
• A default app
• One or more roles to control what the user can do

 Roles

Roles specify what the user is allowed to do in Splunk Enterprise. Splunk Enterprise includes predefined roles that you can modify, or you can create new roles. The predefined roles are:

• admin: This role has the most capabilities.
• power: This role can edit all shared objects and alerts, tag events, and other similar tasks.
• user: This role can create and edit its own saved searches, run searches, edit preferences, create and edit event types, and other similar tasks.
• can_delete: This role has the single capability of deleting by keyword, which is required for using the delete search operator.
• splunk-system-role: This role is based on admin, but has more restrictions on searches and jobs.

Each role is defined by a combination of these permissions and restrictions:

• Capabilities, which specify the system settings and resources the user is allowed to view or modify. For example, you could allow users to list data inputs but not edit them. For a full list of capabilities, see "Capabilities", below.
• Restrictions on searches and search jobs. For example, you can set a limit on the number of concurrent search jobs the user can run, or restrict the data that the user can search by setting a search filter.
• Allowed indexes, to explicitly specify which indexes the user is allowed to search.
• Indexes to search by default.
• Other roles to inherit properties from.

When you inherit other roles, their capabilities, restrictions, and properties are not merged with those of the current role, but rather they are maintained separately. For example, if you list capabilities of a role, its inherited capabilities are not listed—you must explicitly request a list of inherited capabilities. When a role is modified, the changes are made automatically where ever the role is inherited.

You can also assign one or more roles to each user. When multiple roles are assigned, the broadest permissions from these roles are given. Specifically, the user's permissions are the union of all capabilities and the intersection of the restrictions.

 Secret storage

Secret storage in Splunk Enterprise allows for the management of secure credentials. When you store a secret in a Splunk app, the platform encrypts the password with a secret key that resides on the same machine. You can manage access to this service based on a user's capabilities. For example, users require the list_storage_passwords capability to read plain text secrets and the admin_all_objects capability to create, update, and delete secrets.

 The user, role, and secret storage APIs

To work with users, roles, and secret storage in the Splunk Enterprise SDK for Python, use these classes through an instance of the splunklib.client.Service class:

• The splunklib.client.User class for an individual user.
• The splunklib.client.Users class for the collection of users.
• The splunklib.client.Role class for an individual role.
• The splunklib.client.Roles class for the collection of roles.
• The splunklib.client.StoragePassword class for an individual secret.
• The splunklib.client.StoragePasswords class for the collection of secrets.

Retrieve a collection, and from there you can access individual items in the collection and create new ones. For example, here's a simplified program for getting a collection of users and creating a new one:

# Connect to Splunk
service = client.connect(...)

# Get the collection of users
users = service.users

# Create a user
user = service.users.create(username, password, roles)

 Code examples

This section provides examples of how to use the users, roles, and secret storage APIs, assuming you first connect to a Splunk instance.

 To list users and display properties

This example shows how to use the splunklib.client.Users class to retrieve the collection of users that have been added to your Splunk system and list them, sorted by the realname field. This example also retrieves a few properties for each user, including their roles. For a list of available parameters to use when retrieving a collection, see "Collection parameters".

# Get the collection of users, sorted by realname
kwargs = {"sort_key":"realname", "sort_dir":"asc"}
users = service.users.list(count=-1,**kwargs)

# Print the users' real names, usernames, and roles
print "Users:"
for user in users:
    print "%s (%s)" % (user.realname, user.name)
    for role in user.role_entities:
        print " - ", role.name

 To add a new user and modify properties

This example shows how to create a new user. At a minimum, provide a username and password, and specify one or more roles. You can also specify additional properties for the user at the same time by providing a dictionary of key-value pairs for the properties. Or, modify properties after you have created the user.

Note that when you set properties, the new values overwrite any existing ones. For example, if you set a role, it replaces any existing roles already assigned to the user.

# Create a new user
newuser = service.users.create(username="testuser",
                            password="yourpassword",
                            roles=["power","user"])
# Print the user's properties
print "Properties of the new user '" + newuser.name + "':\n"
print "Full name:  ", newuser["realname"]
print "Default app:", newuser["defaultApp"]
...
Show More

 To get the current user

This example shows how to find out which user is currently logged in.

# Get the current user
print "The current user is", service.username

 To list roles and display properties

This example shows how to use the splunklib.client.Roles class to retrieve the collection of roles that have been configured for Splunk and list them along with their capabilities. For a list of available parameters to use when retrieving a collection, see "Collection parameters".

# Get the collection of roles
roles = service.roles
print "There are %s roles" % (len(roles))

# Display the name of each role and its capabilities
for role in roles:
    print role.name
    for capability in role.capabilities:
        print " - ", capability
    for capability in role.imported_capabilities:
        print " - ", capability, "(imported)"

 To create a new role and modify properties

This example shows how to create a new role, then how to import capabilities and properties from existing roles. At a minimum, provide a name for the new role. You can specify additional properties at the same time by providing a dictionary of key-value pairs. Or, modify properties after you have created the role.

Be aware that when you set properties using a dictionary of kwargs, the new values overwrite the existing ones. However, you can use the splunklib.client.Role.grant method to add capabilities to an existing set rather than replace them. Similarly, use the splunklib.client.Role.revoke method to remove capabilities from the current set, leaving the rest of the set intact.

# Create a new role called "testrole"
newrole = service.roles.create("testrole")
# Import properties from the 'user' role and update the server
kwargs = {"imported_roles": "user"}
newrole.update(**kwargs).refresh()
# Display the properties of the new role
...
Show More

 To create a new secret

This example shows how to create a new secret.

service = client.connect(...)

# Create a secret 
secret = service.storage_passwords.create("your_password", "some_username", "some_realm")
print("Created secret with name: {}".format(secret.name))

 To list secrets

This example shows how to list the secrets visible to the current user.

service = client.connect(...)
secrets = service.storage_passwords
 
# List secrets
for secret in secrets.list():
    print(secret.name)

 Parameters

Here are the available parameters for working with users, roles, and passwords.

 Capabilities

For a list of capabilities you can allow in a role, see Table of Splunk platform capabilities in the Splunk Enterprise Securing the Splunk Platform manual.

 Collection parameters

By default, all entries are returned when you retrieve a collection. But by using the parameters below, you can also specify the number of entities to return and how to sort them. These parameters are available whenever you retrieve a collection.

 User authentication parameters

The parameters you can use for user authentication correspond to the parameters for the authentication/* endpoints in the Splunk Enterprise REST API Reference Manual.

 Roles parameters

The parameters you can use for working with roles correspond to the parameters for the authorization/* endpoints in the Splunk Enterprise REST API Reference Manual.