1. Home
  2. Managing Projects and Users
  3. Obtaining and using FABRIC API tokens

Obtaining and using FABRIC API tokens

As described in this article the foundation of FABRIC user permission are projects and project tags. But how do they actually translate into decisions by the FABRIC Control Framework to allow or deny the use of FABRIC resources? This is where FABRIC tokens come into play. Tokens are JWTs (JSON Web Tokens or short documents expressed in JSON) that are

  1. Tied to your identity
  2. Tied to the project the you are working in
  3. Have a finite lifetime, but can be renewed
  4. Issued to you by an element of FABRIC infrastructure called the Credential Manager

When issued, the token includes in it the information about the project tags granted to the chosen project. The token is included into API calls with the Control Framework, allowing elements of the FABRIC Control Framework to make decisions on whether to allocate or not allocate specific resources based on the tags included in the token. FABRIC tokens are a form of a bearer token conferring the rights to specific resources to whoever presents the token. Tokens are stored on your local filesystem, when using your own laptop to call on FABRIC APIs, in your Jupyter notebook container, when using the Jupyter Hub or in your browser if you are working in the Portal.

It is imperative to keep your tokens secure. If your token is leaked, the new owner of the token assumes the same rights you had at the time the token was issued. They can continue using it until the token expires (one hour). Starting with Release 1.3 FABRIC Portal will offer the opportunity to revoke a token.

FABRIC software goes to great lengths to hide the majority of interactions with the Credential Manager and other systems making FABRIC token management mostly transparent to the user.

Using tokens within the FABRIC Portal

The good news is there is nothing you need to do to use FABRIC tokens within the portal – all of it will happen completely transparently to you.

There is nothing you need to do to manage your tokens explicitly if you are only using the portal. If you are using FABlib with Jupyter Hub or on your laptop, read on.

The portal also has the ability to help you obtain a new token via a graphical interface for when you are using FABlib either in Jupyter Hub or on your laptop. Navigate to Experiments and click Manage Tokens. When generating a token be sure to select the project for which this token is being generated – remember the rights that you have will depend on which permissions are given to the specific project you chose to work in.

Generating FABRIC token in the Portal

You will be offered a chance to download the token as a file named token.json. Note that at present the portal will automatically log you out as soon as you download the token and you will need to log back in if you want to continue using it.

This process will change with the Release 1.3 of FABRIC software

Using tokens within the Jupyter Hub

When your Jupyter Hub notebook is started, it is pre-loaded with a valid token and FABlib will renew it as necessary while you are running inside the notebook. In the rare instances when the token expires, you may need to go to the FABRIC Portal to obtain a new token.

FABlib expects the token to be in the location identified by the environment variable FABRIC_TOKEN_LOCATION. By default, on JupyterHub, FABRIC_TOKEN_LOCATION is set as indicated below. When you run into a token error such as “Refresh Token: (invalid grant)“, please re-generate the tokens again from the Portal as indicated in the section above and upload to JupyterHub at the location indicated below.

$ echo $FABRIC_TOKEN_LOCATION
/home/fabric/.tokens.json

Using tokens when working on your laptop/desktop

Presumably you are talking to FABRIC API using FABlib, in which case the tokens should initially be setup as indicated here.

FABlib expects the token to be in the location identified by the environment variable FABRIC_TOKEN_LOCATION. When user runs into a token error such as “Refresh Token: (invalid grant)“, please re-generate the tokens again from the Portal as indicated in the section above and update in the location specified in FABRIC_TOKEN_LOCATION.

Updated on May 26, 2022

Was this article helpful?

Related Articles

Need Help?
Can't find the answer you're looking for? Search and ask questions in the forum!
Go to FORUM

Leave a Comment