Use authentication tokens

If you have been assigned an authentication token, you can access a Splunk platform instance using Representational State Transfer (REST) calls. On Splunk Enterprise, you can also use the CLI. These methods let you access the instance and make requests without having to authenticate with credentials.

You must possess a valid token that has been given to you from an administrator who maintains the instance. The token cannot be expired, as expired tokens are unusable. Administrators can delay when the validity of a token starts, meaning that the token cannot be used until its validity begins.

You cannot use a token on any instance other than the instance where the administrator granted you the token. For example, if you have a token for server1, and need access to server2, you must ask the administrator for server2 to give you access to a token there. There is an exception on search head clusters: if an administrator grants you token-based access to a search head cluster, that token is valid for all search head cluster nodes.

You lose access to the instance through the token if any of the following occurs:

• The token expires. You can ask the administrator to issue a new token to regain access.
• The administrator disables the token. The administrator must reenable the token before you can use it again.
• The administrator deletes the token. You can ask the administrator to issue a new token to regain access.
• The administrator disables token authentication, either temporarily or permanently.
• The administrator deletes your account.
• You lock out or disable your Active Directory account on a Splunk platform instance that uses LDAP to connect to Active Directory.

Confirm that the administrator sends you the full token when they assign it to you. You must have the full token to authenticate with it. If you do not, the Splunk platform rejects those authentication requests as if you had entered incorrect credentials.

Use an authentication token to make REST calls to an instance

After you receive a valid token for the instance you want to use, you can use the token to make calls to REST endpoints on the instance. Your access is the same as what you have if you logged in with credentials.

The type of web request you make depends on the endpoint you want to access and what you want to do with the endpoint. For more information on REST endpoints and how to use them, see the REST API User Manual and the REST API Reference Manual for information on REST and using REST endpoints.

Understand the ramifications of making REST calls using tokens. Tokens are only a method of authentication, not a safeguard against making potentially dangerous changes to a Splunk platform instance. If you have questions or concerns about using tokens, contact your administrator.

Currently, tokens are available only for making REST calls or using the CLI to access a Splunk Enterprise instance. You cannot use tokens to authenticate using Splunk Web.

Use your REST web client or command line tool to make an HTTP GET, POST, or DELETE request on an endpoint. When you make the request, include the management port of the instance:

curl -H "Authorization: <type> <token>" -X <method> https://<instance host name or IP address>:<management port>/<REST endpoint> -d <data...> [-d <data...>...]

For <type>, you can use one of the following:

• Bearer: Means to use a bearer token header, the standard for Javascript Object Notation (JSON) Web Tokens (JWTs), on which Splunk authentication tokens are based.
• Splunk: Means to use the Splunk header for authentication.

Use the correct header type for your application. If you don't, the request might not authenticate.

If the operation succeeds, the command prints a response in XML that contains the information that the instance generated upon accessing the endpoint.

An authentication failure appears as follows:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <messages>
    <msg type="WARN">call not properly authenticated</msg>
  </messages>
</response>

Insufficient permissions to access the endpoint appear as follows:

<response>
  <messages>
    <msg type="ERROR">You (user=<user>) do not have permission to perform this operation (requires capability: <capability> [or <capability>...]).</msg>
  </messages>
</response>

Use the CLI to access a Splunk Enterprise instance with a token

You can run commands with the Splunk CLI and use a token as authentication rather than standard credentials. You can do this with any command that normally requires authentication.

Use the -token CLI argument to supply the token:

/opt/splunk/bin/splunk search '*' -token <token>

Examples

The following examples assume that you have properly configured TLS certificates on your Splunk Enterprise instance. If you have not, then the commands will not work. This is not an issue on Splunk Cloud Platform instances, as TLS is always properly configured on those instance types.

As a temporary measure to test connectivity to TLS, you can use the -k argument for curl to bypass certificate review. Do not do this long term, as certificates are a key part of maintaining security in TLS.

Do not use the -k argument for curl when you want to access Splunk Cloud Platform instances. This action results in reduced security and the command can fail.

Examples for accessing REST endpoints using tokens

The following example performs a Splunk search by accessing the /services/search/jobs endpoint:

