BookmarkSubscribeRSS Feed

SAS Viya CLI Token Expiry

Started ‎12-06-2022 by
Modified ‎12-06-2022 by
Views 2,600

Throughout the last year leading up to the SAS Viya Stable 2022.10 release the default token lifetimes for SAS Viya have been changing. With the SAS Viya 2022.10 Stable release the Access Token now has a default lifetime of 1 hour while the Refresh Token has a default lifetime of 90 days. It should be noted that the current SAS Viya 2022.09 LTS release still has a default lifetime for the Access Token of 4 hours, while the Refresh Token lifetime is 90 days. Refresh Tokens, as we will explore, are revokable so they can be long lived. Whereas the Access Tokens are not revokable and so they have a much shorter lifetime.


Given these lifetime values for the tokens I wanted to discuss some implications for the SAS Viya CLI, how tokens can be revoked and the implications for any custom clients of SAS Logon Manager. Previously, Edoardo Riva has discussed Tuning the authentication timeout for long-running jobs where he discusses the implications for situations where clients have long-running sessions that try to use expired Access Tokens – and obviously fail.


Types of Tokens


As we have stated above there are two types of tokens generated by SAS Logon Manager. The Access Token is used to access the different SAS Viya services and the Refresh Token, if requested, can be used to obtain a new Access Token. Most of the time when using the SAS Viya web applications, you will not need to be concerned about the SAS Logon Manager generated tokens. Since the tokens are requested and used seamlessly by the various SAS Viya web applications. The tokens are never exposed to the end-user’s browser and the end-user never has direct access to their tokens.


