Service endpoints - Overview

TFS/VSTS supports Continuous Integration (CI) & Continuous Deployment (CD) scenarios involving external services:

• Building source code from various external source repo providers like GitHub, SVN etc.
• Consuming build artifacts from various external services like Jenkins, TeamCity etc. within release.
• Deploying applications to various external services like Azure, Chef, SCVMM, Docker etc. as part of release.

Service endpoints is used to light up CI/CD scenarios involving external services.

Service endpoints serves the following purposes:

• Stores details related to external service that can include secrets as well.
• Allows querying the external service in a secure manner and use the results to enhance CI/CD user experience.

Details that a service endpoint typically captures include the following:

• Name of the endpoint using which it can be referred to later
• Type of the endpoint
• URL to connect to the external service
• Authentication scheme to use (e.g. Basic authentication, Certificate based authentication etc.)
• Authentication scheme parameters (User name, Password, Certificate etc.)

Single endpoint type can support multiple authentication schemes.

There is support for providing additional details specific to endpoint type beyond the above. How additional details can be included is covered in section below.

Authentication parameters provided as part of endpoint are stored securely and is never returned back from the service.

Service endpoints are stored within individual team projects.

Service endpoint can be created through the following UI:

Security can be applied on endpoints to control access to them.

Endpoints support security 2 role types: Administrator or User.

Administrator of endpoint can essentially manage the endpoint (update/delete, set permissions) and also be able to use the endpoint within build definitions or release definitions.

User of endpoint can only use the endpoint within build definitions or release definitions.

Each project has 2 groups – Endpoint Administrators & Endpoint Creators.

Endpoint Administrators group is added as an Administrator role on each endpoint by default. Project Administrators are added to the Endpoint Administrators group in every project by default.

Endpoint Creators group control who can create endpoint within the project. Contributors are added to the Endpoint Creators group in every project by default.

Service endpoints support REST APIs to be able to work with them. The set of supported REST APIs is documented here:

https://www.visualstudio.com/en-us/docs/integrate/api/endpoints/overview

Endpoints created within the project can later be referenced in tasks within Build or Release definition.

Tasks can define an endpoint input & additional inputs that are essentially drop-downs that get populated by querying external services using the endpoint input.

Here are references to some tasks that use endpoints:

https://github.com/Microsoft/vsts-tasks/blob/ed7d8ec751176d75c83132f79e9ad6eae1109377/Tasks/SqlAzureDacpacDeployment/task.json https://github.com/Microsoft/vsts-tasks/blob/2cb2a67ee75be8ecc75e155d99d55d33aa364b40/Tasks/AzureCLI/task.json

During runtime, TFS/VSTS passes down the endpoint information down to the agent and makes it available to tasks that use them.

vsts-task-lib contains helper functions to let tasks query endpoint information:

• For PS based tasks, Get-VstsEndpoint commandlet can be used to retrieve endpoint details.
• For Node based tasks, task.getEndpointUrl & task.getEndpointAuthorization helpers can be used to retrieve endpoint details.

Here are references to task implementations that consume endpoints:

https://github.com/Microsoft/vsts-tasks/blob/ed7d8ec751176d75c83132f79e9ad6eae1109377/Tasks/SqlAzureDacpacDeployment/Utility.ps1 https://github.com/Microsoft/vsts-tasks/blob/2cb2a67ee75be8ecc75e155d99d55d33aa364b40/Tasks/AzureCLI/azureclitask.ts

Service endpoints – Authentication schemes Service endpoints - Customization Service endpoints – Data sources