Splunk® Enterprise

REST API Reference Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Access endpoint descriptions

Access and manage user credentials.

Review ACL information for an endpoint

To check Access Control List (ACL) properties for an endpoint, append /acl to the path. For more information see Access Control List in the REST API User Manual.

Authentication and Authorization

Username and password authentication is required for most endpoints and REST operations. Additional capability or role-based authorization may also be required, particularly for POST or DELETE operations.


LDAP REST API usage details

Splunk Enterprise users can configure LDAP user authentication using the REST API. If you are using Splunk Cloud, contact Support for assistance with setting up LDAP authentication.

LDAP user authentication lets you specify configurations, user groups, and group to role mappings to manage permissions in your Splunk deployment.

You can use the LDAP REST API for the following LDAP management tasks.

  • Configure an LDAP strategy for a server in your deployment.
  • Map LDAP groups to user roles in a server to manage group permissions.
  • Enable or disable an LDAP strategy.

To learn more about using LDAP authentication, see Set up user authentication with LDAP in Securing Splunk Enterprise.

admin/LDAP-groups

https://<host>:<mPort>/services/admin/LDAP-groups

Access and update LDAP group to role mappings.

Authentication and authorization
Requires the change_authentication capability for access.


GET

Access LDAP group mappings.

Request parameters

If you are passing in a strategy name with an LDAP group name, they must be comma separated.

Name Description
strategy LDAP strategy name
LDAPgroup LDAP group name

Returned values
For each group, the following values are returned in the response.

Name Description
roles Roles mapped to this group
strategy Strategy name
type Group type
users List of users in this group


Example request and response

curl -u admin:changeme -X GET -k https://localhost:8089/services/admin/LDAP-groups/

...
  <title>LDAP-groups</title>
  <id>https://localhost:8089/services/admin/LDAP-groups</id>
  <updated>2016-11-10T13:04:02-08:00</updated>
  <generator build="2469654e091cb630e237a02094e683ced50f2fe5" version="20161031"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/admin/LDAP-groups/_acl" rel="_acl"/>
  <opensearch:totalResults>20</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>Abc123-Admin</title>
    <id>https://localhost:8089/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin</id>
    <updated>2016-11-10T13:04:02-08:00</updated>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="list"/>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="roles">
          <s:list/>
        </s:key>
        <s:key name="strategy">ActiveDirectory_New</s:key>
        <s:key name="type">static</s:key>
        <s:key name="users">
          <s:list>
            <s:item>CN=Abc123 CI,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
            <s:item>CN=Test 1 User,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
            <s:item>CN=Test 2. User,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
          </s:list>
        </s:key>
      </s:dict>
    </content>
  </entry>

POST

Create an LDAP group.


Request parameters
Append the group name to the LDAP-groups/ endpoint. Pass in a strategy name using comma separation. For example, this POST creates the ActiveDirectory_New strategy and specifies the Abc123 group name. 

  curl -k -u admin:password -X POST
  https://localhost:8089/services/admin/LDAP-groups/ActiveDirectory_New,Abc123-Admin -d roles=user
Name Description
strategy Required. LDAP strategy name
LDAPgroup Required. LDAP group name


Returned values

Name Description
roles Roles mapped to this group.
strategy Strategy name
type Group type
users List of users in this group.


Example request and response


curl -k -u admin:password -X POST https://localhost:8089/services/admin/LDAP-groups/ActiveDirectory_New,Abc123-Admin -d roles=user


.
.
.
    <title>Abc123-Admin</title>
    <id>https://localhost:8089/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin</id>
    <updated>2016-11-10T13:07:28-08:00</updated>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="list"/>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="roles">
          <s:list>
            <s:item>user</s:item>
          </s:list>
        </s:key>
        <s:key name="strategy">ActiveDirectory_New</s:key>
        <s:key name="type">static</s:key>
        <s:key name="users">
          <s:list>
            <s:item>CN=Abc123 CI,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
            <s:item>CN=Test 1 User,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
            <s:item>CN=Test 2. User,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
          </s:list>
        </s:key>
      </s:dict>
    </content>
  </entry>
.
.
.


authentication/LDAP-auth

https://<host>:<mPort>/services/authentication/LDAP-auth

Access or create LDAP authentication strategies on a server in your deployment.

Authentication and authorization
Requires the change_auth capability for access.

GET

Access LDAP configurations strategies.

Request parameters

Name Description
strategy Name of LDAP configuration strategy

Returned values
The response lists LDAP strategy settings.

See LDAP settings in authentication.conf for strategy settings information.

Example request and response

curl -k -u admin:password https://localhost:8089/services/authentication/LDAP-auth/

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>LDAP-auth</title>
  <id>https://localhost:8089/services/authentication/LDAP-auth</id>
  <updated>2016-11-09T16:14:07-08:00</updated>
  <generator build="2469654e091cb630e237a02094e683ced50f2fe5" version="20161031"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/LDAP-auth/_new" rel="create"/>
  <link href="/services/authentication/LDAP-auth/_acl" rel="_acl"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>my_strategy</title>
    <id>https://localhost:8089/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy</id>
    <updated>2016-11-09T16:14:07-08:00</updated>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="list"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="edit"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="remove"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SSLEnabled">0</s:key>
        <s:key name="anonymous_referrals">1</s:key>
        <s:key name="bindDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="bindDNpassword">********</s:key>
        <s:key name="charset">utf8</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="emailAttribute">mail</s:key>
        <s:key name="groupBaseDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="groupMappingAttribute">dn</s:key>
        <s:key name="groupMemberAttribute">sn</s:key>
        <s:key name="groupNameAttribute">sn</s:key>
        <s:key name="host">1.1.1.1</s:key>
        <s:key name="nestedGroups">0</s:key>
        <s:key name="network_timeout">20</s:key>
        <s:key name="order">1</s:key>
        <s:key name="port">389</s:key>
        <s:key name="realNameAttribute">sn</s:key>
        <s:key name="sizelimit">1000</s:key>
        <s:key name="timelimit">15</s:key>
        <s:key name="userBaseDN">OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="userNameAttribute">sn</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST

Create an LDAP strategy.

Usage details
Use the following endpoints to enable or disable an LDAP strategy after you create it.

  • services/authentication/LDAP-auth/{LDAP_strategy_name}/enable
  • services/authentication/LDAP-auth/{LDAP_strategy_name}/disable

Request parameters
See LDAP settings in authentication.conf for required and optional settings information.

Returned values
None.

Example request and response

curl —k u admin:password -X POST https://localhost:8089/services/authentication/LDAP-auth/ -d name=my_strategy -d groupBaseDN="CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com" -d groupMemberAttribute=sn -d groupNameAttribute=sn -d host=1.1.1.1 -d realNameAttribute=sn -d userBaseDN="OU=SAML Test,DC=qa,DC=ab2008e2,DC=com" -d userNameAttribute=sn -d bindDN="CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com" -d bindDNpassword=password