However, there are other cases where the end-user does have access to their tokens. This could be when leveraging the supported third-party programming languages such as Java, Python, or Lua to interact with either SAS Cloud Analytic Services REST API or other SAS Viya REST APIs. Or when using the SAS Viya CLI. The SAS Viya CLI will place the Access Token and Refresh Token in a credentials.json file within the user’s home directory. On Linux this would be ~/.sas/credentials.json and for example would contain:


  "Default": {
    "access-token": "eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0.
    "expiry": "2022-11-28T14:43:20Z",
    "refresh-token": "642db5db07e140bbb19262793b0f3c06-r"


In this output you can see that authenticating with the SAS Viya CLI has obtained the Access Token and Refresh Token. The Access Token is a signed JSON Web Token while, in this case, the Refresh Token is an opaque token. With the SAS Viya 2022.09 Stable release the SAS Viya CLI started to use opaque tokens for the Refresh Token. Also note the "-r" at the end of the Refresh Token, this means that the Refresh Token can be revoked. Specifically, when you issue the command sas-viya auth logout the SAS Viya CLI will revoke the existing Refresh Token and remove the contents of the credentials.json file. This way even if someone has managed to obtain a copy of the Refresh Token it cannot be abused once the logout command is issued.


The same information can be viewed in a nicer format using the SAS Viya CLI itself. The command sas-viya profile show will display essentially the same information, as shown here:


Current settings for the [Default] profile:
Setting               Current Value
output                text
access-token          eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xv...
expiry                2022-11-29T12:36:41Z
refresh-token         6c51cf4fa54d4a76b3c118f3c5350ec5-r
ansi-colors-enabled   true
oauth-client-id       sas.cli


It should be noted that in both cases the expiry time is shown in the UTC time zone, which might not reflect the same time zone as the host where you are running the SAS Viya CLI.


SAS Viya CLI Auto-Refresh


The SAS Viya CLI will automatically use the opaque Refresh Token to obtain a new Access Token. This means that even when the Access Token has expired you are still able to run SAS Viya CLI commands, so long as the Refresh Token has not expired, and you have not logged out. This does not require any interaction from the end-user. So, with the SAS Viya 2022.09 LTS release after 4 hours the Access Token will be automatically refreshed for you. While with SAS Viya 2022.10 Stable release (and later) this occurs after 1 hour. If you look at the credentials.json file, you will see that the Access Token has been refreshed and the expiry time moved forward. If you attempt to use the SAS Viya CLI after the Refresh Token has expired, you’ll be presented with the following message:


The following errors have occurred:
The user token is expired. Login again before attempting any commands.
Http Status: 0

This means that if you have a secured environment where you want to run scheduled tasks leveraging the SAS Viya CLI and you are confident in the security of the credentials.json file you could leave the SAS Viya CLI authenticated. The SAS Viya CLI would then continue to refresh the Access Token until the Refresh Token expires, after 90 days.


Revoking Tokens


Since the Refresh Token produced by the SAS Viya CLI will be valid for 90 days and can be used to obtain an Access Token, being able to revoke the Refresh Token is important. If you are administrating a SAS Viya environment and are concerned that some of your end-users might not remember to use the command sas-viya auth logout to revoke their own token. Then you could revoke all Refresh Tokens issued to the SAS Viya CLI on a regular basis. You will need to have a Bearer token as a member of SAS Administrators or the sasboot user.


To revoke the Refresh Tokens issued to users of the SAS Viya CLI you would use:


curl -i -X GET "${INGRESS_URL}/SASLogon/oauth/token/revoke/client/sas.cli" -H "Authorization: Bearer $BEARER_TOKEN"


Which would output:


HTTP/1.1 200
Date: Tue, 29 Nov 2022 12:35:02 GMT
Content-Length: 0
Connection: keep-alive
Set-Cookie: sas-ingress-nginx=a772dad7648bc6f096fb118a58701b7e|f8c52217c576225c1e53519ff3193724; Path=/SASLogon/; Secure; HttpOnly; SameSite=Lax
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=15724800; includeSubDomains
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
X-Content-Type-Options: nosniff

After this, anyone using the SAS Viya CLI would need to reauthenticate once their Access Token has expired. But it would not impact any existing Access Tokens.


Custom Clients


If you define your own clients to SAS Logon Manager, you will need to decide about the correct lifetime values you want to use for the Access Tokens. You can override the system-wide default for your custom applications by updating the value for the access_token_validity property. See Register an OAuth Client ID in SAS Viya: Authentication for information about the access_token_validity property and the steps for registering a client so that it can obtain tokens.


For example, say you have registered a client to SAS Logon Manager with the following settings:


curl -k -X POST "${INGRESS_URL}/SASLogon/oauth/clients" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   -d '{
    "client_id": "",
    "client_secret": "myclientsecret",
    "scope": ["*"],
    "authorized_grant_types": ["password","authorization_code","refresh_token"],
    "access_token_validity": 300,
    "redirect_uri": "urn:ietf:wg:oauth:2.0:oob"


This will allow end-users to authenticate with either their username and password or using the authorization code. This client will produce Access Tokens with a lifetime of 5 minutes but will use the system wide default of 90 days for the lifetime of the Refresh Tokens. With this client you could then authenticate with a username and password to obtain the end-users Access Token and Refresh Token with the following:


AUTH_RESP=$(curl -skX POST "${INGRESS_URL}/SASLogon/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=sasadm&password=Metadata0" \
  -u ""); \
USER_TOKEN=$(echo $AUTH_RESP|jq -r '."access_token"'); \
USER_REFRESH=$(echo $AUTH_RESP|jq -r '."refresh_token"'); \
echo "The end-user access-token is: " ${USER_TOKEN}; \
echo "The end-user refresh-token is: " ${USER_REFRESH}; \
echo "Expiry date of Access Token is: $(printf '%(%FT%T%z)T\n' $(echo ${USER_TOKEN}|awk -F'.' '{print $2}'|base64 -d|jq -r '."exp"'))"


Which would produce an output something like the following:


The end-user access-token is:  eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0.
The end-user refresh-token is:  eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0.
Expiry date of Access Token is: 2022-11-29T10:48:31-0500

You could then use the Refresh Token to obtain a new Access Token with the following:


AUTH_RESP=$(curl -skX POST "${INGRESS_URL}/SASLogon/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "${USER_REFRESH}"); \
USER_TOKEN=$(echo $AUTH_RESP|jq -r '."access_token"'); \
echo "The end-user access-token is: " ${USER_TOKEN}; \
echo "Expiry date of Access Token is: $(printf '%(%FT%T%z)T\n' $(echo ${USER_TOKEN}|awk -F'.' '{print $2}'|base64 -d|jq -r '."exp"'))"


Which would produce the following:


The end-user access-token is:  eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbG9jYWxob3N0L1NBU0xvZ29uL3Rva2VuX2tleXMiLCJraWQiOiJsZWdhY3ktdG9rZW4ta2V5IiwidHlwIjoiSldUIn0.
base64: invalid input
Expiry date of Access Token is: 2022-11-29T10:50:33-0500


These simple CURL examples demonstrate how you could use the Refresh Token for your own custom clients of SAS Logon Manager. Notice that in this case the Refresh Token is a Signed JSON Web Token, not an opaque token, and is not revokable.




With the SAS Viya 2022.10 Stable release the Access Token now has a default lifetime of 1 hour while the Refresh Token has a default lifetime of 90 days. In this blog we have shown how the SAS Viya CLI will automatically refresh the Access Token so long as the Refresh Token is still valid. Equally, we have shown how you can easily revoke these long-lived Refresh Token’s ensuring that you can force your end-users to reauthenticate. Finally, we have also discussed how these token lifetimes might impact your custom clients of SAS Logon Manager, and how you can also leverage the Refresh Token.

Version history
Last update:
‎12-06-2022 02:02 PM
Updated by:



Registration is open! SAS is returning to Vegas for an AI and analytics experience like no other! Whether you're an executive, manager, end user or SAS partner, SAS Innovate is designed for everyone on your team. Register for just $495 by 12/31/2023.

If you are interested in speaking, there is still time to submit a session idea. More details are posted on the website. 

Register now!

Free course: Data Literacy Essentials

Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning  and boost your career prospects.

Get Started

Article Tags