Authenticate access with personal access tokens for VSTS and TFS

VSTS | TFS 2018 | TFS 2017

Visual Studio Team Services (VSTS) and Team Foundation Server (TFS) use enterprise-grade authentication, backed by a Microsoft account or Azure Active Directory (Azure AD), to help protect and secure your data. Clients like Visual Studio and Eclipse (with the Team Explorer Everywhere plug-in) natively support Microsoft account and Azure AD authentication, so you can directly use those authentication methods to sign in.

For non-Microsoft tools that integrate into VSTS but do not support Microsoft account or Azure AD authentication interactions (for example, Git, NuGet, or Xcode), you need to set up personal access tokens (PATs). You set up PATs by using Git credential managers or by creating them manually. You can also use personal access tokens when there is no "pop- up UI," such as with command-line tools, integrating tools or tasks into build pipelines, or using REST APIs.

Personal access tokens essentially are alternate passwords that you create in a secure way by using your normal authentication. PATs can have expiration dates, limited scopes (for example, only certain REST APIs or command-line operations are valid), and specific VSTS organizations. You can put them in environment variables so that scripts don't hard code passwords. For more information, see Authentication overview and Scopes.

Create personal access tokens to authenticate access

  1. Sign in to either your VSTS organization (https://{yourorganization}.visualstudio.com) or your Team Foundation Server web portal (https://{server}:8080/tfs/).

  2. From your home page, open your profile. Go to your security details.

    TFS 2017

    Go to VSTS account home, open your profile, go to Security

    VSTS

    TFS home page, open your profile, go to Security

  3. Create a personal access token.

    Add a personal access token

  4. Name your token. Select a lifespan for your token.

    If you're using VSTS, and you have more than one account, you can also select the VSTS account where you want to use the token.

    Name your token, select a lifespan. If using VSTS, select an account for your token

  5. Select the scopes that this token will authorize for your specific tasks.

    For example, to create a token to enable a build and release agent to authenticate to VSTS or TFS, limit your token's scope to Agent Pools (read, manage).

  6. When you're done, make sure to copy the token. You'll use this token as your password.

    Use a token as the password for your Git tools or apps

    Note

    Remember that this token is your identity and acts as you when it's used. Keep your tokens secret and treat them like your password.

    To keep your token more secure, use credential managers so that you don't have to enter your credentials every time. Here are some recommended credential managers:

Revoke personal access tokens to remove access

When you don't need your token anymore, just revoke it to remove access.

  1. From your home page, open your profile. Go to your security details.

    VSTS

    Go to the VSTS account home page, open your profile, go to Security

    TFS 2017

    Go to the TFS home page, open your profile, go to Security

  2. Revoke access.

    Revoke a token or all tokens

Using PATs

For examples of using PATs, see Git credential managers, REST APIs, NuGet on a Mac, and Reporting clients.

Frequently asked questions

Q: What is my Visual Studio Team Services URL?

A: https://{yourorganization}.visualstudio.com, for example.

Q: What notifications might I receive about my PAT?

A: Users receive two notifications during the lifetime of a PAT, one at creation and the other 7 days approaching the expiration.

Here's the notification at PAT creation:

PAT creation notification

Here's the notification that a PAT is nearing expiration:

PAT nearing expiration notification

Q: What do I do if I believe that someone other than me is creating access tokens on my organization?

A: If you get a notification that a PAT was created and you don't know what caused this, keep in mind that some actions can automatically create a PAT on your behalf. For example:

  • Connecting to a VSTS Git repo through git.exe. This creates a token with a display name like "git: https://MyOrganization.visualstudio.com/ on MyMachine."
  • Setting up an Azure App Service web app deployment. This creates a token with a display name like "Service Hooks :: Azure App Service :: Deploy web app."
  • Setting up web load testing as part of a pipeline. This creates a token with a display name like "WebAppLoadTestCDIntToken."

If you still believe that a PAT was created in error, we suggest revoking the PAT. The next step is to investigate whether your password has been compromised. Changing your password is a good first step to defend against this attack vector. If you’re an Azure Active Directory user, talk with your administrator to check if your organization was used from an unknown source or location.