tutorials GitHub

Hello, Tapis

In this first tutorial, we will learn to authenticate with Tapis using our TACC username and password; then we will make our first API request to Tapis.

As discussed in the introduction, we will use the official Tapis Python SDK for all of our interactions with the APIs. The Python SDK provides Python-native methods and objects for making HTTP requests and parsing HTTP responses to and from the Tapis API. In order to do just about anything with Tapis, we will need to authenticate.

Tapis authentication is based on tokens (specifically, JSON Web Tokens). To make an API request to Tapis, you first need to generate a token. Tapis can be configured to support the requirements of different projects and institutions, including different mechanisms for generating tokens. For this tutorial, we will generate a token using our TACC username and password. (If you do not have a TACC account, check the prerequisites and sign up for an account here.)

In your Jupyter notebook copy the block below and execute it (Control+Shift).

# Enter your TACC username and password
import getpass

username = input("Username: ")
password = getpass.getpass(prompt="Password: ", stream=None)

All of our interactions with Tapis will go through the Tapis python object. In particular, we can use it to generate a token.

In your Jupyter notebook that is connected to a TACC server, copy the block below and execute it using the (Shift+Enter) method. You will get a Tapis v3 token to interact with the Tapis services.

from tapipy.tapis import Tapis
base_url = "https://tacc.tapis.io"

# Create python Tapis client for user
t = Tapis(base_url= base_url, username=username, password=password)

# *** Tapis v3: Call to Tokens API
t.get_tokens()

# Print Tapis v3 token
t.access_token

The output should look something similar to the following:

access_token: eyJ0eXAiOiJKV1...
claims: {'jti': 'dfada014-66ca-4f6e-a57a-48b618a79678', 'iss': 'https://tacc.tapis.io/v3/tokens', 
'sub': 'jstubbs@tacc', 'tapis/tenant_id': 'tacc', 'tapis/token_type': 'access', 
'tapis/delegation': False, 'tapis/delegation_sub': None, 'tapis/username': 'jstubbs', 
'tapis/account_type': 'user', 'exp': 1638153035, 'tapis/client_id': None, 
'tapis/grant_type': 'password'}
expires_at: 2021-11-29 02:30:35+00:00
expires_in: <function Tapis.add_claims_to_token.<locals>._expires_in at 0x7f110806a8b0>
jti: dfada014-66ca-4f6e-a57a-48b618a79678
original_ttl: 14400

The actual access token is the string labeled access_token beginning with eyJ.. in the output above. The tapipy library derived the other fields from the token, including the set of claims. The claims represent information about the authentication, including the username and when the token expires. When you make an API request to Tapis passing the token, the service uses the claims to determine who you are and what accesses you have.

Take the access_token value and export it to a JWT variable on the command line as follows:

export JWT=eyJ..

Now that we have an allocated access token, we are ready to make our first authenticated API request to Tapis. For this Hello, Tapis tutorial, we’ll make a call to the Authenticator service to see that Tapis knows who we are.

Copy the following block into your notebook and run it.

t.authenticator.get_userinfo()

You should see your user information in output similar to the following:

create_time: None
dn: cn=jstubbs,ou=People,dc=tacc,dc=utexas,dc=edu
email: jstubbs@tacc.utexas.edu
given_name: Joe
last_name: Stubbs
mobile_phone: None
phone: None
uid: 811324
username: jstubbs

The API request syntax t.authenticator.get_userinfo() follows a common pattern: t.<service>.<endpoint>(<parameters>). Here, the Tapis service we are using is authenticator and the specific endpoint we are invoking is the get_userinfo() endpoint. The authenticator service has many other endpoints which you can read about in the Tapis reference documentation or in API specification.

Next Steps

Now that we have covered authenticating with Tapis, let’s look at Tapis’s concept of a system – these are the storage and computing resources Tapis will interact with on your behalf.

Next-> Introduction to Systems

Additional Resources

See the following links for more information about the above topics.