Create authentication tokens

Authentication tokens let users of Splunk platform environments access Representational State Transfer (REST) endpoint resources or use the Splunk CLI in Splunk Enterprise environments. You can create tokens in Splunk Web or use an API call to a REST endpoint on the instance where the tokens are to reside.

At this time, you can not use the CLI to create authentication tokens.

Prerequisites for token creation

• You must enable token authentication. See Enable or disable token authentication.
• Your Splunk platform account must satisfy at least one of the following criteria before you can create authentication tokens:
  • If you want to create tokens for yourself, your account must hold a role that has the edit_tokens_own capability.
  • If you want to create tokens for any user on the instance, your account must hold a role that has the edit_tokens_all capability. See About defining roles with capabilities for additional information on Splunk platform capabilities.
• For static and ephemeral tokens, you must be prepared to save or share the token immediately after you create it. You only have one opportunity to do so, and you cannot recall the full token after you close the "New token" dialog box.

Supported user types for token creation

You can only create tokens for users that exist on the Splunk platform instance where you create the token. The users that exist on the instance depend on the authentication scheme that the instances uses:

• Native Splunk authentication: Where user accounts exist only on that specific instance
• Authentication through a single-sign-on (SSO) scheme that uses Security Assertion Markup Language (SAML)
• Authentication through a Lightweight Directory Access Protocol (LDAP) server, on Splunk Enterprise instances only

The Splunk platform confirms that the user you entered exists and raises an error message if the user does not exist.

Considerations for creating tokens on instances that use the LDAP authentication scheme

When you create a token on an instance that uses the LDAP authentication scheme, the LDAP server treats that creation as a login for LDAP caching purposes. The Splunk platform connects to the LDAP server to validate the user and any associated LDAP groups.

Considerations for creating tokens on instances that use the SAML authentication scheme

You might need to perform additional tasks before you can create tokens for users who use the SAML authentication scheme to access Splunk platform resources. This need depends on the identity provider (IdP) that the Splunk platform instance connects to with SAML.

• On Splunk Cloud Platform instances, the authentication scheme only supports the Azure and Okta IdPs.
• If the SAML IdP supports Attribute Query Requests (AQRs), then you do not need to perform any additional work, and tokens that you create will be immediately usable by users who access a Splunk platform instance that uses the SAML scheme.
• If the SAML IdP does not support AQRs, then you must configure authentication extensions that interface with the IdP. See Configure SAML authentication extensions for additional information and instructions.

Save or share the token immediately after you create it

When you create either a static or an ephemeral authentication token, for security purposes, you only have one opportunity to see the entire token. After you specify a user and audience for the token and click "Create", the token appears as a string of text in the "New Token" dialog box. You must copy this token and paste it into another document such as a text file before closing the "New Token" dialog box.

Token users must have the full token to authenticate without credentials. If you close the Create Token dialog box before saving the full token somewhere, then you must create a new token, as you cannot recover the one that you previously created.

Configure token expiry and "Not Before" settings

When you create a new static token, you can set whether or not the token expires, and whether or not it is valid before a certain time. Both of these choices are optional, which means that you can configure a token to last forever and be available for use immediately.

Ephemeral and interactive tokens have different restrictions on token expiry:

• Ephemeral tokens can only last up to six hours ("+6h") after you create them.
• Interactive tokens can only last up to one hour, and you cannot configure them.

If you want a static authentication token to expire, you must set an expiry date and time for it. You can set an absolute time, such as "Friday, February 1, 2019 at 10:30", or you can set a relative time, which is a certain period of time from the current time, for example, three days from now, a week from now, or two months from now. Expiration times can never be in the past.

If you do not set an expiration time, then the Splunk platform uses the default global expiration time, which is 30 days from when you issued it ("+30d"). You can change this default. See Set a default relative token expiration time using configuration files.

