Choosing the right authentication mechanism

When writing an application which interfaces with VSTS, you will have to authenticate to gain acess to resources like REST APIs. We understand that VSTS offers many different ways to authenticate your application. This topic provides guidance to help you choose the right authentication for your application. The following table outlines the recommended authentication mechanism for different application types. We have provided basic descriptions, examples, and code samples to get you started.

Type of application Description example Authentication mechanism Code samples
Interactive client-side (REST) Client application, that allows user interaction, calling VSTS REST APIs Console application enumerating projects in an account Active Directory authentication library (ADAL) sample
Interactive client-side (Client library) Client application, that allows user interaction, calling VSTS Client libraries Console application enumerating bugs assigned to the current user Client libraries sample
Interactive Javascript GUI based Javascript application AngularJS single page app displaying project information for a user Active Directory authentication Library for JS (ADAL JS) sample
Non-interactive client-side Headless text only client side application Console app displaying all bugs assigned to a user Device Profile sample
Interactive client-side app targeting VSTS and TFS Client application, that allows user interaction, authenticates VSTS and TFS users Console application allowing VSTS and TFS users to see assigned bugs Client Library (Interactive and Windows authentication) sample
Interactive web GUI based web application Custom Web dashboard displaying build summaries OAuth sample
TFS application TFS app using the Client OM library TFS extension displaying team bug dashboards Client Libraries sample
VSTS Extension VSTS extension Agile Cards VSS Web Extension SDK sample walkthrough

Enabling IIS Basic Authentication invalidates using PATs for TFS

Learn more about using IIS Basic Authentication with TFS on-premises.

Q&A

Q: I am making an interactive client-side application. Should I use VSTS Client Libraries or VSTS REST APIs?

A: We recommend using VSTS Client Libraries over REST API's when accessing VSTS resources. They are simplier and more easily maintained when version changes to our REST endpoints occur. If there is missing functionality from the client libraries ADAL is the best authentication mechanism to use with our REST API's.

Q: Can I use ADAL if I log into my VSTS account with a Microsoft account (MSA)?

A: Yes, you can use ADAL to create client side applications for an MSA backed account using ADAL with some limitations. Instead of configuring ADAL with a Client ID or Reply URL from Azure Portal, MSA users can use the Client ID: "872cd9fa-d31f-45e0-9eab-6e460a02d1f1" and Reply URL: "urn:ietf:wg:oauth:2.0:oob" as replacement values to get a valid ADAL access token without needing an Azure Active Directory.

Note: This approach will only work for client side applications. For JS web apps, ADAL JS will not work without an AAD tenant.

Q: Is this guidance only for VSTS or is this also relevant for on-prem TFS users?

A: This guidance is mainly for VSTS users. Client Libraries are a series of packages built specifically for extending TFS functionality. For on-prem users, we recommend using the Client Libraries, Windows Auth, or Personal Access Tokens (PATs) to authenticate on behalf of a user.

Q: What if I want my application to authenticate with both TFS and VSTS?

A: The best practice is to have different authentication paths for TFS and VSTS. You can use the requestContext to find out which you're hitting and then use the best mechanism for each. Alternatively, if you want a unified solution, PATs will work for both.