Authenticate access with personal access tokens for Azure DevOps Services and TFS

Azure DevOps Services | TFS 2018 | TFS 2017

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 organizations. You can put them in environment variables so that scripts don't hard code passwords. For more information, see Authentication overview and Scopes.

Azure DevOps Services 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 Azure DevOps Services 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.

Create personal access tokens to authenticate access

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

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

    Azure DevOps Services

    Go to Azure DevOps organization home, open your profile, go to Security

    TFS 2017

    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 Azure DevOps Services, and you have more than one organization, you can also select the Azure DevOps organization 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 Azure DevOps Services 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.

    Azure DevOps Services

    Go to the Azure DevOps organization 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

What is my Azure DevOps Services URL?

https://dev.azure.com/{yourorganization}

What notifications might I receive about my PAT?

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

The following notification is sent at PAT creation:

PAT creation notification

The following notification is sent - a PAT is nearing expiration:

PAT nearing expiration notification

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

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 an Azure DevOps Services 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.