If you do not want the token to be valid immediately, you can set a "Not Before" time for it. This means that even though you create the token now, it cannot be used until the Not Before time has passed. For example, if today is Friday, January 25, 2019, and you do not want the token to be used until the following Friday, you can set an absolute time of Friday, February 1, 2019 at 00:00, or a relative time of +7d (7 days from now). The "Not before" time can never be in the past, nor can it be after the expiration time.

Specify relative time versus absolute time for validity start and expiration times

When you specify expiration and "Not before" times, you can specify an absolute time or a relative time for static tokens. You can specify either type of time format for either type of time.

You indicate the absolute time by specifying a date and time, including year, month, day, hour, minute, and second. In Splunk Web, you can use the date picker to chose the appropriate date and time, or you can type it in. If you type it in, you must specify it in the following format:

YYYY-MM-DDTHH:MM:SS[+HH:MM]

The T between DD and HH is the actual letter T, and stands for "time". The +HH:MM represents the time zone that you want to use, and is optional.

You indicate the relative time by specifying a string that represents an amount of time beyond the current time. In general, specify the following format:

+<number>[s|h|m|d]@[s|h|m|d][+<number>[s|h|m|d]]

The letters s, m, h, and d are identifiers that represent seconds, minutes, hours, and days, respectively. You can also use the following words as identifiers:

• seconds, secs, sec
• minutes, mins, min
• hours, hrs, hr
• days, day

If you want to round down to a certain time, you can include the @ modifier in the time string. For example, if you want a token to expire 10 days from now at the beginning of the day, you can specify +10d@d. This string reads as "10 days from now, on the day."

You can also concatenate different identifiers. For example, to have a token expire 15 days and 5 hours, on the hour, from now, you can specify +15d+5h@h.

Use Splunk Web to create authentication tokens

You can create static tokens with Splunk Web. To create ephemeral or interactive tokens, see "Use REST to create authentication tokens" later in this topic.

1. in the system bar, click Settings > Tokens.
2. Click New Token. The "New Token" dialog box appears.

   If you see a message that says you have not enabled token authentication, see Enable token authorization for instructions on how to enable token authorization.

3. In the "New Token" dialog, enter the Splunk platform user that you want to create the token for in the User field.
4. Enter a short description of the token purpose in the Audience field.
5. (Optional) In the Expiration drop down list, select one of Absolute Time or Relative Time. This selection determines what to enter in the text field below the drop down list.
1. If you selected Absolute Time, then two text fields appear under the drop down.
1. Enter a valid date into the first field. You can also click the field to select a date from a pop-up calendar.
2. Enter a valid 24-hour time in the second field.
2. Otherwise, one text field appears under the drop down list.
1. Enter a string that represents how long after the current time you want the token to remain valid. For example, if you want the token to expire 10 days from now, enter +10d into this field.
6. (Optional) In the Not Before drop-down, select one of Absolute Time or Relative Time.
7. Repeat the step you used for the "Expiration" control. The "Not before" time can neither be in the past, nor can it be later than the "Expiration" time.
8. Click Create. The New Token window updates the Token field to show you the token that has been generated.
9. Select all of the token text in the field. Depending on your operating system and browser, you can click on the "Token" field, then either triple click or press Ctrl-A or Command-A on your keyboard.

   Confirm that you have selected all of the token text. There are no further opportunities to see the whole token after you close the window.

10. Copy the text from the Token field.
11. Paste the token into a text file, e-mail, or other form of communication to the person you have authorized to use the token.

    Confirm that you share the token only with those who you have authorized to use it. Anybody who has the full token can use it to authenticate.

12. Click Close.
13. Share the token with its authorized user.

Use REST to create authentication tokens

You can also create authentication tokens by making an API call to the services/authorization/tokens REST endpoint on a Splunk platform instance with the cURL web transfer tool. The cURL tool is not available on Windows PowerShell; instead you can use the Invoke-RestMethod cmdlet on PowerShell version 3.0 and higher.

