Manage or delete authentication tokens

Before you can manage or delete authentication tokens, you must have enabled token authentication and created at least one token. If you have not enabled token authentication, see Enable token authorization for instructions.

You can manage authentication tokens that you have created in Splunk Web or by using Representational State Transfer (REST) calls. You can view the following information on each token:

• Token ID
• Token issuer (Issued by, comprised of the Splunk platform user who created the token and the hostname on which the token was created)
• Token owner (Username or subject) and audience
• Token validity ranges including Not before and expiration times
• The Identity Provider (the authentication scheme that was in use when the administrator created the token)
• When the token was last used
• The IP address that last used the token

Owing to security reasons, you cannot do any of the following with tokens:

• Reassign token ownership. A token is assigned to a single user and audience at all times.
• Change a token audience.
• Change the expiration of a token.
• Change the "Not before" validity of a token.
• Renew an expired token. Users of expired tokens lose access immediately.

If you need to change any of these properties of a token, then you must create a new token with the updated settings, share the token with the user, and, optionally, disable or delete the old tokens.

Considerations for managing authentication tokens on instances that use LDAP for authentication

There are some caveats for using and managing authentication tokens on Splunk platform instances that use the Lightweight Directory Access Protocol (LDAP) to authenticate.

• The LDAP cache controls how long Splunk platform instances that use LDAP retain information from LDAP queries. By default, the LDAP cache never expires. You must either reload the authentication configuration or restart the Splunk platform instance to clear the LDAP cache.
• When you delete a user from an LDAP provider, delete any tokens that are associated with the deleted user as well. Tokens can remain valid until the user entry in the LDAP cache expires.
• While tokens that are associated with a deleted user no longer work for authentication, if you create a new user with the same username, the LDAP provider can re-associate those tokens with the new user, potentially causing unauthorized access.

Considerations for managing authentication tokens on instances that use SAML for authentication

There are some caveats for for using and managing authentication tokens on Splunk platform instances that use Security Assertion Markup Language (SAML) as an authentication scheme:

• When you delete a user on a SAML-complaint identity provider, the user remains in the user list until you reload the authentication configuration. However, the user cannot log in to the instance, and any saved searches that it owns no longer function.

Manage authentication tokens in Splunk Web

You can perform the following actions on the Tokens page:

• Create new tokens. See Create authentication tokens for the procedure.
• Enable or disable existing tokens. See "Enable or disable authentication tokens" later in this topic.
• Delete existing tokens. See "Delete authentication tokens" later in this topic.

While you can view token IDs, there is no way to view a token in its entirety. Token users require the full token before they can use it. You cannot give the token ID to a user to use as a token if they have forgotten or misplaced the token. You must either provide the entire token, if it is available to you, or create a new one.

View token information

The Tokens page lists information on the tokens that you have created. Each token is represented by its token ID.

It is not possible to view a full token on this page. You can only view a full token immediately after you create it in the "New Token" dialog box, and before you close that dialog box.

1. From the system bar, click Settings > Tokens. The Tokens page appears.
2. (Optional) Use the Search text box to locate a token by one of the following fields:
   • ID
   • Owner
   • Issuer
   • Audience
   • Status: "Enabled" or "Disabled"
   • Identity provider
3. (Optional) Hover the mouse over a token ID to see a tooltip that shows the entire token ID.
4. (Optional) Select the > button to expand a token entry and show detailed information about a token:
   • Token ID
   • Token issuer and issuing workstation
   • "Not before" validity time
   • The Splunk authentication scheme that this token uses
   • The last IP address that used the token successfully

The instance updates the last seen IP address and time whenever you use a token. There is a period of up to two minutes after use, where usage information is cached, and Splunk Web does not show multiple uses during that period.

Enable or disable existing tokens

When you disable a token, users who use the token lose access immediately. You must enable the token again for users to regain access while it is valid.

Tokens that have not reached their "Not Before" validity time remain unusable until that time has passed, regardless of the changes that you make with this procedure.

1. From the system bar, click Settings > Tokens. The tokens page appears.
2. (Optional) Use the Search text box to locate a token. The page updates to show only tokens that match the text you entered.
3. Locate the token whose status you want to change.
4. In the Actions column for the token, if a token is enabled, click the Disable link to disable the token.
   1. In the Disable Token dialog box that appears, click Disable.
5. Otherwise, if a token is disabled, click the Enable link to enable the token.
   1. In the Enable Token dialog box that appears, click Enable.
6. Repeat these actions for additional tokens whose status you want to change. You can use the Search text box to update the list of tokens.

Delete an existing token

When you delete a token, users who use the token lose access when the cache for the token expires, up to two minutes after token revocation. You must reissue a new token or standard credentials to grant access to the user that had the previous token.

1. From the system bar, click Settings > Tokens. The tokens page appears.
2. (Optional) Use the Search text box to locate a token. The page updates to show only tokens that match the text you entered.
3. Locate the token that you want to delete.
4. In the Actions column for the token, click the Delete link to disable the token.
   1. In the Delete Token dialog box that appears, click Delete.
5. Repeat these actions for additional tokens that you want to delete. You can use the Search text box to update the list of tokens.

Manage authentication tokens using REST