<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>LDAP-auth</title>
  <id>https://localhost:8089/services/authentication/LDAP-auth</id>
  <updated>2016-11-09T16:20:14-08:00</updated>
  <generator build="2469654e091cb630e237a02094e683ced50f2fe5" version="20161031"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/LDAP-auth/_new" rel="create"/>
  <link href="/services/authentication/LDAP-auth/_acl" rel="_acl"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages>
    <s:msg type="INFO">Successfully performed a bind to the LDAP server</s:msg>
    <s:msg type="WARN">Failed to find the email attribute 'mail' in a returned user entry.</s:msg>
  </s:messages>
  <entry>
    <title>my_strategy</title>
    <id>https://localhost:8089/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy</id>
    <updated>2016-11-09T16:20:14-08:00</updated>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="list"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="edit"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="remove"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SSLEnabled">0</s:key>
        <s:key name="anonymous_referrals">1</s:key>
        <s:key name="bindDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="bindDNpassword">********</s:key>
        <s:key name="charset">utf8</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="emailAttribute">mail</s:key>
        <s:key name="groupBaseDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="groupMappingAttribute">dn</s:key>
        <s:key name="groupMemberAttribute">sn</s:key>
        <s:key name="groupNameAttribute">sn</s:key>
        <s:key name="host">1.1.1.1</s:key>
        <s:key name="nestedGroups">0</s:key>
        <s:key name="network_timeout">20</s:key>
        <s:key name="order">1</s:key>
        <s:key name="port">389</s:key>
        <s:key name="realNameAttribute">sn</s:key>
        <s:key name="sizelimit">1000</s:key>
        <s:key name="timelimit">15</s:key>
        <s:key name="userBaseDN">OU=SAML Test,DC=qa,DC=ab2008e2,DC=com</s:key>
        <s:key name="userNameAttribute">sn</s:key>
      </s:dict>
    </content>
  </entry>
</feed>


authentication/LDAP-auth/{LDAP_strategy_name}

https://<host>:<mPort>/services/authentication/LDAP-auth/{LDAP_strategy_name}

Access, update, or delete the {LDAP_strategy_name} strategy.

Authentication and authorization
Requires the change_auth capability for access.

GET

Access an existing LDAP strategy.

Usage details
Use the following endpoints to enable or disable the {LDAP_strategy_name} strategy.

  • services/authentication/LDAP-auth/my_strategy/enable
  • services/authentication/LDAP-auth/my_strategy/disable


Request parameters
None.

Returned values
See LDAP settings in authentication.conf for strategy settings information.

Example request and response

curl —k u admin:password https://localhost:8089/services/authentication/LDAP-auth/my_strategy

.
.
.
  <entry>
    <title>my_strategy</title>
    <id>https://localhost:8089/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy</id>
    <updated>2016-11-09T16:14:07-08:00</updated>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="list"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="edit"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="remove"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SSLEnabled">0</s:key>
        <s:key name="anonymous_referrals">1</s:key>
        <s:key name="bindDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="bindDNpassword">********</s:key>
        <s:key name="charset">utf8</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="emailAttribute">mail</s:key>
        <s:key name="groupBaseDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="groupMappingAttribute">dn</s:key>
        <s:key name="groupMemberAttribute">sn</s:key>
        <s:key name="groupNameAttribute">sn</s:key>
        <s:key name="host">1.1.1.1</s:key>
        <s:key name="nestedGroups">0</s:key>
        <s:key name="network_timeout">20</s:key>
        <s:key name="order">1</s:key>
        <s:key name="port">389</s:key>
        <s:key name="realNameAttribute">sn</s:key>
        <s:key name="sizelimit">1000</s:key>
        <s:key name="timelimit">15</s:key>
        <s:key name="userBaseDN">OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="userNameAttribute">sn</s:key>
      </s:dict>
    </content>
  </entry>
.
.
.

POST

Update an existing LDAP strategy.

Request parameters and returned values
See LDAP settings in authentication.conf for strategy settings information.

Example request and response

curl —k u admin:password -X POST https://localhost:8089/services/authentication/LDAP-auth/my_strategy -d port=390

  <entry>
    <title>my_strategy</title>
    <id>https://localhost:8089/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy</id>
    <updated>2016-11-09T16:14:07-08:00</updated>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="list"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="edit"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="remove"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SSLEnabled">0</s:key>
        <s:key name="anonymous_referrals">1</s:key>
        <s:key name="bindDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="bindDNpassword">********</s:key>
        <s:key name="charset">utf8</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="emailAttribute">mail</s:key>
        <s:key name="groupBaseDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="groupMappingAttribute">dn</s:key>
        <s:key name="groupMemberAttribute">sn</s:key>
        <s:key name="groupNameAttribute">sn</s:key>
        <s:key name="host">1.1.1.1</s:key>
        <s:key name="nestedGroups">0</s:key>
        <s:key name="network_timeout">20</s:key>
        <s:key name="order">1</s:key>
        <s:key name="port">390</s:key>
        <s:key name="realNameAttribute">sn</s:key>
        <s:key name="sizelimit">1000</s:key>
        <s:key name="timelimit">15</s:key>
        <s:key name="userBaseDN">OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="userNameAttribute">sn</s:key>
      </s:dict>
    </content>
  </entry>
.
.
.

DELETE

Delete an existing LDAP strategy.

Request parameters
None

Returned values
None

Example request and response

curl -k -u admin:password -X DELETE https://localhost:8089/services/authentication/LDAP-auth/my_strategy

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>LDAP-auth</title>
  <id>https://ronnie:8132/services/authentication/LDAP-auth</id>
  <updated>2016-11-09T16:18:37-08:00</updated>
  <generator build="2469654e091cb630e237a02094e683ced50f2fe5" version="20161031"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/LDAP-auth/_new" rel="create"/>
  <link href="/services/authentication/LDAP-auth/_acl" rel="_acl"/>
  <opensearch:totalResults>0</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
</feed>


authentication/LDAP-auth/{LDAP_strategy_name}/enable

https://<host>:<mPort>/services/authentication/LDAP-auth/{LDAP_strategy_name}/enable


GET

Enable the {LDAP_strategy_name} LDAP strategy.

Request parameters
None

Returned values
None

Example request

curl —k u admin:password https://localhost:8089/services/authentication/LDAP-auth/my_strategy/enable

authentication/LDAP-auth/{LDAP_strategy_name}/disable

https://<host>:<mPort>/services/authentication/LDAP-auth/{LDAP_strategy_name}/disable


GET

Disable the {LDAP_strategy_name} LDAP strategy.

Request parameters
None

Returned values
None

Example request

curl —k u admin:password https://localhost:8089/services/authentication/LDAP-auth/my_strategy/disable

admin/SAML-groups

https://<host>:<mPort>/services/admin/SAML-groups

Description

Convert external groups in an IdP response to internal Splunk platform roles.

Authentication and authorization
Requires change_authentication capability for all operations.

Method summary

Method Description
GET Access internal roles for this external group.
POST Convert an external group to internal roles.

GET admin/SAML-groups

Example

Request parameters
None.

Response keys

Name Description
roles Corresponding internal role for the external group.

POST admin/SAML-groups

Example


Request parameters

