Partager via

Service endpoints - Authentication schemes

  • Article

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

Comments

  • Anonymous
    February 27, 2017
    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.
    • Anonymous
      February 27, 2017
      @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?
      • Anonymous
        April 07, 2017
        The comment has been removed
        • Anonymous
          June 06, 2017
          @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.
          • Anonymous
            October 23, 2017
            @Jim - We have added JWT based OAuth as another authentication scheme we support within service endpoints. Hopefully this would address the requirement you have.
  • Anonymous
    June 06, 2017
    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
    • Anonymous
      June 06, 2017
      Just some more details: I'm trying to acomplish this task against TFS2017.1
      • Anonymous
        June 06, 2017
        @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.
  • Anonymous
    August 03, 2017
    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-cacheAuthorization: Basic *************************************Content-Type: application/json;charset=UTF-8Accept-Encoding: gzip, deflateIf 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-cacheAuthorization: FortifyToken 012345689ABCDEFGHIJKLMNOPQRSTUVWXYZContent-Type: application/json;charset=UTF-8Accept-Encoding: gzip, deflateWhat would be the correct approach for a scenario like this?
    • Anonymous
      August 04, 2017
      @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?
      • Anonymous
        August 04, 2017
        Also, what is the URL used to query the token? Is it endpoint's URL or will it be a different one?
      • Anonymous
        August 04, 2017
        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).
        • Anonymous
          August 06, 2017
          @Steve - thanks for your inputs. We will let you know once we have added support for your scenario.
        • Anonymous
          August 07, 2017
          @Steve - could you pl. clarify the body that you would take when making the first POST call to get the token?