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 a new installation of Splunk Enterprise. Before you can create and manage tokens, you must enable token authentication.

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:

• 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 Splunk Enterprise 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.

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 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, 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 configuration files

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

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 system, use this procedure. Expiration times that you specify in the token creation dialog override the default setting. You cannot perform this operation in 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.

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 later.

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

   
   Splunk Enterprise enables token authentication immediately, and there is no need to restart the instance.

Disable token authentication on a Splunk platform instance

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.

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 configuration files

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

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.

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.

Create, use, manage, and delete tokens

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

• Create tokens. See Create authentication tokens.
• Manage or delete tokens. See Manage or delete authentication tokens.
• Use tokens to authenticate. See Use 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.