Personal Access Tokens & VSTS

If you happen to be using Git-based projects in Visual Studio Team Services (VSTS – formerly known as Visual Studio Online) then you might have already encountered Personal Access Tokens – or, PAT, for short. If you are not familiar with PATs in VSTS then read on… :-)

As you are already aware, you can sign into VSTS using a Microsoft Account or, if your VSTS account is tied to Azure, an Azure Active Directory account. This approach works great when using the web-based interface for VSTS or when using Microsoft tools such as Visual Studio, both of which provide inherent support for Microsoft and AAD Accounts. If you are making use of 3rd party tools such as the Git command-line interface, SourceTree, etc., then the account types mentioned above don’t play nicely with your tool set.

Until recently, you had to rely on what is known as alternate credentials, which can be created easily enough within your VSTS profile. Alternate credentials are essentially a set of credentials that map to your Microsoft or AAD Account within VSTS. You can choose to make the user name and password the same as your MSA but you don’t have to. Then, when your 3rd party tool prompts you to sign in, you can provide your alternate credentials for authentication purposes.

There are some limitations to this approach. For example, you might be testing out a new app that needs to sign in to VSTS. However, you don’t want to provide your credentials to this app because you don’t know what the app is doing with the credentials. For all you know, the app could be storing your user ID and password for later retrieval. Yikes! Assuming you do trust the app enough to provide it your user credentials, maybe you would like it if the credentials were scoped to a specific area of VSTS, such as being able to read work items only. You can’t do that with alternate credentials.

These are the types of problems that personal access tokens are designed to solve. Once you create a PAT you can use it pretty much anywhere your user credentials are required for authentication. If you use a PAT for a 3rd party tool only to find out later that it is acting maliciously, you can deactivate that specific PAT and it immediately becomes invalid. You can also apply one or more scopes to a PAT so you can, for example, limit access to reading work items and nothing else. Cool!

Creating a PAT

Creating a personal access token is fairly straightforward. To create a PAT:

1. Sign in to VSTS.
2. Click on your user name on the VSTS page and click on My profile.

   

3. From there, click on the Security tab and you will see the Personal access tokens section.

   

4. Click on the Add button and you will see a screen something like the following:

   

5. Once you’ve configured everything the way you want, click on Create Token.

   

6. The new PAT will be displayed once you create it. NOTE: This is the ONLY time the PAT will be displayed. You will need to copy it and store it somewhere safe (e.g. a password vault) so that you can retrieve it as needed. Click on the Copy Token link to display a dialog with the full PAT visible so that you can copy it to the clipboard.

   

Using Your PAT

First, let’s demonstrate the use of a PAT by causing something to fail :-) As shown above, we’ve scoped our PAT to reading work items only. Let’s see what happens if we attempt to clone a Git repo using this PAT.

We will use the command-line interface for this test:

You can see in the above screen shot that our attempt to clone the repo failed. Since our PAT is scoped to reading work items only, authentication failed.

You will also notice that I typed a random user name into the Username field when prompted. When using a PAT, it does not matter what user name you provide. You cannot see the PAT because it is hidden when entered.

Now, let’s go ahead and add the ability to work with source code to our PAT just to prove that the scopes work as expected.

I clicked on the Work Items PAT to display its properties. Here, I checked the “Code (read and write)” scope and clicked Save.

Let’s run the same test again and see if we’re able to successfully clone our repo:

SUCCESS!

Although our PAT is no longer aptly named (it’s not just reading work items any more) you can see that scopes can be used to easily restrict a PAT’s access within VSTS.

Revoking a PAT

As of right now PATs can be configured to be valid for 90 days, 180 days or 1 year. After the time period has elapsed the PAT will be revoked automatically by VSTS. However, you might want to revoke a PAT prior to its scheduled expiration. For example, I might want to revoke the PAT used in the example above so that readers of this article can’t use it to mess around with my sample source code ;-)

Revoking a PAT is as simple as clicking on the Revoke link next to the desired PAT. For example, if I click on Revoke next to Work Items PAT I get the following dialog:

Clicking on Revoke will now list the PAT as having been revoked and is no longer valid for use.

Summary

In summary, if you are working within Microsoft tools, then your MSA or AAD account is an acceptable (and well-supported) approach. If, however, you are working with 3rd party tools that do not support Microsoft or AAD Accounts – or you simply do not want to provide your primary credentials to the tool – then you can make use of personal access tokens to limit your risk. They’re easy to create when you need them and easy to revoke when you don’t.