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
Manage or delete authentication tokens | Troubleshoot token authentication |
This documentation applies to the following versions of Splunk Cloud Platform™: 9.2.2406, 8.2.2112, 8.2.2202, 9.0.2205, 8.2.2201, 8.2.2203, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release)
Feedback submitted, thanks!