Name Datatype Description
name String External group name.
roles String Equivalent internal role for the group.

Response keys
None.

admin/SAML-groups/{group_name}

https://<host>:<mPort>/services/admin/SAML-groups/{group_name}


Delete a particular SAML group.

Authentication and authorization
Requires change_authentication capability for all operations.

Method summary

Method Description
DELETE Remove an external group.

DELETE admin/SAML-groups/{group_name}

Example


Request parameters
None

Response keys
None.

admin/SAML-idp-metadata

https://<host>:<mPort>/services/admin/SAML-idp-metadata

Description

Access IdP SAML metadata attributes.

Authentication and authorization
Requires change_authentication capability for all operations.

Method summary

Method Description
GET Access SAML user and role information for saved searches.

GET admin/SAML-idp-metadata method detail

Example

Request parameters

Name Datatype Description
idpMetadataFile File path. See description. Full path of the metadata file location. File should be local to splunkd server.

Response keys

Name Description
idpMetadataPayload SAML IdP metadata in XML format.

admin/SAML-sp-metadata

https://<host>:<mPort>/services/admin/SAML-sp-metadata

Description

Access service provider SAML metadata attributes.

Authentication and authorization
Requires change_authentication capability for all operations.

GET admin/SAML-sp-metadata method detail

Example

Request parameters
None.

Response keys

Name Description
spMetadataPayload SAML service provider metadata in XML format.

auth/login

https://<host>:<mPort>/services/auth/login

Description

Get a session ID for use in subsequent API calls that require authentication. Set up cookie-based authorization.

Use cookie-based authorization

To use cookie-based authorization, first ensure that the allowCookieAuth setting is enabled in server.conf. By default, this setting is enabled in Splunk software versions 6.2 and later.

If allowCookieAuth is enabled, you can pass a cookie=1 parameter to the POST request on auth/login. As noted in the Response data keys section below, a Set-Cookie header is returned. This header must be used in subsequent requests.

Any request authenticated using a cookie may include a new Set-Cookie header in its response. Use this new cookie value in any subsequent requests.

If you do not receive a Set-Cookie header in response to the auth/login POST request but login succeeded, you can use the standard Authorization:Splunk... header with the session key for authorization.

See also

Method summary

Method Description Formats
POST Get a session ID for use in subsequent API calls that require authentication. Optionally, use cookie-based authentication. XML, JSON

POST auth/login method detail

Example

Request parameters
Name Datatype Default Description
cookie
optional 		Boolean, only used value is 1. To use cookie-based REST auth, pass in cookie=1. Cookies will only be returned if the cookie parameter is passed in with the value of 1.
password
required 		String Current username password.
username
required 		String Authenticated session owner name.
Response data keys
Name Description
sessionKey Session ID.

A Set-Cookie HTTP header is returned if cookie-based authentication is requested.

Note: Only a <response> element is returned, instead of the full <atom> feed.

Application usage

The splunkd server supports token-based authentication using the standard HTTP authorization header. Before you can access Splunk Enterprise resources, you must authenticate with the splunkd server using your username and password.

Failure to authenticate returns the following response: 

<response>
     <messages>
         <msg type="WARN">Login failed</msg>
     </messages>
</response>

Obtain a session ID to be used in the authorization header of subsequent REST API calls that require authentication.

[ Top ]

authentication/current-context

https://<host>:<mPort>/services/authentication/current-context


Description

Get the the authenticated session owner username.

See also

Method summary

Method Description Formats
GET Get the user information for the current context. XML, JSON

GET authentication/current-context method detail

Example

Request parameters

Pagination and filtering parameters can be used with this method.

Response data keys
Name Description
capabilities List of capabilities assigned to role.
defaultApp Default app for the user, which is invoked at login.
defaultAppIsUserOverride Default app override indicates:
true = Default app overrides the user role default app.
false = Default app does not override the user role default app.
defaultAppSourceRole The role that determines the default app for the user, if the user has multiple roles.
email User email address.
password User password.
realname User full name.
restart_background_jobs Restart background search job that has not completed when Splunk Enterprise restarts indication:
true = Restart job.
false = Do not restart job.
roles Roles assigned to the user.
type User authentication system type:
  • LDAP
  • Scripted
  • Splunk
  • System (reserved for system user)
tz User timezone.
username Authenticated session owner name.
Application usage

Use this endpoint in a search command to get the current user: 

... rest /services/authentication/current-context/context | fields + username ...

[ Top ]

authentication/httpauth-tokens

https://<host>:<mPort>/services/authentication/httpauth-tokens


Description

List currently active session IDs and users.

See also

Method summary

Method Description Formats
GET List currently active session IDs/users. XML, JSON

GET authentication/httpauth-tokens method detail

Example

Request parameters

Pagination and filtering parameters can be used with this method.

Response data keys
Name Description
authString Unique identifier for this session.
searchId Search ID associated with the session, if it was created for a search job. If it is a login-type session, the value is empty.
timeAccessed Last time the session was touched.
userName Username associated with the session.
Application usage

The session ID token is valid for the duration of the web session.

Search command example: 

| rest /services/authentication/httpauth-tokens | search (NOT userName="splunk-system-user") searchId="" | table userName splunk_server timeAccessed


[ Top ]

authentication/httpauth-tokens/{name}

https://<host>:<mPort>/services/authentication/httpauth-tokens/<name>


Description

Get or delete the {name} session, where {name} is the session ID returned by auth/login.

See also

Method summary

Method Description Formats
DELETE Delete the session associated with this session ID. XML, JSON
GET Get session information. XML, JSON

DELETE authentication/httpauth-tokens/{name} method detail

Example

Request parameters

None

Response data keys

None

GET authentication/httpauth-tokens/{name} method detail

Example

Request parameters

None

Response data keys
Name Description
authString Unique session identifier.
searchId Session search ID, if it is a search job session. The value is blank for a login-type session.
timeAccessed Last time the session was touched.


userName Username associated with the session.

[ Top ]


authentication/providers/SAML

https://<host>:<mPort>/services/authentication/providers/SAML

Description

Access and create SAML configurations.

Authentication and authorization
Requires change_authentication capability for all operations.


Method summary

Method Description
GET Access SAML configurations.
POST Create a new SAML configuration.

GET authentication/providers/SAML method detail

Request parameters
None.

Response keys