You can use either a REST client or the cURL command-line utility to generate REST requests to your Splunk Enterprise instance. All of the following command examples use cURL. In addition to using standard credentials to manage tokens, you can also use a valid token to perform these requests.

1. Open a shell prompt.
2. From the prompt, run the appropriate curl command, based on how you want to authenticate.
   1. To authenticate with standard credentials, provide them as part of the command: curl -k -u <username>:<password> ...
   2. To authenticate with a token, provide the token in an authorization header: curl -k -H "Authorization: Bearer <valid_token> ..."
3. Review the output to confirm that the command completed successfully.
4. (Optional) Perform additional requests, depending on the endpoints you are using and the tasks you want to complete.

View all existing tokens

curl -k -u <username>:<password> -X GET https://<server>:<management_port>/services/authorization/tokens

This command generates the following output:

<?xml version="1.0" encoding="UTF-8"?>
...
<feed xmlns="https://www.w3.org/2005/Atom" xmlns:s="https://dev.splunk.com/ns/rest" xmlns:opensearch="https://a9.com/-/spec/opensearch/1.1/">
  <title>tokens</title>
  <id>https://10.224.61.92:43705/services/authorization/tokens</id>
  <updated>2019-02-19T22:29:33+00:00</updated>
 ...
  <author>
    <name>Splunk</name>
  </author>
 ...
  <entry>
    <title>45a2b05b2cc737e4ce6387092a00b8fcbb7502960dd651a0ab16129161495ad6</title>   <id>https://10.224.61.92:43705/services/authorization/tokens/45a2b05b2cc737e4ce6387092a00b8fcbb7502960dd651a0ab16129161495ad6</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/services/authorization/tokens/45a2b05b2cc737e4ce6387092a00b8fcbb7502960dd651a0ab16129161495ad6" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
...
    <content type="text/xml">
      <s:dict>
        <s:key name="claims">
          <s:dict>
            <s:key name="aud">Tokentown</s:key>
            <s:key name="exp">0</s:key>
            <s:key name="iat">1550614409</s:key>
            <s:key name="idp">splunk</s:key>
            <s:key name="iss">admin from so1</s:key>
            <s:key name="nbr">1550614409</s:key>
            <s:key name="roles">
              <s:list>
                <s:item>*</s:item>
              </s:list>
            </s:key>
            <s:key name="sub">admin</s:key>
          </s:dict>
        </s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="headers">
          <s:dict>
            <s:key name="alg">HS512</s:key>
            <s:key name="kid">splunk.secret</s:key>
            <s:key name="ttyp">static</s:key>
            <s:key name="ver">v1</s:key>
          </s:dict>
        </s:key>
        <s:key name="lastUsed">1550615373</s:key>
        <s:key name="lastUsedIp">10.32.34.55</s:key>
        <s:key name="status">enabled</s:key>
      </s:dict>
    </content>
  </entry>
  <entry>
    <title>c2aa8106ec905dd7ac6c5227725730b2d25b986d0983f81b0972de31a025aaca</title>
    <id>https://10.224.61.92:43705/services/authorization/tokens/c2aa8106ec905dd7ac6c5227725730b2d25b986d0983f81b0972de31a025aaca</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
...
  </entry>
</feed>

View existing tokens by user

curl -k -u <username>:<password> -X GET https://<server>:<management_port>/services/authorization/tokens?username=<token_user>

View existing tokens by status

curl -k -u <username>:<password> -X GET https://<server>:<management_port>/services/authorization/tokens?status=<enabled|disabled>

View information on a single existing token

curl -k -u <username>:<password> -X GET https://<server>:<management_port>/services/authorization/tokens -d id=<token_id>

Disable an existing, enabled token

If you disable the token that you are actively using, there is no warning or ability to cancel or undo the change. You must then either log in with standard credentials to re-enable it, or use another token if it is available.

curl -k -u <username>:<password> -X POST https://<server>:<management_port>/services/authorization/tokens/<token_user> -d id=<token_id> -d status=disabled

Enable an existing, disabled token

curl -k -u <username>:<password> -X POST https://<server>:<management_port>/services/authorization/tokens/<token_user> -d id=<token_id> -d status=enabled

Delete an existing token

If you delete the token that you are actively using, there is no warning or ability to cancel or undo the change. You must then either log in with standard credentials to create a new one, or use another token if it is available.

curl -k -u <username>:<password> -X DELETE https://<server>:<management_port>/services/authorization/tokens/<token_user> -d id=<token_id>

This command generates the following output:

<?xml version="1.0" encoding="UTF-8"?>
...
<feed xmlns="https://www.w3.org/2005/Atom" xmlns:s="https://dev.splunk.com/ns/rest" xmlns:opensearch="https://a9.com/-/spec/opensearch/1.1/">
  <title>tokens</title>
  <id>https://10.224.61.92:43705/services/authorization/tokens</id>
  <updated>2019-02-19T23:04:31+00:00</updated>
  <generator build="71b3ebc05ef9" version="7.3.0"/>
  <author>
    <name>Splunk</name>
  </author>
...
  <s:messages>
    <s:msg type="INFO">Token(s), removed.</s:msg>
  </s:messages>
</feed>