Manage authentication tokens in Splunk Cloud Platform
The ACS API requires a JSON Web Token (JWT) to authenticate ACS endpoint requests. You can use the ACS API itself to create these authentication tokens, which facilitates automated workflows that integrate ACS API requests. For example, you can set up a fully automated CI/CD pipeline for private app installation that includes the creation of the required token.
Requirements
To manage authentication tokens using the ACS API:
- Your role must have the capabilities required to access the ACS API endpoint. The
sc_admin
role has all required capabilities by default. For a list of required capabilities, see Manage ACS API access with capabilities. - You must have Splunk Cloud Platform version 8.0.2007 or higher.
- Your deployment must have one or more separate search heads or a search head cluster. ACS is not supported on single instance deployments.
- You must provide a valid username and password for basic authentication.
The ACS API does not support authentication token management on FedRAMP deployments.
Set up the ACS API
Before using the ACS API, you must download the ACS Open API 3.0 specification, which includes the parameters, codes, and other data you need to work with the ACS API. You must also create an authentication token for use with ACS endpoint requests. You can create this token using the Splunk Web UI or using the ACS API itself. For details on how to set up the ACS API, see Set up the ACS API.
Manage authentication tokens using the ACS API
You can use the ACS API to view existing tokens, create new tokens, view individual tokens, and delete tokens.
Authentication tokens are valid only on the search head on which you create them. ACS does not replicate tokens across the search tier. By default ACS token operations apply to the first standard search head (sh1) or search head cluster (shc1) of your Splunk Cloud Platform deployment.
To create and manage tokens on additional search heads or premium search heads, you must target the specific search head on which you want to perform the ACS token operation. For more information, see Target a specific search head for ACS operations.
View existing authentication tokens
To list existing JWT authentication tokens in your environment, send an HTTP GET request to the following endpoint:
admin.splunk.com/{stack}/adminconfig/v2/tokens
For example:
curl 'https://admin.splunk.com/{stack}/adminconfig/v2/tokens/' \ --header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...'
The request returns information about each token, including token id, user, audience, status, and expiration date. For example:
[ { "id": "d9637736177efc773ec8c5c04efcc2e19859cd852af00689ef81bf9e809364a8", "user": "admin", "audience": "acs-test", "status": "enabled", "expiresOn": "2021-11-19T00:34:46Z", "notBefore": "2021-10-20T00:34:46Z", "lastUsed": "2021-10-20T03:52:53Z", "lastUsedIP": "50.216.96.2" }, { "id": "a9637736177efc773ec8c5c04efcc2e19859cd852af00689ef81bf9e80936984", "user": "admin", "audience": "acs-test2", "status": "enabled", "expiresOn": "2022-05-19T00:34:46Z", "notBefore": "2022-04-20T00:34:46Z", "lastUsed": "2022-04-24T03:52:53Z", "lastUsedIP": "45.216.96.2" } ]
By default, the list tokens request returns a maximum count of 30 tokens. To change the count, you can specify a count
value up to a maximum of 100. A count
value of 0 lists all authentication tokens.
If you have more than 100 tokens, you can specify an offset
value to list additional tokens. For example, to list tokens 100-200, specify an offset
value of 100. For example:
curl 'https://admin.splunk.com/{stack}/adminconfig/v2/tokens?offset=100&count=100'
Create a new authentication token
To create a new JWT authentication token, send an HTTP POST request to the tokens
endpoint.
You must provide the username and password of your Splunk Cloud Platform deployment with the POST request to enable token authentication. You can do so by specifying your credentials in the request URL. You must also specify the user
and audience
parameters in the request body.
You can optionally specify the expiresOn
parameter in either relative time (+<number>[s][m][h][d]) or absolute time (YYYY-MM-DDTHH:MM:SS[+HH:MM]). If you do not specify expiresOn
in your request, ACS assigns a default value of 30 days.
For example:
curl -u username:password -X POST 'https://admin.splunk.com/keziabutterfinger/adminconfig/v2/tokens' \ --header 'Content-Type: application/json' \ --data-raw '{ "user" : "admin", "audience" : "acs-test", "expiresOn" : "+100d" }'
The request output shows the token ID and the full token value, as shown:
{ "user": "admin", "audience": "acs-test", "id": "0c1daac93fd01bc50cfe8ed938ce401bc168a8730c1c9e2f343671541e759fbf", "token": "eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...", "status": "enabled", "expiresOn": "2021-12-16T21:37:11Z", "notBefore": "2021-11-16T21:37:11Z"
You can optionally specify username:password
as a b64 encoded string using a basic authentication header. For example: --header 'Authorization: Basic a2V6aWE6a2V6aWF0ZXN0'
.
If you do not specify password
in the request URL, ACS prompts you for the password associated with the username
. If you do not specify user
or audience
in the request body, ACS returns a 400 error. Possible error responses include:
{ "code": "400-bad-request", "message": "expires_on argument is in an invalid format." } { "code": "400-bad-request", "message": "audience must be sent in the request body" } { "code": "400-bad-request", "message": "user must be sent in the request body" } { "code": "401-unauthorized", "message": "call not properly authenticated" }
ACS returns the token value once only in the initial POST request that creates the token. Subsequent GET requests to view individual tokens do not return the token value. Make sure to save the token in a secure location.
For endpoint details, see tokens in the ACS endpoint reference.
Create an ephemeral authentication token
The ACS tokens
endpoint supports an optional type
request parameter, which lets you create an ephemeral JWT token that expires by default after 6 hours. Ephemeral tokens are ideal for use cases in which you do not want to maintain long-lived credentials, such as initiating an automated CI/CD pipeline, or when working with contractors or third-parties that need only temporary access to a deployment.
You can specify a type
value of either "static" or "ephemeral". If not specified, the type
value defaults to "static".
While ephemeral tokens have a default expiration of 6 hours, you can use the expiresOn
parameter to specify a value of less than 6 hours for the ephemeral token, but not greater than 6 hours.
To create an ephemeral token using the ACS API, send an HTTP POST request to the tokens
endpoint, specifying "ephemeral" as the type
value in the request body. You must also specify user
and audience
parameter values in the request body, and provide the username and password of your Splunk Cloud Platform deployment in the request URL. For example:
curl -u username:password -X POST 'https://admin.splunk.com/<stack name>/adminconfig/v2/tokens' \ 2--header 'Content-Type: application/json' \ 3--data-raw '{ 4 "user": "blah", 5 "audience": "test", 6 "type": "ephemeral" 7}'
The request output shows the token ID and the full token value, along with the expiresOn
value for the ephemeral token. For example:
{ "id": "e4a4514f1cc8d3103393e9f9521d0b92fada2464d9f0be2dd6753f7488ffed02", "token": "eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...", "expiresOn": "+6h" }
You cannot list ephemeral tokens with a GET request or delete them. You can only create ephemeral tokens and use them until they automatically expire.
Specifying a type
value is optional. There is no difference between specifying "type": "static"
in the request body and specifying no type parameter at all.
For endpoint details, see tokens in the ACS endpoint reference.
View individual tokens
To describe an individual token, send an HTTP GET request to the tokens/{id}
endpoint, specifying the token ID that you received when you created the token. For example:
curl 'https://admin.splunk.com/important-iguana-u5q/adminconfig/v2/tokens/55ee3d1c199645c330d28dcd9fa50bc6e9f74154c3d1c3d31229b6e78be77ed7' \ --header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi…'
The authorization token that you use for the request does not have to be the token associated with the {id}.
The request returns token details, including time shown in UTC for the expiresOn
, notBefore
, and lastUsed
parameters. For example:
{ "id": "d9637736177efc773ec8c5c04efcc2e19859cd852af00689ef81bf9e809364a8", "user": "admin", "audience": "acs-test", "status": "enabled", "expiresOn": "2021-11-19T00:34:46Z", "notBefore": "2021-10-20T00:34:46Z", "lastUsed": "2021-10-20T03:52:53Z", "lastUsedIP": "50.216.96.2" }
For endpoint details, see tokens/{id} in the ACS endpoint reference.
Delete token
To delete a token, send an HTTP DELETE request to the tokens/{id}
endpoint, specifying the token ID of the token you want to delete. For example:
curl -X DELETE 'https://admin.splunk.com/important-iguana-u5q/adminconfig/v2/tokens/55ee3d1c199645c330d28dcd9fa50bc6e9f74154c3d1c3d31229b6e78be77ed7' \ --header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...'
The authorization token that you use for the request does not have to be the token associated with the {id}.
For endpoint details, see tokens/{id} in the ACS endpoint reference.
Manage app permissions in Splunk Cloud Platform | Manage HTTP Event Collector (HEC) tokens in Splunk Cloud Platform |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403, 9.2.2406 (latest FedRAMP release)
Feedback submitted, thanks!