OAuth2 Authentication Tokens in Splunk

By: Jon Walthour | Technical Architect

Authentication tokens in Splunk allow you to access Splunk via the REST interface, usually serviced on port 8089 on a search head, without needing to pass a username/password combinations in the call. The type of tokens Splunk employs are JSON web tokens.

To utilize an authentication token to access Splunk via API, you would use a curl command something like the following:

curl -X GET -H "Authorization: Bearer <auth-token>" -d search="search index%3D_internal|head 3" -d output_mode=xml

To set up and administer tokens, go to Settings > Tokens (under “Users and Authentication”). To administer tokens, you need to have the “edit_all_tokens” capability.

Here is what you can do with the tokens in Splunk in terms of reporting and alerting:

For reporting, here’s an example SPL to get you started. NOTE: All of these searches and alerts should be run from the Monitoring Console app on your Monitoring Console instance so that all search heads can be queried and reported on at once. However, they could be run from any search head by changing “splunk_server_group=dmc_group_search_head” to “splunk_server=local”:

| rest splunk_server_group=dmc_group_search_head /services/ authorization/tokens

| convert ctime(claims.exp), ctime(claims.iat), ctime(claims.nbr)

| rename claims.aud as audience, claims.exp as expiration_date, claims.iat as issued_at_date, claims.idp as identity_provider, claims.iss as issuer, claims.nbr as not_before_date, claims.roles as roles, claims.sub as user, headers.alg as algorithm, headers.kid as kid, headers.ttyp as token_type, headers.ver as version, lastUsed as last_used_date, lastUsedIp as last_used_from_ip_address, title as token

| eval last_used_date=if(last_used_date=0,"not yet used",strftime(last_used_date,"%m/%d/%Y %H:%M:%S")), last_used_from_ip_address=if(last_used_from_ip_address=""," not yet used",last_used_from_ip_address)

| table token status user roles audience issued_at_date not_before_date expiration_date last_used_date
last_used_from_ip_address issuer issued_at_date identity_provider splunk_server

You can also find token-related setup information at:

| rest splunk_server_group=dmc_group_search_head /services/ admin/Token-auth/tokens_auth

An example alert you could use for expiring tokens, say those that are going to expire in the next 30 days:

| rest splunk_server_group=dmc_group_search_head /services/ authorization/tokens

| where ‘claims.exp’ < relative_time(now(),”+30d”)

Additionally, with the “not before date” (claims.nbr) entry, it would be possible to set up multiple future-date, even overlapping, tokens for the same user. So, for example, you could set up two tokens for an API user today–one starting today for the next 90 days and one that started on day 89 and extended 182 days. This would give you two tokens spanning six months that had a two-day overlap period. Now, set an alarm on your calendar on days 89 and 90 to, on one of those days, go into the source system using the token to send API calls to Splunk and swap out the old token for the new one. You’d have two days to get the swap out made and potentially no loss of service.

If you would like additional support with your authentication tokens in Splunk or any other Splunk issue please contact us right away.