Name Description
allowSslCompression Indicates whether ssl data compression is enabled.
assertionConsumerServiceUrl Endpoint where SAML assertions are posted by the IdP.
attributeAliasMail Specifies which SAML attribute is mapped to ‘email’. Defaults to ‘email’.
attributeAliasRealName Specifies which SAML attribute maps to ‘realName’. Defaults to realName.
attributeAliasRole Specifies which SAML attribute maps to role. Defaults to role.
attributeQueryRequestSigned Indicates whether Attribute Queries should be signed.
attributeQueryResponseSigned Indicates whether Attribute Query responses should be signed.
attributeQuerySoapPassword Credentials for making Attribute Query using SOAP over HTTP.
attributeQuerySoapUsername Credentials for making Attribute Query using SOAP over HTTP.
attributeQueryTTL ttl (time to live) for the Attribute Query credentials cache.
blacklistedAutoMappedRoles Comma separated list of Splunk platform roles that should be blacklisted from being auto-mapped from the IDP Response.
blacklistedUsers Comma separated list of user names from the IDP response to be blacklisted by the Splunk platform.
caCertFile File path for CA certificate. For example, /home/user123/saml-install/etc/auth/server.pem
cipherSuite Ciphersuite for making Attribute Queries using ssl. For example, TLSv1+HIGH:@STRENGTH.
defaultRoleIfMissing Default role to use if no role is returned in a SAML response.
ecdhCurveName EC curves for ECDH/ECDHE key exchange - ssl setting.
entityId Unique id preconfigured by the IdP.
errorUrL URL to display for a SAML error. Errors may be due to incorrect or incomplete configuration in either the IDP or the Splunk platform.
errorUrlLabel Label or title of the content to which errorUrl points. Defaults to Click here to resolve SAML error..
fqdn Load balancer url.
idpAttributeQueryUrl IdP attribute query url where SAML attribute queries are sent.
idpCertPath Path for IdP certificate.
idpSLOUrl IdP sso url where SAML SSO requests are sent.
idpSSOUrl IdP SSO url where SAML SLO requests are sent.
maxAttributeQueryQueueSize Maximum number of Attribute jobs to queue.
maxAttributeQueryThreads Maximum number of threads for asynchronous Attribute Queries.
name Configuration stanza name.
nameIdFormat Specifies how subject is identified in SAML Assertion. Defaults to 
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Override it when using Azure AD as an IDP and set it to 
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
redirectAfterLogoutToUrl Redirect URL after user logout If no SLO URL is configured.
signAuthnRequest Indicates whether to sign authentication requests.
signedAssertion Indicates whether to sign SAML assertions.
singleLogoutServiceUrl URL where the IdP posts SAML Single Logout responses.
skipAttributeQueryRequestForUsers Used in conjunction with defaultRoleIFMissing. Indicates whether to skip Attribute Queries for some users.
spCertPath Service provider certificate path.
sslAltNameToCheck Alternate name to check in the peer certificate.
sslCommonNameToCheck Common name to check in the peer certificate.
sslKeysfile Location of service provider private key.
sslKeysfilePassword SSL password.
sslVerifyServerCert Indicates whether to verify peer certificate.
sslVersions SSL versions.
uiStatusPage Splunk Web page for redirecting users in case of errors.

Example request and response

GET authentication/providers/SAML


XML Request

curl -u admin:pass -k -X GET https://localhost:8089/services/authentication/providers/SAML

XML Response

 <title>SAML-auth</title>
 <id>https://localhost:8089/services/authentication/providers/SAML</id>
 <updated>2016-01-27T11:13:29-08:00</updated>
 <generator build="d4236ccf1981eec20e461cd26a1f808e0ae54e71" version="20160126"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/authentication/providers/SAML/_new" rel="create"/>
 <link href="/services/authentication/providers/SAML/_acl" rel="_acl"/>
 <opensearch:totalResults>1</opensearch:totalResults>
 <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
 <opensearch:startIndex>0</opensearch:startIndex>
 <s:messages/>
 <entry>
   <title>saml_settings</title>
   <id>https://localhost:8089/services/authentication/providers/SAML/saml_settings</id>
   <updated>2016-01-27T11:13:29-08:00</updated>
   <link href="/services/authentication/providers/SAML/saml_settings" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/authentication/providers/SAML/saml_settings" rel="list"/>
   <link href="/services/authentication/providers/SAML/saml_settings" rel="edit"/>
   <link href="/services/authentication/providers/SAML/saml_settings" rel="remove"/>
   <link href="/services/authentication/providers/SAML/saml_settings/disable" rel="disable"/>
   <content type="text/xml">
     <s:dict>
       <s:key name="allowSslCompression">true</s:key>
       <s:key name="assertionConsumerServiceUrl">https://wimpy.sv.splunk.com:29000/saml/acs</s:key>
       <s:key name="attributeQueryRequestSigned">1</s:key>
       <s:key name="attributeQueryResponseSigned">1</s:key>
       <s:key name="attributeQuerySoapPassword">******</s:key>
       <s:key name="attributeQuerySoapUsername"></s:key>
       <s:key name="attributeQueryTTL">3600</s:key>
       <s:key name="attribute_aliases"/>
       <s:key name="blacklistedAutoMappedRoles">
         <s:list/>
       </s:key>
       <s:key name="blacklistedUsers">
         <s:list/>
       </s:key>
       <s:key name="caCertFile">/home/rdimri/binary_11/etc/auth/server.pem</s:key>
       <s:key name="cipherSuite">TLSv1+HIGH:TLSv1.2+HIGH:@STRENGTH</s:key>
       <s:key name="defaultRoleIfMissing"></s:key>
       <s:key name="disabled">0</s:key>
       <s:key name="eai:acl">
         <s:dict>
           <s:key name="app"></s:key>
           <s:key name="can_list">1</s:key>
           <s:key name="can_write">1</s:key>
           <s:key name="modifiable">0</s:key>
           <s:key name="owner">system</s:key>
           <s:key name="perms">
             <s:dict>
               <s:key name="read">
                 <s:list>
                   <s:item>admin</s:item>
                   <s:item>splunk-system-role</s:item>
                 </s:list>
               </s:key>
               <s:key name="write">
                 <s:list>
                   <s:item>admin</s:item>
                   <s:item>splunk-system-role</s:item>
                 </s:list>
               </s:key>
             </s:dict>
           </s:key>
           <s:key name="removable">0</s:key>
           <s:key name="sharing">system</s:key>
         </s:dict>
       </s:key>
       <s:key name="ecdhCurves"></s:key>
       <s:key name="entityId">someOtherEntityId</s:key>
       <s:key name="errorUrl"></s:key>
       <s:key name="errorUrlLabel"></s:key>
       <s:key name="fqdn">https://wimpy.sv.splunk.com</s:key>
       <s:key name="idpCertPath">idpCert.pem</s:key>
       <s:key name="maxAttributeQueryQueueSize">100</s:key>
       <s:key name="maxAttributeQueryThreads">2</s:key>
       <s:key name="nameIdFormat"></s:key>
       <s:key name="protocol_endpoints">
         <s:dict>
           <s:key name="idpAttributeQueryUrl"></s:key>
           <s:key name="idpSLOUrl">http://idp.saml2.com:48080/openam/IDPSloPOST/metaAlias/idp</s:key>
           <s:key name="idpSSOUrl">http://idp.saml2.com:48080/openam/SSOPOST/metaAlias/idp</s:key>
         </s:dict>
       </s:key>
       <s:key name="redirectAfterLogoutToUrl"></s:key>
       <s:key name="signAuthnRequest">0</s:key>
       <s:key name="signedAssertion">1</s:key>
       <s:key name="singleLogoutServiceUrl">https://wimpy.sv.splunk.com:29000/saml/logout</s:key>
       <s:key name="skipAttributeQueryRequestForUsers">
         <s:list/>
       </s:key>
       <s:key name="spCertPath">/home/rdimri/binary_11/etc/auth/server.pem</s:key>
       <s:key name="sslAltNameToCheck"></s:key>
       <s:key name="sslCommonNameToCheck"></s:key>
       <s:key name="sslKeysfile">/home/rdimri/binary_11/etc/auth/server.pem</s:key>
       <s:key name="sslKeysfilePassword">******</s:key>
       <s:key name="sslVerifyServerCert">false</s:key>
       <s:key name="sslVersions">SSL3,TLS1.0,TLS1.1,TLS1.2</s:key>
       <s:key name="uiStatusPage">/account/status</s:key>
     </s:dict>
   </content>
 </entry>

