Splunk® Enterprise

Securing the Splunk Platform

Acrobat logo Download manual as PDF

Acrobat logo Download topic as PDF

Enable or disable token authentication

You can enable token authentication at any time if your Splunk platform account has the appropriate permissions. Token authentication is off by default on the Splunk platform.

You can also disable token authentication at any time if you have enabled it and have the appropriate permissions. If token authentication is disabled, token users cannot authenticate into the instance, even if you have previously defined valid tokens.

Tokens retain their individual validity status regardless of whether token authentication is on or off, and when you re-enable token authentication after disabling it, holders of valid tokens can use them again.

Prerequisites for enabling or disabling token authentication

Before you can enable token authentication, you must satisfy the following requirements:

Splunk Cloud

  • You must configure your Splunk Cloud instance to use the SAML authentication scheme. Currently, Splunk supports using tokens only when Splunk Cloud uses SAML for authentication.
  • You must configure your Splunk Cloud instance to use a SAML identity provider (IdP) that supports Attribute Query Requests (AQR). Currently, Splunk supports using tokens in Splunk Cloud for the Microsoft Azure and Okta IdPs only. Those IdPs do not support AQR, but do have authentication extensions available. See Configure Splunk Cloud to use SAML for authentication tokens in the Splunk Cloud Admin Guide.
  • The account that you use to log into the Splunk platform must hold a role that has the edit_tokens_settings Splunk platform capability before you can turn token authentication on or off.

Splunk Enterprise

  • You must enable Transport Layer Security (TLS)/SSL on your Splunk platform instance. See About securing Splunk Enterprise with SSL for details.
  • You must confirm that you have enabled app key value store (KV Store). By default, KV store is enabled on search heads. See About app key value store in the Admin Manual for more information.
  • The Splunk platform instance where you want to enable token authentication must not operate in legacy mode, where Splunk Web operates as a separate process. If the Splunk platform is in legacy mode, token authentication does not run. See Start and Stop Splunk Enterprise in the Admin Manual for information on legacy mode.
  • The account that you use to log into the Splunk platform must hold a role that has the edit_tokens_settings Splunk platform capability before you can turn token authentication on or off.

Enable token authentication for a Splunk platform instance

You can enable token authentication by using Splunk Web, editing configuration files, or making a call to a Representational State Transfer (REST) endpoint.

At this time, you cannot use the Splunk CLI on Splunk Enterprise to enable or disable token authentication.

Enable token authentication using Splunk Web

When token authentication is off, the following message displays on the "Tokens" page in Splunk Web:

Token authentication is currently disabled
To enable token authentication, click Enable Token Authentication.

Perform this procedure on the instance where you want to enable token authentication.

  1. Log in to the Splunk platform instance as an administrator-level user, or a user that can manage tokens settings.

    You cannot use a token to log in to Splunk Web. You must provide a valid user name and password.

  2. After you log in successfully, in the system bar, select Settings > Tokens.
  3. Click Enable Token Authentication. The Splunk platform instance enables token authentication immediately, and there is no need to restart the instance.

Enable token authentication using REST

The curl command does not come standard on Windows PowerShell. Instead, you can use the Invoke_RestMethod PowerShell cmdlet on PowerShell versions 3.0 and higher.

  1. Open a shell prompt.
  2. Run the following command
    curl -k -u <splunk_username>:<password> -X POST https://<servername>:<port>/services/admin/token-auth/tokens_auth -d disabled=false

    The Splunk platform enables token authentication immediately. On Splunk Enterprise instances, there is no need to restart.

Enable token authentication using configuration files

Perform this procedure on the Splunk Enterprise instance where you want to enable token authentication. This option is not available on Splunk Cloud instances.

  1. Open a shell prompt or PowerShell window.
  2. Change to the $SPLUNK_HOME/etc/system/local directory.
  3. Use a text editor to open the authorize.conf file for editing.
  4. In the authorize.conf file, add the following lines of text:
    [tokens_auth]
    disabled = false
    
  5. Save the authorize.conf file and close it.
  6. Restart the Splunk platform.

Set a default relative token expiration time using configuration files

Optionally, to set a default relative time expiration for any tokens on the Splunk Enterprise instance, use this procedure. Expiration times that you specify in the token creation dialog override the default setting. You cannot perform this operation in Splunk Cloud or on Splunk Web, and you cannot set an expiration time in the past.

  1. Open a shell prompt or PowerShell window.
  2. Change to the $SPLUNK_HOME/etc/system/local directory.
  3. Use a text editor to open the authorize.conf file for editing.
  4. In the tokens_auth stanza, add the following line of text, substituting <relative time> with a string that represents an amount of time from the time that you create a token:
    expiration=<relative time>
    

    For example, if you want to specify a default expiration time of 5 days for a token after you create it, set <relative time> to +5d.

  5. Save the file and close it.
  6. Restart the Splunk platform.

See Time modifiers in the Search Reference manual for more information on time modifier syntax.

Disable token authentication on a Splunk platform instance

On Splunk Cloud instances, you can disable token authentication by using Splunk Web. On Splunk Enterprise instances, you can disable token authentication by using Splunk Web, editing configuration files, or making a call to a REST endpoint.

Disable token authentication using Splunk Web

Perform this procedure on the instance where you want to disable token authentication. You can use Splunk Web to disable token authentication on either Splunk Cloud or Splunk Enterprise instances

  1. Log in to the Splunk platform instance as a user that can edit token settings.

    You cannot use a token to log in to Splunk Web. You must provide a valid user name and password.

  2. After you log in, in the system bar, select Settings > Tokens.
  3. Click Disable Token Authentication. The instance disables token authentication immediately, and there is no need to restart the instance.

Disable token authentication using REST

The curl command does not come standard on Windows PowerShell. Instead, you can use the Invoke_RestMethod PowerShell cmdlet.

  1. Open a shell prompt.
  2. Run the following command
    curl -k -u <splunk_username>:<password> -X POST https://<servername>:<port>/services/admin/token-auth/tokens_auth -d disabled=true

    The instance disables token authentication immediately, and there is no need to restart the instance.

Disable token authentication using configuration files

Perform this procedure on the Splunk Enterprise instance where you want to disable token authentication. This option is not available for Splunk Cloud instances.

  1. Open a shell prompt or PowerShell window.
  2. Change to the $SPLUNK_HOME/etc/system/local directory.
  3. Use a text editor to open the authorize.conf file.
  4. In the authorize.conf file, edit the following lines of text:
    [tokens_auth]
    disabled = true
    
  5. Save the authorize.conf file and close it.
  6. Restart Splunk Enterprise.

Create, use, manage, and delete tokens

After you enable token authentication, you can do the following with authentication tokens:

If you disable token authentication, any tokens that are on the instance become inaccessible immediately, and you must enable token authentication again to restore access to tokens that are valid.

Last modified on 27 August, 2020
PREVIOUS
Set up authentication with tokens
  NEXT
Create authentication tokens

This documentation applies to the following versions of Splunk® Enterprise: 8.1.0


Was this documentation topic helpful?

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