Azure DevOps authentication options
Last updated
Was this helpful?
Last updated
Was this helpful?
SpecSync supports several authentication options for the . This section provides a summary of how the different authentication options have to be configured:
For Azure DevOps (Visual Studio Team Services, VSTS):
(from build and release pipelines)
For on premises Azure DevOps Server (or Team Foundation Server):
(from build and release pipelines)
The authentication credentials can be specified in multiple ways:
During the execution of the SpecSync command using the interactive prompt (password is masked). This method is used by SpecSync if either the user name (token) or the password is not configured anywhere else.
Using the --user
and --password
.
In the of the (specsync.json
).
In the .
In system environment variables that can be referred to either in the configuration file or from the command prompt (see examples below). The environment variable name has to be specified using the {env:ENV_VAR}
format (%ENV_VAR%
format is also accepted for backwards compatibility).
Specifying the user name in the specsync.json
configuration file:
Specifying the user name in the command line:
Specifying the user credentials that refer to an environment variable in the specsync.json
configuration file. The example requires the user name to be stored in the environment variable SPECSYNC_REMOTE_USER
:
You can also use the environment variables without the shell resolving their values. For that, specify the value in the {env:ENV_VAR}
format.
For on premises Team Foundation Server, PAT can only be used if the connection to the Azure DevOps server is using https
.
To create a personal access token, you have to follow the following steps:
On the upper right corner, click on your name and select "Security".
Switch to the "Personal access tokens" tab inside the "Security" group.
Click on "New Token" to create a new personal access token for synchronization.
Click on "Create" and save the generated token.
Once you have created your token, you can use it as user for the synchronization.
Or on the command line prompt:
path-to-specsync-package/tools/SpecSync4AzureDevOps.exe push --user "52yny...........................nycsetda"
In order to work correctly SpecSync requires at least the following authorization scopes enabled for Personal Access Tokens (PAT). The Build and Release read permissions are required to associate the test results to build and release pipelines.
Work Items
Read & write
Test Management
Read & write
Build
Read
Release
Read
Once the Job access token is enabled, you can refer to it with $(System.AccessToken)
. E.g.
You can find more information about configuring a build or release pipeline for running synchronization in How to use SpecSync from build or release pipeline.
In order to use the configured service principal you will need the following details:
Microsoft Entra Tenant ID - you need to specify this in the remote/tenantId
configuration setting.
Application ID (Client ID) - you need to specify this in the remote/user
configuration setting or with the --user
command line option.
A client secret or the thumbprint of the authentication certificate.
In case you use a client secret, the value has to be specified in the remote/password
configuration setting or with the --password
command line option. If you don't specify the client secret, SpecSync will read it thought an interactive prompt.
In case you use authentication certificate, the certificate has to be saved to the Personal certificate store and the thumbprint of the certificate has to be specified in the remote/authenticationCertificateThumbprint
configuration setting.
The following example shows a setup where the service principal details are configured in the SpecSync configuration file and the client secret is loaded from an environment variable SPECSYNC_CLIENT_SECRET
.
In the second example, the client secret is specified using the --password
command line option.
A slightly less secure alternative of personal access tokens is to use alternate authentication credentials with Azure DevOps. With this option, you can provide a username/password pair that can be used for password-based authentication.
To enable alternate authentication credentials, you have to follow the following steps:
On the upper right corner, click on your name and select "Security".
Switch to the "Alternate credentials" tab inside the "Security" group.
Check the "Enable alternate authentication credentials" checkbox and specify a (secondary) user name and password.
Click on "Save".
Once you have enabled alternate authentication credentials, you can use the synchronization with the secondary user name and password. This user name and password is not the same as the user name (email) and password you specify to login to Azure DevOps with your browser!
Or on the command line prompt:
(If you don't specify the --password
option, the tool will prompt you for entering the password.)
For installed Team Foundation Servers, you can use your domain user name (MYDOMAIN\myuser
format) and password for the synchronization.
Or on the command line prompt:
(If you don't specify the --password
option, the tool will prompt you for entering the password.)
For installed Team Foundation Servers, if you don't specify the user, you will be asked to provide your credentials in an interactive sign-in prompt.
A that configures credentials for multiple projects.
The recommended way to access your Azure DevOps project for synchronization is to use (PAT). PAT is like a combination of a user name and a password that are valid for a certain time only and can have restricted access to your Azure DevOps resources.
Navigate to your Azure DevOps server (e.g. ) with a browser.
Specify a description (e.g. "SpecSync"), select an expiration and select "Full access" as authorized scopes or select at least the scopes listed below in section .
The personal access token can be configured in the :
When performing synchronization from build and release pipelines the easiest is to use the Job access token (sometimes also referred as System access token). A job access token is a security token that is dynamically generated by Azure Pipelines for each job at run time. The agent on which the job is running can use the job access token in order to access resources in Azure DevOps. Learn more about job access tokens in the .
in Azure DevOps organizations can be used to grant access to your organization resources. For many teams, this feature can be a viable and preferred alternative to personal access tokens (PATs) when you authenticate applications that power automation workflows in your company.
In order to use service principal for authentication, you have to configure that first in Azure and in Azure DevOps. Please follow the steps described in the .
The service principal is treated like an separate user in Azure DevOps, so in order to use that account for testing-related activities (like use it with SpecSync), you need to set its to one that allows these activities, e.g. Basic + Test Plans
. This might incur additional Azure license costs.
Azure DevOps no longer supports alternate credentials since 2020. It is recommended to use instead. See for details.
Navigate to your Azure DevOps server (e.g. ) with a browser.
The alternate authentication credentials can be configured in the :
The domain user name and password can be configured in the :
The Windows sign-in prompt is currently not supported when you use the of SpecSync.