POST authentication/providers/SAML method detail

Request parameters

Name Description
allowSslCompression Indicates whether ssl data compression is enabled.
assertionConsumerServiceUrl Endpoint where SAML assertions are posted by the IdP.
attributeAliasMail Specifies which SAML attribute is mapped to ‘email’. Defaults to ‘email’.
attributeAliasRealName Specifies which SAML attribute maps to ‘realName’. Defaults to realName.
attributeAliasRole Specifies which SAML attribute maps to role. Defaults to role.
attributeQueryRequestSigned Indicates whether Attribute Queries should be signed.
attributeQueryResponseSigned Indicates whether Attribute Query responses should be signed.
attributeQuerySoapPassword Credentials for making Attribute Query using SOAP over HTTP.
attributeQuerySoapUsername Credentials for making Attribute Query using SOAP over HTTP.
attributeQueryTTL ttl (time to live) for the Attribute Query credentials cache.
blacklistedAutoMappedRoles Comma separated list of Splunk platform roles that should be blacklisted from being auto-mapped from the IDP Response.
blacklistedUsers Comma separated list of user names from the IDP response to be blacklisted by the Splunk platform.
caCertFile File path for CA certificate. For example, /home/user123/saml-install/etc/auth/server.pem
cipherSuite Ciphersuite for making Attribute Queries using ssl. For example, TLSv1+HIGH:@STRENGTH.
defaultRoleIfMissing Default role to use if no role is returned in a SAML response.
ecdhCurveName EC curves for ECDH/ECDHE key exchange - ssl setting.
entityId Required. Unique id preconfigured by the IdP.
errorUrL URL to display for a SAML error. Errors may be due to incorrect or incomplete configuration in either the IDP or the Splunk platform.
errorUrlLabel Label or title of the content to which errorUrl points. Defaults to Click here to resolve SAML error..
fqdn Load balancer url.
idpAttributeQueryUrl IdP attribute query url where SAML attribute queries are sent.
idpCertPath Path for IdP certificate.
idpSLOUrl IdP sso url where SAML SSO requests are sent.
idpSSOUrl Required. IdP SSO url where SAML SLO requests are sent.
maxAttributeQueryQueueSize Maximum number of Attribute jobs to queue.
maxAttributeQueryThreads Maximum number of threads for asynchronous Attribute Queries.
name Required. Configuration stanza name.
nameIdFormat Specifies how subject is identified in SAML Assertion. Defaults to 
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Override it when using Azure AD as an IDP and set it to 
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
redirectAfterLogoutToUrl Redirect URL after user logout If no SLO URL is configured.
signAuthnRequest Indicates whether to sign authentication requests.
signedAssertion Indicates whether to sign SAML assertions.
singleLogoutServiceUrl URL where the IdP posts SAML Single Logout responses.
skipAttributeQueryRequestForUsers Used in conjunction with defaultRoleIFMissing. Indicates whether to skip Attribute Queries for some users.
spCertPath Service provider certificate path.
sslAltNameToCheck Alternate name to check in the peer certificate.
sslCommonNameToCheck Common name to check in the peer certificate.
sslKeysfile Location of service provider private key.
sslKeysfilePassword SSL password.
sslVerifyServerCert Indicates whether to verify peer certificate.
sslVersions SSL versions.
uiStatusPage Splunk Web page for redirecting users in case of errors.


Response keys
None.

Example request and response

POST authentication/providers/SAML


XML Request

curl -u admin:password -k -X POST https://localhost:8089/services/authentication/providers/SAML -d "name=saml_settings" -d "entityId=http://myURL" -d "idpMetadataFile=/home/my_folder/binary_11/openam.xml"
-d "idpSSOUrl=http://idp.saml2.com:8080/openam/SSOPOST/metaAlias/idp"

XML Response

<title>SAML-auth</title>
  <id>https://localhost:8089/services/authentication/providers/SAML</id>
  <updated>2016-01-26T11:51:18-08:00</updated>
  <generator build="420c52964b8db66082924ce2190253da9a41e6c" version="20160126"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/providers/SAML/_new" rel="create"/>
  <link href="/services/authentication/providers/SAML/_acl" rel="_acl"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>saml_settings</title>
    <id>https://localhost:8089/services/authentication/providers/SAML/saml_settings</id>
    <updated>2016-01-26T11:51:18-08:00</updated>
    <link href="/services/authentication/providers/SAML/saml_settings" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authentication/providers/SAML/saml_settings" rel="list"/>
    <link href="/services/authentication/providers/SAML/saml_settings" rel="edit"/>
    <link href="/services/authentication/providers/SAML/saml_settings" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="allowSslCompression">true</s:key>
        <s:key name="assertionConsumerServiceUrl">https://localhost:8000/saml/acs</s:key>
        <s:key name="attributeQueryRequestSigned">1</s:key>
        <s:key name="attributeQueryResponseSigned">1</s:key>
        <s:key name="attributeQuerySoapPassword">******</s:key>
        <s:key name="attributeQuerySoapUsername"></s:key>
        <s:key name="attributeQueryTTL">3600</s:key>
        <s:key name="attribute_aliases"/>
        <s:key name="blacklistedAutoMappedRoles">
          <s:list/>
        </s:key>
        <s:key name="blacklistedUsers">
          <s:list/>
        </s:key>
        <s:key name="caCertFile">/home/my_folder/binary_11/etc/auth/server.pem</s:key>
        <s:key name="cipherSuite">TLSv1+HIGH:TLSv1.2+HIGH:@STRENGTH</s:key>
        <s:key name="defaultRoleIfMissing"></s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="ecdhCurves"></s:key>
        <s:key name="entityId">http://rdimriSplunk</s:key>
        <s:key name="errorUrl"></s:key>
        <s:key name="errorUrlLabel"></s:key>
        <s:key name="fqdn">https://splunk.com</s:key>
        <s:key name="idpCertPath">idpCert.pem</s:key>
        <s:key name="maxAttributeQueryQueueSize">100</s:key>
        <s:key name="maxAttributeQueryThreads">2</s:key>
        <s:key name="nameIdFormat"></s:key>
        <s:key name="protocol_endpoints">
          <s:dict>
            <s:key name="idpAttributeQueryUrl"></s:key>
            <s:key name="idpSLOUrl">http://idp.saml2.com:8080/openam/IDPSloPOST/metaAlias/idp</s:key>
            <s:key name="idpSSOUrl">http://idp.saml2.com:8080/openam/SSOPOST/metaAlias/idp</s:key>
          </s:dict>
        </s:key>
        <s:key name="redirectAfterLogoutToUrl"></s:key>
        <s:key name="signAuthnRequest">0</s:key>
        <s:key name="signedAssertion">1</s:key>
        <s:key name="singleLogoutServiceUrl">https://localhost:8000/saml/logout</s:key>
        <s:key name="skipAttributeQueryRequestForUsers">
          <s:list/>
        </s:key>
        <s:key name="spCertPath">/home/rdimri/binary_11/etc/auth/server.pem</s:key>
        <s:key name="sslAltNameToCheck"></s:key>
        <s:key name="sslCommonNameToCheck"></s:key>
        <s:key name="sslKeysfile">/home/my_folder/binary_11/etc/auth/server.pem</s:key>
        <s:key name="sslKeysfilePassword">******</s:key>
        <s:key name="sslVerifyServerCert">false</s:key>
        <s:key name="sslVersions">SSL3,TLS1.0,TLS1.1,TLS1.2</s:key>
        <s:key name="uiStatusPage">/account/status</s:key>
      </s:dict>
    </content>
  </entry>


