Service endpoints - Authentication schemes

Authentication scheme in a service endpoint determines the credentials that would be used to connect to the external service. In order to populate task drop downs, TFS/VSTS connects to the external service using the credentials provided as part of the endpoint. TFS/VSTS effectively becomes a client of the external service querying for details pertaining to the task input.

For TFS/VSTS to be able to connect to the external service, in addition to using the credentials, there is also need to know how to set the credentials in the HTTP request header when calling the external endpoint. TFS/VSTS supports a closed set of authentication schemes that can be utilized by a custom service endpoint type. This set is closed so that VSTS/TFS would be able to interpret the auth. scheme used injso any custom endpoint & support connecting to the external service.

Following are the authentication schemes that are part of the closed set:

Basic authentication

"id": "endpoint-auth-scheme-basic",
"description": "Basic Authentication based endpoint authentication scheme",
"type": "ms.vss-endpoint.service-endpoint-auth-scheme",
"targets": [
"ms.vss-endpoint.endpoint-auth-schemes"
],
"properties": {
"name": "UsernamePassword",
"displayName": "i18n:Basic Authentication",
"headers": [
{
"name": "Authorization",
"value": "Basic {{ #base64 endpoint.username \":\" endpoint.password }}"
}
],
"inputDescriptors": [
{
"id": "username",
"name": "i18n:Username",
"description": "i18n:Username for connecting to the endpoint",
"inputMode": "textbox",
"isConfidential": false,
"validation": {
"isRequired": true,
"dataType": "string",
"maxLength": 300
}
},
{
"id": "password",
"name": "i18n:Password",
"description": "i18n:Password for connecting to the endpoint",
"inputMode": "passwordbox",
"isConfidential": true,
"validation": {
"isRequired": true,
"dataType": "string",
"maxLength": 300
}
}
]
}
This scheme takes 2 inputs – Username & Password (confidential)

Default auth. header used is: "Basic {{ #base64 endpoint.username \":\" endpoint.password }}"

 

Token based authentication

"id": "endpoint-auth-scheme-token",
"description": "i18n:Token based endpoint authentication scheme",
"type": "ms.vss-endpoint.service-endpoint-auth-scheme",
"targets": [
"ms.vss-endpoint.endpoint-auth-schemes"
],
"properties": {
"name": "Token",
"displayName": "i18n:Token Based Authentication",
"headers": [
{
"name": "Authorization",
"value": "{{endpoint.apitoken}}"
}
],
"inputDescriptors": [
{
"id": "apitoken",
"name": "i18n:API Token",
"description": "i18n:API Token for connection to endpoint",
"inputMode": "textbox",
"isConfidential": true,
"validation": {
"isRequired": true,
"dataType": "string",
"maxLength": 300
}
}
]
}
This scheme takes 1 input – API Token (confidential)

Default auth header used is: {{endpoint.apitoken}}

 

Certificate based authentication

"id": "endpoint-auth-scheme-cert",
"description": "i18n:Creates a certificate-based endpoint authentication scheme",
"type": "ms.vss-endpoint.service-endpoint-auth-scheme",
"targets": [
"ms.vss-endpoint.endpoint-auth-schemes"
],
"properties": {
"name": "Certificate",
"displayName": "i18n:Certificate Based",
"inputDescriptors": [
{
"id": "certificate",
"name": "i18n:Certificate",
"description": "Content of the certificate",
"inputMode": "TextArea",
"isConfidential": true,
"validation": {
"isRequired": true,
"dataType": "string"
}
}
]
}

This scheme takes 1 input – Certificate (confidential)

The value of certificate has to be provided in the text area.

 

No authentication

"id": "endpoint-auth-scheme-none",
"description": "i18n:Creates an endpoint authentication scheme with no authentication.",
"type": "ms.vss-endpoint.service-endpoint-auth-scheme",
"targets": [
"ms.vss-endpoint.endpoint-auth-schemes"
],
"properties": {
"name": "None",
"displayName": "i18n:No Authentication"
}

This scheme is used when an endpoint type does not require to take any input. For e.g. external services that support anonymous access to its resources.

JSON web token based OAUTH authentication

"id": "endpoint-auth-scheme-JWT",
"description": "i18n:Endpoint authentication scheme to support OAUTH using JSON Web token",
"type": "ms.vss-endpoint.service-endpoint-auth-scheme",
"targets": ["ms.vss-endpoint.endpoint-auth-schemes"],
"properties": {
"name": "JWT",
"displayName": "i18n:JSON Web Token based authentication",
"inputDescriptors": [
{
"id": "Issuer",
"name": "i18n:Issuer",
"description": "i18n:Issuer for creating JWT",
"inputMode": "textbox",
"isConfidential": false,
"validation": {
"isRequired": false,
"dataType": "string",
"maxLength": 300
}
},
{
"id": "Audience",
"name": "i18n:Audience",
"description": "i18n:Audience for creating JWT",
"inputMode": "textbox",
"isConfidential": false,
"validation": {
"isRequired": true,
"dataType": "string",
"maxLength": 300
}
},
{
"id": "Scope",
"name": "i18n:Scope",
"description": "i18n:Scope to be provided",
"inputMode": "textbox",
"isConfidential": false,
"validation": {
"isRequired": false,
"dataType": "string",
"maxLength": 300
}
},
{
"id": "PrivateKey",
"name": "i18n:Private Key",
"description": "i18n:Private Key for connecting to the endpoint",
"inputMode": "textbox",
"isConfidential": true,
"validation": {
"isRequired": true,
"dataType": "string",
"maxLength": 2000
}
}
]
}

This authentication scheme takes 4 inputs – Issuer, Audience, Scope, PrivateKey.

The following processing is done in order to generate auth. header for this authentication scheme:

  • Create JSON web token using the issuer, audience & scope provided. Scope is added as additional claim in the token.
  • PrivateKey is used to populate the signature in the token. It is expected to be in PEM format.
  • POST call is made to the audience with the generated token as content & the response of the call is taken as the bearer’s access token in the auth. header. (Bearer <access_token>)

Azure specific authentication schemes

In addition to the above schemes, Azure certificate & Azure service principal based authentication schemes are supported which are used in the Azure Classic and Azure RM endpoint types respectively.

Further References

Service endpoints - Overview Service endpoints - Customization Service endpoints – Data sources MD version of this blog