How to Use AAC's New OAuth 2.0 Refresh Tokens for the AAC API

[briancoombs]

Overview

This tutorial guides Alteryx Analytics Cloud (AAC) developers or AAC users interested in trying the AAC API to use the new OAuth 2.0 API Tokens.

We’ll show 3 different ways to refresh your access and refresh tokens to be continually used in your scripts:

1. Postman

2. Curl

3. Python

Guide

Getting and Saving Your Tokens

1. Go to your user preferences and then go to the OAuth 2.0 API Tokens page.

2. Select Generate.

3. Save the resulting API Access Token and API Refresh Token in a credential store or secure place of your choosing. If you lose these tokens you will have to restart this process.

API Token Rules

• Access tokens last 1 hour.

• Refresh tokens last however long you configured in the UI above, between 1 and 365 days.

Refreshing Your Refresh Tokens

In all the examples below (Postman, Curl, and Python) you will be given a new access token and refresh token. You will need to save these over your existing tokens wherever you have them saved.

Get Your Client ID and the URL to Hit to Refresh your Token (ISS)

1. Examine the access token you saved above and find the section between the 2 periods.

   1. E.g. in the JWT: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c”

   2. “eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ” would be the section you want to use. We’ll call this <payloadOfYourToken>

2. Get your client_id and iss values from the payload of your token.

   1. On Mac

      1. In terminal, enter echo "<payloadOfYourToken>" | base64 -d

      2. The response should include your client_id and iss values.

   2. On Windows

      1. First, you need to have the Base64 string in a file. Save the <payloadOfYourToken> string in a file named “encoded.txt”.

      2. Open your command prompt and enter this command (when in the same folder as your encoded.txt file): certutil -decode encoded.txt decoded_output.txt

      3. Open “decoded_output.txt” to find your client_id and iss values.

3. Copy the client_id and iss values. These shouldn’t change and are public. You can store them in plain text in your script.

   1. The iss value should look similar to https://pingauth.alteryxcloud.com/as

   2. The URL of the endpoint you will use to refresh a token will be the iss value with /token appended at the end. The result will be a URL that looks similar to https://pingauth.alteryxcloud.com/as/token

Postman

1. In Postman, create a new HTTPS request.

2. From the HTTP request method dropdown, select POST.

3. In the URL field, enter the iss value you saved earlier and then concatenate this string to the end: /token

   1. Your url should look something like this: https://pingauth.alteryxcloud.com/as/token

4. Select the Authorization tab.

5. From the Type dropdown, select No Auth.

6. Select the Body tab.

7. Select the x-www-form-urlencoded radio button.

8. On a new row, enter grant_type in the Key field. On the same row, enter refresh_token in the Value field.

9. On a new row, enter refresh_token in the Key field. On the same row, paste the Refresh Token value you saved earlier.

10. On a new row, enter client_id in the Key field. On the same row, paste the client_id value you saved earlier.

11. Select the Send button. You should get a 200 response and see a new access token and refresh token in the response body.

Curl

curl --location '<ISS>/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=<REFRESHTOKEN>' \
--data-urlencode 'client_id=<CLIENTID>'

If the value of iss were https://pingauth.alteryxcloud.com/as, the curl command would look like:

curl --location 'https://pingauth.alteryxcloud.com/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=<REFRESHTOKEN>' \
--data-urlencode 'client_id=<CLIENTID>'

This should give a response with a refresh token and access token. Make sure to overwrite your existing refresh and access token with them.

Python Script

# Initial tokens (store these in a secure key management system of some kind)
access_token = ""
refresh_token = ""

# your iss goes here as the refresh_url
REFRESH_URL = "https://pingauth.alteryxcloud.com/as/token"
CLIENT_ID = ""

## Function to refresh the access token
def refresh_tokens(refresh_token, file_path):
    print("refreshing tokens")
    headers = {
        "Content-Type": "application/x-www-form-urlencoded",
    }
    body = {
        "grant_type": "refresh_token",
        "refresh_token": f"{refresh_token}",
        "client_id": f"{CLIENT_ID}"
    }
    try:
        response = requests.post(REFRESH_URL, data=body, headers=headers)
        response.raise_for_status()  # Raises an HTTPError for bad responses
        new_token_info = response.json()
        print(new_token_info)
        new_access_token = new_token_info.get('access_token') # Update the access token
        new_refresh_token = new_token_info.get('refresh_token') # Update the refresh token
        # make sure to add your own code to save the refresh and access token you get securely
        return new_access_token, new_refresh_token
    except (requests.exceptions.HTTPError, KeyError) as err:
        logging.error(f"Failed to refresh token: {err}")
        raise Exception("Could not refresh the tokens.") from err

This should return a refresh token and access token. Make sure to overwrite your existing refresh and access token with them.

AAC has enabled refresh token rotation by default to ensure that refresh tokens can be used only once. Every time the client uses a refresh token, the authorization server issues a new access token and a new refresh token. When the application wants to run another refresh token flow, it uses the refresh token that was issued most recently.

When an application uses a refresh token, it always receives a new refresh token for next time. As a result, refresh tokens are used only once.

However, if an attacker uses malicious code to steal an application's refresh token, the application won’t be aware that the refresh token has been stolen. It will keep using the refresh token to obtain new access tokens (and refresh tokens). The attacker, who has stolen a refresh token, also wants to get a new access token (and refresh token). As a result, either the attacker or the client application will use a refresh token for the second time.

Refresh token reuse likely indicates that a second party is trying to use a stolen refresh token. In response to this reuse, the authorization server immediately revokes the reused refresh token, along with all descendant tokens.

Conclusion

You can now use your new access token for any of your other AAC API needs and refresh them as they expire.

Please see our other tutorials on how to build different scripts and apps with the AAC APIs.

Thank you for reading along and if you have issues or questions feel free to comment them below or post in the Developer Discussion Forum!