authentication/providers/SAML/{stanza_name}

https://<host>:<mPort>/services/authentication/providers/SAML/{stanza_name}

Description

Access and update a particular SAML configuration.

Authentication and authorization
Requires change_authentication capability for all operations.


Method summary

Method Description
GET Access a SAML configuration.
POST Update a SAML configuration.

authentication/users

https://<host>:<mPort>/services/authentication/users


Description

Create a user and list current users.

See also

Method summary

Method Description Formats
GET List registered users. XML, JSON
POST Create a user. XML, JSON

GET authentication/users method detail

Example

Request parameters

Pagination and filtering parameters can be used with this method.

Response data keys
Name Description
capabilities List of capabilities assigned to role.
defaultApp Default app for the user, which is invoked at login.
defaultAppIsUserOverride Default app override indicates:
true = Default app overrides the user role default app.
false = Default app does not override the user role default app.
defaultAppSourceRole The role that determines the default app for the user, if the user has multiple roles.
email User email address.
password User password.
realname User full name.
restart_background_jobs Restart background search job that has not completed when Splunk Enterprise restarts indication:
true = Restart job.
false = Do not restart job.
roles Roles assigned to the user.
type User authentication system type:
  • LDAP
  • Scripted
  • Splunk
  • System (reserved for system user)
tz User timezone.

POST authentication/users method detail

Example

Request parameters
Name Datatype Default Description
createrole Boolean false Flag to indicate that a new role should be created for the user. If set to "true", the new role user-<name> is created and assigned to the user. The <name> portion of the new role matches the name parameter value passed in with this POST request.

If set to "false", at least one existing role must be specified using the roles parameter for the POST request.
defaultApp String User default app. This overrides the default app inherited from the user roles.
email String User email address.
force-change-pass Boolean Force user to change password indication:
true = Force password change.
false = Do not force password change.
name
required 		String Unique user login name.
password
required 		String User login password.
realname String Full user name.
restart_background_jobs Boolean Restart background search job that has not completed when Splunk Enterprise restarts indication:
true = Restart job.
false = Do not restart job.
roles String One or more existing roles to assign to this user. At least one existing role is required if you are not using the createrole parameter to create a new role for the user. If you are using createrole to create a new role, you can optionally use this parameter to specify additional roles to assign to the user.
tz String User timezone.
Response data keys

None

Application usage

When creating a user you must specify at least one role.


[ Top ]

authentication/users/{name}

https://<host>:<mPort>/services/authentication/users/<name>

Description

Get, update, or delete the {name} user.

See also

List of available capabilities

Method summary

Method Description Formats
DELETE Remove the specified user from the system. XML, JSON
GET Return the specified user information. XML, JSON
POST Update the specified user information. XML, JSON

DELETE authentication/users/{name} method detail

Example

Request parameters

None

Response data keys

None

GET authentication/users/{name} method detail

Example

Request parameters

None

Response data keys
Name Description
capabilities List of capabilities assigned to role.
defaultApp Default app for the user, which is invoked at login.
defaultAppIsUserOverride Default app override indicates:
true = Default app overrides the user role default app.
false = Default app does not override the user role default app.
defaultAppSourceRole The role that determines the default app for the user, if the user has multiple roles.
email User email address.
password User password.
realname User full name.
restart_background_jobs Restart background search job that has not completed when Splunk Enterprise restarts indication:
true = Restart job.
false = Do not restart job.
roles Roles assigned to the user.
type User authentication system type:
  • LDAP
  • Scripted
  • Splunk
  • System (reserved for system user)
tz User timezone.
Application usage

{name} is not case-sensitive.


POST authentication/users/{name} method detail

Example

Request parameters
Name Datatype Default Description
defaultApp String User default app. This overrides the default app inherited from the user roles.
email String User email address.
force-change-pass Boolean Force user to change password indication:
true = Force password change.
false = Do not force password change.
password
required 		String User login password.
realname String Full user name.
restart_background_jobs Boolean Restart background search job that has not completed when Splunk Enterprise restarts indication:
true = Restart job.
false = Do not restart job.
roles String One or more existing roles to assign to this user.
tz String User timezone.
Response data keys
Name Description
capabilities List of capabilities assigned to role.
defaultApp Default app for the user, which is invoked at login.
defaultAppIsUserOverride Default app override indicates:
true = Default app overrides the user role default app.
false = Default app does not override the user role default app.
defaultAppSourceRole The role that determines the default app for the user, if the user has multiple roles.
email User email address.
password User password.
realname User full name.
restart_background_jobs Restart background search job that has not completed when Splunk Enterprise restarts indication:
true = Restart job.
false = Do not restart job.
roles Roles assigned to the user.
type User authentication system type:
  • LDAP
  • Scripted
  • Splunk
  • System (reserved for system user)
tz User timezone.

[ Top ]

authorization/capabilities

https://<host>:<mPort>/services/authorization/capabilities

Description

Get a list of all capabilities.

Method summary

Method Description Formats
GET List system capabiilities. XML, JSON

GET authorization/capabilities method detail

Example

Request parameters

Pagination and filtering parameters can be used with this method.

Response data keys
Name Description
capabilities List of capabilities assigned to role.

[ Top ]

authorization/roles

https://<host>:<mPort>/services/authorization/roles


Description

Create a role or get a list of defined roles with role permissions.

See also

Method summary

Method Description Formats
GET List all roles and the permissions for each role. XML, JSON
POST Create a user role. XML

GET authorization/roles method detail

Example

Request parameters

Pagination and filtering parameters can be used with this method.

Response data keys
Name Description
capabilities List of capabilities assigned to role.

The Securing Splunk manual describes List of available capabilities.

cumulativeRTSrchJobsQuota Maximum number of concurrently running real-time searches for all role members. Warning message logged when limit is reached.
cumulativeSrchJobsQuota Maximum number of concurrently running searches for all role members. Warning message logged when limit is reached.
defaultApp The name of the app to use as the default app for this role.