If you have an existing valid static or ephemeral token, you can use it rather than user credentials to authenticate when creating a new token. The user account that is associated with the token must satisfy the previously-described criteria for token creation.

You cannot configure interactive tokens in any way.

See "Example API calls" later in this topic for examples on token creation.

1. Open a shell prompt.
2. Generate the token.
   

   curl [-u <username>:<password>|-H "Authorization: Bearer <existing_token>"] -X POST https://<servername>:<management_port>/services/authorization/tokens?output_mode=json --data name=<token_user> --data audience=<audience> [--data type=static|ephemeral|interactive] [--data-urlencode expires_on=[<relative_time>|<absolute_time>]] [--data-urlencode not_before=[<relative_time>|<absolute_time>]]
   

   
   See the syntax variable table that follows this procedure for a description of each variable in the syntax.
3. In the output that appears, look for the "token":" string. The text immediately after this string, up to the next " character, is the token.
4. Share the whole token with the person who is to use it.
5. Close the shell prompt.

Sample output of token creation

Following is sample output from a REST call to generate a token.

{"links":{"create":"/services/authorization/tokens/_new"},"origin":"https://mysplunk.com:8089/services/authorization/tokens","updated":"2019-03-07T22:55:46+00:00","generator":{"build":"85dd8eb9bcda","version":"7.3.0"},"entry":[{"name":"tokens","id":"https://mysplunk.com:8089/services/authorization/tokens/tokens","updated":"1970-01-01T00:00:00+00:00","links":{"alternate":"/services/authorization/tokens/tokens","list":"/services/authorization/tokens/tokens","edit":"/services/authorization/tokens/tokens","remove":"/services/authorization/tokens/tokens"},"author":"system","acl":{"app":"","can_list":true,"can_write":true,"modifiable":false,"owner":"system","perms":{"read":["admin","power","splunk-system-role","user"],"write":["admin","splunk-system-role"]},"removable":false,"sharing":"system"},"content":{"eai:acl":null,"id":"ca08a6842d3ec21b4d18549754e8e8d77a392d7e17de28cfdc71b78005a16e78","token":"eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnIjoiSFM1MTIiLCJ2ZXIiOiJ2MSIsInR0eXAiOiJzdGF0aWMifQ.eyJpc3MiOiJhZG1pbiBmcm9tIHNvMSIsInN1YiI6ImFkbWluIiwiYXVkIjoiVG9rZW50b3duIiwiaWRwIjoic3BsdW5rIiwianRpIjoiY2EwOGE2ODQyZDNlYzIxYjRkMTg1NDk3NTRlOGU4ZDc3YTM5MmQ3ZTE3ZGUyOGNmZGM3MWI3ODAwNWExNmU3OCIsImlhdCI6MTU1MTk5OTM0NiwiZXhwIjowLCJuYnIiOjE1NTE5OTkzNDZ9.RrZxe89qchfEtrEnG1PjTmJzO_JTtPX8xqSiSunYGylupG114KujO3-E88TtM-Tf51qtVpJydR3JSJpPfaf17w"}}],"paging":{"total":1,"perPage":30,"offset":0},"messages":[]}

The token is embedded in the output:

eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnIjoiSFM1MTIiLCJ2ZXIiOiJ2MSIsInR0eXAiOiJzdGF0aWMifQ.eyJpc3MiOiJhZG1pbiBmcm9tIHNvMSIsInN1YiI6ImFkbWluIiwiYXVkIjoiVG9rZW50b3duIiwiaWRwIjoic3BsdW5rIiwianRpIjoiY2EwOGE2ODQyZDNlYzIxYjRkMTg1NDk3NTRlOGU4ZDc3YTM5MmQ3ZTE3ZGUyOGNmZGM3MWI3ODAwNWExNmU3OCIsImlhdCI6MTU1MTk5OTM0NiwiZXhwIjowLCJuYnIiOjE1NTE5OTkzNDZ9.RrZxe89qchfEtrEnG1PjTmJzO_JTtPX8xqSiSunYGylupG114KujO3-E88TtM-Tf51qtVpJydR3JSJpPfaf17w

