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 in 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.

 

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


Comments (13)

  1. Jim Przybylinski says:

    This is all very helpful. Is there an authorization scheme that will support Json Web Token authentication? I can put the needed data in a service endpoint, and use it in the build tasks I’m writing, but using a datasource requires headers built with cryptography that probably doesn’t fit in a Mustache handler.

    1. Sriram B says:

      @Jim – I presume the Json Web Token authentication related data passed in the header of HTTP request. The auth. header to be specified in the HTTP request when querying a data source can be customized: https://blogs.msdn.microsoft.com/sriramb/2016/09/15/service-endpoints-customization/
      Is there any additional capability required to support JWT authentication that we currently don’t have?

      1. Jim Przybylinski says:

        @Sriram – I’m sorry I didn’t get back to you sooner (didn’t get an email about your reply). JWT requires that part of the header be encoded with a cryptographic hash (in my case it must be RS256). Is there Mustache handler that will do that?

        1. Sriram B says:

          @Jim – We do not have a Mustache handle to encode using RS256 as of now. Thanks for the feedback. We will add this support going forward & let you know once we have it.

  2. Bruno Figueiredo says:

    Hi Sriram,

    I’m trying to use the VSTS REST API to add a new service endpoint (to SonarQube) that seems to rely on the token authentication. But when ever I try to add it I get a “Authentication scheme couldn’t be recognized ‘Token’\r\nParameter name: endpoint.Authorization.Scheme”.

    Any thoughts on this?

    the json I’m sending is:
    {
    name: “SonarQube@sonarqube.server”,
    type: “Sonarqube”,
    url: “http://sonarqube.server/”,
    authorization: {
    “scheme”: “Token”,
    “parameters”: {
    “apitoken”: “[SOME_API_TOKEN]”
    }
    }
    }

    Thanks,
    Bruno

    1. Bruno Figueiredo says:

      Just some more details: I’m trying to acomplish this task against TFS2017.1

      1. Sriram B says:

        @Bruno – Looks like SonarQube endpoint type does not support “Token” based authentication scheme. In the latest version of the extension (2.1.2) I see it only supports Basic authentication scheme. Could you check if you are able to create a token auth. scheme based endpoint from UI (Project -> Settings -> Services -> New Service Endpoint -> Sonar Qube) with TFS 2017.1? If not, then the failure in the API is expected.

  3. Steve L. says:

    I’m trying to consume an internal rest api by creating a custom endpoint. In order to communicate with this api, I have to make a token request using basic authentication which will return a token that’s valid for 24-hours. Here are are the headers I need to pass in the initial request:

    Accept: application/json, text/plain, */*
    Cache-Control: no-cache
    Authorization: Basic *************************************
    Content-Type: application/json;charset=UTF-8
    Accept-Encoding: gzip, deflate

    If successful, I should get a response that looks like this:

    {
    “data”: {
    “token”: “012345689ABCDEFGHIJKLMNOPQRSTUVWXYZ”,
    “creationDate”: “2015-07-22T16:20:12.000+0000”,
    “terminalDate”: “2015-07-23T16:20:12.000+0000”
    },
    “responseCode”: 200
    }

    Once I have the token, all calls should have headers that look like this:

    Accept: application/json, text/plain, */*
    Cache-Control: no-cache
    Authorization: FortifyToken 012345689ABCDEFGHIJKLMNOPQRSTUVWXYZ
    Content-Type: application/json;charset=UTF-8
    Accept-Encoding: gzip, deflate

    What would be the correct approach for a scenario like this?

    1. Sriram B says:

      @Steve – We don’t support a two hop interaction to get the token that can be used in data source queries. We have plans to support this mechanism in near future though. Will update when this support is added.

      In your case, do you do a POST call to get token that’s valid for 24 hours?

      1. Sriram B says:

        Also, what is the URL used to query the token? Is it endpoint’s URL or will it be a different one?

      2. Steve L. says:

        Yes, that’s exactly right. To obtain an authentication token I have to first request (POST) using basic authorization to a specific URL ( https://fortifyinternalserver/ssc/api/v1/auth/obtain_token).

        1. Sriram B says:

          @Steve – thanks for your inputs. We will let you know once we have added support for your scenario.

        2. Sriram B says:

          @Steve – could you pl. clarify the body that you would take when making the first POST call to get the token?

Skip to main content