A user-specific default app overrides this.

imported_capabilities List of capabilities assigned to role made available from imported roles.
imported_roles List of imported roles for this role.

Importing other roles imports all aspects of that role, such as capabilities and allowed indexes to search. In combining multiple roles, the effective value for each attribute is value with the broadest permissions.

imported_rtSrchJobsQuota The maximum number of concurrent real time search jobs for this role. This count is independent from the normal search jobs limit.

imported_rtSrchJObsQuota specifies the quota imported from other roles.

imported_srchDiskQuota The maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.

imported_srchDiskQuota specifies the quota for this role that have imported from other roles.

imported_srchFilter Search string, imported from other roles, that restricts the scope of searches run by this role.

Search results for this role only show events that also match this search string. When a user has multiple roles with different search filters, they are combined with an OR.

imported_srchIndexesAllowed A list of indexes, imported from other roles, this role has permissions to search.
imported_srchIndexesDefault A list of indexes, imported from other roles, that this role defaults to when no index is specified in a search.
imported_srchJobsQuota The maximum number of historical searches for this role that are imported from other roles.
imported_srchTimeWin Maximum time span of a search, in seconds.

0 indicates searches are not limited to any specific time window.

imported_srchTimeWin specifies the limit from imported roles.

rtSrchJobsQuota The maximum number of concurrent real time search jobs for this role. This count is independent from the normal search jobs limit.
srchDiskQuota The maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.
srchFilter Search string that restricts the scope of searches run by this role.

Search results for this role only show events that also match this search string. When a user has multiple roles with different search filters, they are combined with an OR.

srchIndexesAllowed A list of indexes this role has permissions to search.
srchIndexesDefault List of search indexes that default to this role when no index is specified.
srchJobsQuota The maximum number of concurrent real time search jobs for this role.

This count is independent from the normal search jobs limit.

srchTimeWin Maximum time span of a search, in seconds.

0 indicates searches are not limited to any specific time window.

POST authorization/roles method detail

Example

Request parameters
Name Datatype Default Description
capabilities String List of capabilities assigned to role. To send multiple capabilities, send this argument multiple times.

Roles inherit all capabilities from imported roles.

cumulativeRTSrchJobsQuota Number Maximum number of concurrently running real-time searches that all members of this role can have.

Note: If a user belongs to multiple roles then the user first consumes searches from the roles with the largest cumulative search quota. When the quota of a role is completely used up then roles with lower quotas are examined.

cumulativeSrchJobsQuota Number Maximum number of concurrently running searches for all role members. Warning message logged when limit is reached.

Note: If a user belongs to multiple roles then the user first consumes searches from the roles with the largest cumulative search quota. When the quota of a role is completely used up then roles with lower quotas are examined.

defaultApp String Specify the name of the app to use as the default app for the role.A user-specific default app overrides this.

The name you specify is the name of the folder containing the app.

imported_roles String Specify a role to import attributes from. Specify many of these separately to import multiple roles. By default a role imports no other roles.

Importing other roles imports all aspects of that role, such as capabilities and allowed indexes to search. In combining multiple roles, the effective value for each attribute is value with the broadest permissions.

Default Splunk Enterprise roles are:

  • admin
  • can_delete
  • power
  • user

You can specify additional roles created.

name
required 		String The name of the user role to create.
rtSrchJobsQuota Number Specify the maximum number of concurrent real time search jobs for this role.

This count is independent from the normal search jobs limit.

srchDiskQuota Number Specifies the maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.
srchFilter String Specify a search string that restricts the scope of searches run by this role. Search results for this role only show events that also match the search string you specify. In the case that a user has multiple roles with different search filters, they are combined with an OR.

The search string can include source, host, index, eventtype, sourcetype, search fields, *, OR and, AND.

Example: "host=web* OR source=/var/log/*"

Note: You can also use the srchIndexesAllowed and srchIndexesDefault parameters to limit the search on indexes.

srchIndexesAllowed String An index this role has permissions to search. To set several of these, pass this argument several times. These may be wildcarded, but the index name must begin with an underscore to match internal indexes.

Search indexes available by default from Splunk Enterprise include:

  • All internal indexes
  • All non-internal indexes
  • _audit
  • _blocksignature
  • _internal
  • _thefishbucket
  • history
  • main

You can also specify other search indexes added to the server.

srchIndexesDefault String For this role, indexes to search when no index is specified.

These indexes can be wildcarded, with the exception that '*' does not match internal indexes. To match internal indexes, start with '_'. All internal indexes are represented by '_*'.

A user with this role can search other indexes using "index= "

For example, "index=special_index".

Search indexes available by default from Splunk Enterprise include:

  • All internal indexes
  • All non-internal indexes
  • _audit
  • _blocksignature
  • _internal
  • _thefishbucket
  • history
  • main
  • other search indexes added to the server
srchJobsQuota Number The maximum number of concurrent searches a user with this role is allowed to run. In the event of many roles per user, the maximum of these quotas is applied.
srchTimeWin Number Maximum time span of a search, in seconds.

By default, searches are not limited to any specific time window. To override any search time windows from imported roles, set srchTimeWin to '0', as the 'admin' role does.

Response data keys

None

[ Top ]

authorization/roles/{name}

https://<host>:<mPort>/services/authorization/roles/<name>

Description

Access, update, or delete properties of the {name} role.

See also

List of available capabilities

Method summary

Method Description Formats
DELETE Delete the specified role. XML
GET Get the specified role permissions. XML, JSON
POST Create/update the specified role. XML

DELETE authorization/roles/{name} method detail

Example

Request parameters

None

Response data keys

None

GET authorization/roles/{name} method detail

Example

Request parameters

None

Response data keys
Name Description
capabilities List of capabilities assigned to role.

The Securing Splunk manual describes all capabilities.

cumulativeRTSrchJobsQuota Maximum number of concurrently running real-time searches for all role members. Warning message logged when limit is reached.
cumulativeSrchJobsQuota Maximum number of concurrently running searches for all role members. Warning message logged when limit is reached.
defaultApp The name of the app to use as the default app for this role.

A user-specific default app overrides this.

imported_capabilities List of capabilities assigned to role that were made available from imported roles.
imported_roles List of imported roles for this role.

Importing other roles imports all aspects of that role, such as capabilities and allowed indexes to search. In combining multiple roles, the effective value for each attribute is value with the broadest permissions.

imported_rtSrchJobsQuota The maximum number of concurrent real time search jobs for this role. This count is independent from the normal search jobs limit.

imported_rtSrchJObsQuota specifies the quota imported from other roles.

imported_srchDiskQuota The maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.

imported_srchDiskQuota specifies the quota for this role that have imported from other roles.

imported_srchFilter Search string, imported from other roles, that restricts the scope of searches run by this role.

Search results for this role only show events that also match this search string. When a user has multiple roles with different search filters, they are combined with an OR.