curl -H "Authorization: Bearer eyJraWQ..." -X POST https://10.24.38.54:8089/services/search/jobs -d search="search error earliest=-7d"

The following example accesses the /apps/local endpoint to retrieve a list of local Splunk applications on the instance:

curl -H "Authorization: Bearer eyJraWQ..." -X GET https://10.224.100.135:34740/services/apps/local
<?xml-stylesheet type="text/xml" href="/static/atom.xsl"?>
<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>localapps</title>
  <id>https://10.224.100.135:34740/services/apps/local</id>
  <updated>2019-02-13T23:05:24+00:00</updated>
  <generator build="7d447048a453" version="7.3.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/apps/local/_new" rel="create"/>
  <link href="/services/apps/local/_reload" rel="_reload"/>
  <opensearch:totalResults>18</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>alert_logevent</title>
...
  </entry>
...
</feed>

The following example accesses the authorization/roles endpoint to get information about the roles that have been configured on the instance:

curl -H "Authorization: Bearer eyJraWQ..." -X GET https://idx1.splunkcorp.com:8089/services/authorization/roles

<?xml version="1.0" encoding="UTF-8"?>
<!--This is to override browser formatting; see server.conf[httpServer] to disable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .-->
<?xml-stylesheet type="text/xml" href="/static/atom.xsl"?>
<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>roles</title>
  <id>https://10.224.100.135:34740/services/authorization/roles</id>
  <updated>2019-02-13T23:10:41+00:00</updated>
  <generator build="7d447048a453" version="7.3.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authorization/roles/_new" rel="create"/>
  <opensearch:totalResults>5</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>admin</title>
...
   </entry>
...
</feed>

The following example uses a `Splunk` header to access a REST endpoint provided by the IT Service Intelligence (ITSI) app:

 
curl -H "Authorization: Splunk  oc5mKz..." -X GET https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/v4.3.1/service/

Examples for using the CLI with tokens

The following example searches splunkd.log on the local instance for the string JsonWebToken:

./splunk search "index=_internal source=*splunkd.log* JsonWebToken" -token eyJraWQ...

09-18-2019 15:48:25.853 -0700 INFO  JsonWebToken - Saving tokenId: f61b7aecf75e95cd226234f4fe901ed450fa323648165a91bf02f0a07c5199eb, authType: Splunk, IDP: Splunk to KVStore
09-18-2019 15:38:33.825 -0700 INFO  JsonWebToken - Saving tokenId: f61b7aecf75e95cd226234f4fe901ed450fa323648165a91bf02f0a07c5199eb, authType: Splunk, IDP: Splunk to KVStore
09-10-2019 14:45:14.201 -0700 INFO  loader - JsonWebToken Manager registration with KVStore successful.

The following example shows all of the apps that are present on the Splunk platform instance:

./splunk display app -token eyJraWQ...

alert_logevent                 CONFIGURED          ENABLED             INVISIBLE           
alert_webhook                  CONFIGURED          ENABLED             INVISIBLE           
appsbrowser                    CONFIGURED          ENABLED             INVISIBLE           
introspection_generator_addon  CONFIGURED          ENABLED             INVISIBLE           
launcher                       CONFIGURED          ENABLED             VISIBLE             
learned                        UNCONFIGURED        ENABLED             INVISIBLE           
legacy                         UNCONFIGURED        DISABLED            INVISIBLE           
sample_app                     UNCONFIGURED        DISABLED            INVISIBLE           
search                         CONFIGURED          ENABLED             VISIBLE             
splunk_archiver                CONFIGURED          ENABLED             INVISIBLE           
splunk_gdi                     UNCONFIGURED        ENABLED             INVISIBLE           
splunk_httpinput               UNCONFIGURED        ENABLED             INVISIBLE           
splunk_instrumentation         UNCONFIGURED        ENABLED             VISIBLE             
splunk_internal_metrics        UNCONFIGURED        ENABLED             INVISIBLE           
splunk_metrics_workspace       UNCONFIGURED        ENABLED             VISIBLE             
splunk_monitoring_console      UNCONFIGURED        ENABLED             VISIBLE             
SplunkForwarder                UNCONFIGURED        DISABLED            INVISIBLE           
SplunkLightForwarder           UNCONFIGURED        DISABLED            INVISIBLE