Syntax variable table

Determine the meaning of the variables used in the previous syntax using the following table. You can use these variables to configure static and ephemeral tokens. When you create interactive tokens, only the type variable is valid.

Variable	Meaning	Required?
username	The user that is creating the new token	If using a token to perform the action: No Otherwise: Yes
password	The password for the user that is creating the new token	If using a token to perform the action: No Otherwise: Yes
existing_token	A valid, existing token that has already been issued to the user that is creating the new token	If using a token to perform the action: Yes Othewise: No
servername	The Splunk platform instance where the token is to reside	Yes
management_port	The management port of the Splunk instance. Is usually 8089 but can be different depending on how the instance is configured.	Yes
token_user	The user that is to receive the new token. This user must already exist on the Splunk instance.	Yes
audience	The purpose for which the token is being created. The Splunk platform uses this to let you group tokens that have been assigned to different users.	Yes
type	The kind of token to create. Can be one of static, ephemeral, or interactive. Static tokens can have an unlimited expiry, and have backing in app key value store (KV store). Ephemeral tokens do not have backing in KV store, and can last up to 6 hours after you create them. Interactive tokens can last up to one hour. This is the only available argument if you want to create an interactive token.	No
expires_on	An argument that specifies when a token expires. Expired tokens are invalid and authorization requests that contain them are rejected.	No
not_before	An argument that specifies a future time when the token is to become valid. "Not before" tokens are invalid until the "Not before" time has passed, and authorization requests that occur before that time with these kinds of tokens are rejected.	No
absolute_time	A string that represents a specific date and time. Must be in the format YYYY-MM-DDTHH:MM:SS[+HH:MM] Include the time zone offset when able. For example: 2019-02-09T07:35:00+07:00	No, uses default expiration time if not included
relative_time	A string that represents a period of time past the current time. Must be in the format +<number>[s][m][h][d]. For example, +90m means 90 minutes from now, +15d means 15 days from now.	No

Example API calls for creating tokens

The following example is of an administrator using their credentials to create a token for user "jdoe" with an expiration of 30 days from the current time:

curl -k -u  admin:Ch#ng3d! -X POST https://splunk1.server.com:8089/services/authorization/tokens?output_mode=json --data name=jdoe  --data audience=Users --data-urlencode expires_on=+30d 

The following example is of an admin using a valid token to create another token for user "sallyjane" for the purpose "Managers" that uses the default token expiration time.

curl -X POST -H "Authorization: Bearer ejy23898hjkl2QJkl..." https://mysplunk.com:8089/services/authorization/tokens?output_mode=json --data name=sallyjane --data audience=Managers

The following example is of an admin creating a token for user "bobd" on February 5, 2019. The admin wants the token to become valid on March 1, 2019 at midnight and expire around 60 days after that. The instance uses a nonstandard management port 44514:

curl -k -u admin:Ch#ng3d! -X POST https://mysplunk.com:44514/services/authorization/tokens?output_mode=json --data name=bobd --data audience=Accountants --data-urlencode not_before=2019-03-01T00:00:00 --data-urlencode expires_on=+85d

The following example is of an admin creating a token for user "steveg" for the purpose "Operations". The token is not to become valid before 10 days, on the day, from the current time, and should expire 45 days, on the day, plus 2 hours, on the hour, after it becomes valid. The instance uses a nonstandard management port 38182:

curl -k -u admin:Ch#ng3d! -X POST https://mysplunk.com:38182/services/authorization/tokens?output_mode=json --data name=steveg --data audience=Operations --data-urlencode not_before=+10d@d --data-urlencode expires_on=+55d@d+2h@h

Use, manage, and delete tokens

After you created tokens, you can do the following:

• Manage or delete tokens. See Manage or delete authentication tokens.
• Use tokens to authenticate. See Use authentication tokens.