imported_srchIndexesAllowed A list of indexes, imported from other roles, this role has permissions to search.
imported_srchIndexesDefault A list of indexes, imported from other roles, that this role defaults to when no index is specified in a search.
imported_srchJobsQuota The maximum number of historical searches for this role that are imported from other roles.
imported_srchTimeWin Maximum time span of a search, in seconds.

0 indicates searches are not limited to any specific time window.

imported_srchTimeWin specifies the limit from imported roles.

rtSrchJobsQuota The maximum number of concurrent real time search jobs for this role. This count is independent from the normal search jobs limit.
srchDiskQuota The maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.
srchFilter Search string that restricts the scope of searches run by this role.

Search results for this role only show events that also match this search string. When a user has multiple roles with different search filters, they are combined with an OR.

srchIndexesAllowed A list of indexes this role has permissions to search.
srchIndexesDefault List of search indexes that default to this role when no index is specified.
srchJobsQuota The maximum number of concurrent real time search jobs for this role.

This count is independent from the normal search jobs limit.

srchTimeWin Maximum time span of a search, in seconds.

0 indicates searches are not limited to any specific time window.

POST authorization/roles/{name} method detail

Example

Request parameters
Name Datatype Default Description
capabilities String List of capabilities assigned to role. To send multiple capabilities, send this argument multiple times.

Roles inherit all capabilities from imported roles. For more information, refer to About defining roles with capabilities.

cumulativeRTSrchJobsQuota Number Maximum number of concurrently running real-time searches that all members of this role can have.

Note: If a user belongs to multiple roles then the user first consumes searches from the roles with the largest cumulative search quota. When the quota of a role is completely used up then roles with lower quotas are examined.

cumulativeSrchJobsQuota Number Maximum number of concurrently running searches for all role members. Warning message logged when limit is reached.

Note: If a user belongs to multiple roles then the user first consumes searches from the roles with the largest cumulative search quota. When the quota of a role is completely used up then roles with lower quotas are examined.

defaultApp String Specify the name of the app to use as the default app for the role.A user-specific default app overrides this.

The name you specify is the name of the folder containing the app.

imported_capabilities String TBD
imported_roles String Specify a role to import attributes from. Specify many of these separately to import multiple roles. By default a role imports no other roles.

Importing other roles imports all aspects of that role, such as capabilities and allowed indexes to search. In combining multiple roles, the effective value for each attribute is value with the broadest permissions.

Default Splunk Enterprise roles are:

  • admin
  • can_delete
  • power
  • user

You can specify additional roles created.

imported_rtSrchJobsQuota String TBD
imported_srchDiskQuota String TBD
imported_srchFilter String TBD
imported_srchIndexesAllowed String TBD
imported_srchIndexesDefault String TBD
imported_srchJobsQuota String TBD
imported_srchTimeWin String TBD
name String Required field.
rtSrchJobsQuota Number Specify the maximum number of concurrent real time search jobs for this role.

This count is independent from the normal search jobs limit.

srchDiskQuota Number Specifies the maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.
srchFilter String Specify a search string that restricts the scope of searches run by this role. Search results for this role only show events that also match the search string you specify. In the case that a user has multiple roles with different search filters, they are combined with an OR.

The search string can include source, host, index, eventtype, sourcetype, search fields, *, OR and, AND.

Example: "host=web* OR source=/var/log/*"

Note: You can also use the srchIndexesAllowed and srchIndexesDefault parameters to limit the search on indexes.

srchIndexesAllowed String An index this role has permissions to search. To set several of these, pass this argument several times. These may be wildcarded, but the index name must begin with an underscore to match internal indexes.

Search indexes available by default from Splunk Enterprise include:

  • All internal indexes
  • All non-internal indexes
  • _audit
  • _blocksignature
  • _internal
  • _thefishbucket
  • history
  • main

You can also specify other search indexes added to the server.

srchIndexesDefault String For this role, indexes to search when no index is specified.

These indexes can be wildcarded, with the exception that '*' does not match internal indexes. To match internal indexes, start with '_'. All internal indexes are represented by '_*'.

A user with this role can search other indexes using "index= "

For example, "index=special_index".

Search indexes available by default from Splunk Enterprise include:

  • All internal indexes
  • All non-internal indexes
  • _audit
  • _blocksignature
  • _internal
  • _thefishbucket
  • history
  • main
  • other search indexes added to the server
srchJobsQuota Number The maximum number of concurrent searches a user with this role is allowed to run. In the event of many roles per user, the maximum of these quotas is applied.
srchTimeWin Number Maximum time span of a search, in seconds.

By default, searches are not limited to any specific time window. To override any search time windows from imported roles, set srchTimeWin to '0', as the 'admin' role does.

Response data keys

None

[ Top ]

storage/passwords

https://<host>:<mPort>/services/storage/passwords

Authentication: Required

Description

Create or update user credentials, or list credentials for all users.

Method summary

Method Description Formats
GET List available credentials. XML, JSON
POST Create/update new credentials. XML, JSON

GET storage/passwords method detail

Example

Request parameters

Pagination and filtering parameters can be used with this method.

Response data keys
Name Description
clear_password Clear text password.
encr_password Encrypted, stored password.
password Password mask, always ********.
realm Realm in which credentials are valid.
username User name associated with credentials.
Application usage

Only admin-level users can access this endpoint.

The password is encrypted with a secure key resident on the same server.


POST storage/passwords method detail

Example

Request parameters
Name Datatype Default Description
name
required 		String Credentials user name.
password
required 		String Credentials user password.
realm String Credentials realm.
Response data keys
Name Description
clear_password Clear text password.
encr_password Encrypted, stored password.
password Password mask, always ********.
realm Realm in which credentials are valid.
username User name associated with credentials.
Application usage

The password credential is the only part of the user credentials that is stored securely.


[ Top ]

storage/passwords/{name}

https://<host>:<mPort>/services/storage/passwords/<name>

Description

Update, delete, or list credentials for the {name} user.

Method summary

Method Description Formats
DELETE Delete the specified user credentials. XML, JSON
GET Get the specified user credentials. XML, JSON
POST Update the specified user credentials. XML, JSON

DELETE storage/passwords/{name} method detail

Example

Request parameters

None

Response data keys

None

The {name} part of the URL must be bounded by the colon ( : ) symbol.

Example: 

/services/storage/passwords/:uname:


GET storage/passwords/{name} method detail

Example

Request parameters

None

Response data keys
Name Description
clear_password Clear text password.
encr_password Encrypted, stored password.
password Password mask, always ********.
realm Realm in which credentials are valid.
username User name associated with credentials.

POST storage/passwords/{name} method detail

Example

Request parameters
Name Datatype Default Description
password String User password credential.
Response data keys
Name Description
clear_password Clear text password.
encr_password Encrypted, stored password.
password Password mask, always ********.
realm Realm in which credentials are valid.
username User name associated with credentials.
Application usage

The password credential is the only part of the user credentials that is stored securely.

[ Top ]

Retrieved from "https://docs.splunk.com/index.php?title=Documentation:Splunk:RESTREF:RESTaccess:6.3.0beta&oldid=876216"
PREVIOUS
URI quick reference 		  NEXT
Access endpoint examples

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters