Microsoft Azure DevOps (Team Foundation Server)

Technical requirements

The following requirements must be met to integrate Microsoft Azure DevOps with SD Elements. They depend on the Authentication Method of the connection: Password or Personal Access Token (the default) or OAuth 2.0 (Microsoft Entra ID).

Password or Personal Access Token

  • Team Foundation Server version 2018 and later.

  • NTLM or Basic Authentication must be enabled

  • The user configured for the connection should:

    • Be a member of the project

    • Have permission to create, tag, transition and close work items.

    • Specific permissions:

      • Edit project-level information - Allow

      • Create tag definition - Allow

OAuth 2.0 (Microsoft Entra ID)

SD Elements signs in to Azure DevOps as an app registered in Microsoft Entra ID, not as a user, so the requirements for the Password or Personal Access Token method above do not apply.

  • The server is Azure DevOps Services, at dev.azure.com or at the organization’s own <organization>.visualstudio.com address. A connection to any other address, such as an on-premise server, uses Password or Personal Access Token.

  • The connection uses the HTTPS protocol, with Enforce Certificate Validation turned on. That option is in the connection’s advanced options.

  • An app is registered in Microsoft Entra ID.

    • The registration needs no redirect URI.

    • In a default tenant, the registration needs no API permissions and no admin consent.

  • The app has a client secret.

    • Microsoft prefers certificates or federated credentials to client secrets for apps. SD Elements does not support them yet.

  • The Azure DevOps organization is connected to the Microsoft Entra tenant that holds the app.

  • In Azure DevOps, the app is:

    • Added to the organization with Basic access. Stakeholder access is not enough: SD Elements always sets a tag on the work items it creates, and an app with Stakeholder access cannot create tags.

    • Added to the project’s Contributors group.

  • The computer that runs the integration can reach login.microsoftonline.com, as well as Azure DevOps. With an on-premise SD Elements, this is the SD Elements server. For an integration that runs through a Remote Integration Agent, it is the computer that runs the agent.

Microsoft bills an app with Basic access once for each organization it is added to. Microsoft does not say whether the app counts toward the organization’s free Basic users, so ask Microsoft how the app affects your organization’s billing.

Default assigned fields

The following fields are set by default:

  • Title

  • Description

  • Priority

Behavior

The integration supports the following:

With OAuth 2.0 (Microsoft Entra ID), a status-change note for a change made by the app shows the app’s name, and the Object ID of its enterprise application (service principal) where a person’s email would appear. SD Elements renews the app’s token before it expires, so a long sync is not interrupted.

Default Priority Mapping

SD Elements

Microsoft Azure DevOps (TFS)

9-10

1

7-8

2

3-6

3

1-2

4

Set up OAuth 2.0 (Microsoft Entra ID)

Set up a connection that signs in as an app. To change an existing connection, see Switch a connection to OAuth 2.0. For errors, see Common errors.

Prerequisites:

  1. The user has the permission Global Roles→Integration→Edit Issue Tracker connections.

  2. The technical requirements for OAuth 2.0 (Microsoft Entra ID) above are met.

Steps in Microsoft Entra ID and Azure DevOps:

  1. Register an app in Microsoft Entra ID for SD Elements. No redirect URI is needed.

  2. Create a client secret for the app. Copy the secret’s Value when it is shown, and note when the secret expires.

  3. Copy the app’s Application (client) ID and the Directory (tenant) ID.

  4. Connect the Azure DevOps organization to the Microsoft Entra tenant that holds the app, if it is not connected yet.

  5. Add the app to the organization with Basic access.

  6. Add the app to the project’s Contributors group.

Steps in SD Elements:

  1. From the gear icon menu, select Integration.

  2. Add a new Issue Tracker connection for Microsoft Azure DevOps (Team Foundation Server), or edit an existing one. See System Issue Tracker connectors.

  3. Enter dev.azure.com as the Server, the name of the Azure DevOps organization as the Context Root, and select HTTPS as the Protocol. Leave Collection Name empty. If the organization has its own <organization>.visualstudio.com address, you can enter that address as the Server instead, and leave Context Root and Collection Name empty.

  4. For Authentication Method, select OAuth 2.0 (Microsoft Entra ID).

  5. Enter the Azure DevOps (TFS) Tenant ID, Azure DevOps (TFS) Client ID and Azure DevOps (TFS) Client Secret. For the secret, enter its Value, not its ID.

  6. Click Test Connection at the bottom-left of the dialog.

  7. Click Create or Done at the bottom of the form.

Project connections do not have these fields. A project Issue Tracker connection uses the credentials of the system connector it is linked to.

Switch a connection to OAuth 2.0 (Microsoft Entra ID)

Switch an existing connection that uses a Personal Access Token (PAT) by editing its system connector. The project connections linked to it follow, because they use the credentials of the system connector. If you cannot switch yet, see Keep a Personal Access Token for now.

Only a connection whose Server is dev.azure.com or an <organization>.visualstudio.com address can switch. For another address, such as an on-premise server, SD Elements refuses OAuth 2.0 (Microsoft Entra ID) when you save the connection and when you run Test Connection. See the Server field in Connection details.
Steps:

  1. If a Remote Integration Agent serves the connection, upgrade the agent first. Install a Remote Integration Agent that includes sdetools 30.6.0 or later (see Installation and Administration). An older agent does not know the new method, and it keeps signing in with the PAT that SD Elements stored.

  2. Do the steps in Microsoft Entra ID and Azure DevOps that Set up OAuth 2.0 lists.

  3. In SD Elements, from the gear icon menu, select Integration, then edit the system connector for the connection.

  4. For Authentication Method, select OAuth 2.0 (Microsoft Entra ID).

  5. Enter the Azure DevOps (TFS) Tenant ID, Azure DevOps (TFS) Client ID and Azure DevOps (TFS) Client Secret.

  6. Click Test Connection, and correct any error with the help of Common errors.

  7. Click Done.

  8. In Azure DevOps, revoke the PAT that the connection used.

Do not skip the last step. SD Elements keeps the stored username and PAT after the switch, and does not use them with OAuth 2.0. Revoking the PAT in Azure DevOps ends it everywhere, including the stored copy.

Keep a Personal Access Token for now

Microsoft is retiring global PATs, which work across all the organizations their user can reach. Until a connection uses OAuth 2.0 (Microsoft Entra ID), replace any global PAT with a PAT that is scoped to the one organization the connection uses. Create the new PAT in Azure DevOps, enter it in the Azure DevOps (TFS) Password/Personal Access Token field of the system connector, test the connection, and save.

Connection details

Enter the connection details for the server.

Protocol

Select the protocol for the connection (HTTPS or HTTP) (Default: HTTPS). OAuth 2.0 (Microsoft Entra ID) needs HTTPS.

Server

The domain name or IP address of the server

URL changes with Azure DevOps may require the addition of a Context Root as well. For example, the URL acme.visualstudio.com may become dev.azure.com/acme, with dev.azure.com as the Server and acme as the Context Root.

OAuth 2.0 (Microsoft Entra ID) works only with Azure DevOps Services at dev.azure.com or at the organization’s own <organization>.visualstudio.com address, where <organization> is one name without dots. With dev.azure.com, enter the organization’s name as the Context Root and leave Collection Name empty. With the visualstudio.com address, leave Context Root and Collection Name empty. Enter the host only, without https://.

Context Root

Top-level location where Microsoft Azure DevOps is installed on a server. The value for this may be dependent on the configuration of an internal corporate proxy or where an administrator has installed Microsoft Azure DevOps.

Collection name

The name of a project collection in Microsoft Azure DevOps. On Azure DevOps Server, the collection is usually DefaultCollection.

For Azure DevOps Services (dev.azure.com or a visualstudio.com address), the Collection Name field stays empty.

Credentials

Enter the credentials needed to authenticate to the server. The fields that appear depend on the Authentication Method.

Authentication Method

Specifies how SD Elements signs in to Azure DevOps. There are two choices: Password or Personal Access Token (Default), and OAuth 2.0 (Microsoft Entra ID).

Username

This configuration is available if you select Password or Personal Access Token for the Authentication Method. Username authorized to connect with the server and create/edit issues in anticipated projects.

Password/Personal Access Token (PAT)

This configuration is available if you select Password or Personal Access Token for the Authentication Method. The password or the Personal Access Token used to authenticate to the server.

Azure DevOps (TFS) Tenant ID

This configuration is available if you select OAuth 2.0 (Microsoft Entra ID) for the Authentication Method. The Directory (tenant) ID of the Microsoft Entra tenant that holds the app, as shown in Microsoft Entra. It is a GUID, such as 1b2c3d4e-0000-1111-2222-333344445555.

Azure DevOps (TFS) Client ID

This configuration is available if you select OAuth 2.0 (Microsoft Entra ID) for the Authentication Method. The Application (client) ID of the app registered in Microsoft Entra ID, as shown in Microsoft Entra. It is a GUID, such as 1b2c3d4e-0000-1111-2222-333344445555.

Azure DevOps (TFS) Client Secret

This configuration is available if you select OAuth 2.0 (Microsoft Entra ID) for the Authentication Method. The Value of a client secret created for the app in Microsoft Entra, not the secret’s ID. SD Elements stores the secret encrypted and shows it masked.

A client secret expires. Note its expiry date when you create it, and replace the secret in this field before then.

Project connections do not show the Authentication Method or the OAuth 2.0 (Microsoft Entra ID) fields. For the setup, see Set up OAuth 2.0 (Microsoft Entra ID).

Countermeasures to Synchronize

Select Countermeasures to synchronize.

Sync all Countermeasures

Synchronize all Countermeasures from SD Elements.

Sync Risk Policy Countermeasures

Synchronize only Countermeasures that fall under the risk policy.

Project details

Enter the project-level details.

Azure DevOps (TFS) Project

The name of the project where issues should be created.

Advanced Microsoft Azure DevOps configuration

Enter advanced global configuration options.

Issue Type

Type of issue that SD Elements will create when creating a Countermeasure in Azure DevOps. (Default: User Story)

Map an Azure DevOps (TFS) status to an SD Elements status

This mapping determines the status to assign an SD Elements Countermeasure based on its corresponding Azure DevOps issue status.

See Status Mapping for more information.

Map an SD Elements status to an Azure DevOps (TFS) status

This mapping determines the status to assign an Azure DevOps issue based on its corresponding SD Elements Countermeasure status. All Azure DevOps statuses in this mapping should be a single transition away from every other status in the mapping, as well as from the default status for new issues in your Azure DevOps project workflow. For example, an item in an "In Progress" state cannot be transitioned to an item in a "Completed" state. It must transition to a "Resolved" state first, then "Completed".

'Incomplete', 'Complete', and 'Not Applicable' SD Elements statuses must have a mapping. Any unmapped custom SD Elements statuses will use these mappings based on their meaning.

See Status Mapping for more information.

Unmapped Status Fallback (Optional)

The SD Elements status to map to when encountering an unmapped Azure DevOps status (Default: Incomplete)

Closed Issue Status

The name of a status in Azure DevOps to use when its corresponding SD Elements Countermeasure is removed from the project.

Enter advanced project configuration options.

Iteration Path

Name of the iteration (Example: Iteration\ABC)

If you create a new release and select the “Carry over Issue Tracker connections” option, you must manually edit the iteration path to ensure synchronization does not overwrite Countermeasures in your previous Microsoft Azure DevOps iteration.*

Area Path

Name of the Area Path (Default: Project name)

Synchronization

Enter settings for synchronizing SD Elements Countermeasures.

Authoritative Source

Select the tool that will be the authoritative system of record: Microsoft Azure DevOps or SD Elements. This field is used in case of conflicting statuses between the Microsoft Azure DevOps issue and the SD Elements Countermeasure. When you first synchronize a TODO Countermeasure in SD Elements with an issue in Microsoft Azure DevOps, they will have the same status. If you then change the status in one tool, for example by closing the issue in Microsoft Azure DevOps, they will have conflicting statuses. This conflict is resolved when the projects are synchronized. There are three options:

  • Issue Tracker (default): The SD Elements Countermeasure will be updated to match the status in Microsoft Azure DevOps.

  • SD Elements: The Microsoft Azure DevOps status will be updated to match the SD Elements status.

  • Last Status Change: The SD Elements and Azure DevOps states will always reflect the latest updated status. For example, if an Azure DevOps issue is most recently updated then the SD Elements Countermeasure status will be updated to reflect the Azure DevOps status. The opposite is also true.

Include code sample How-To’s in Countermeasure descriptions

Whether or not to include detailed code samples and How-To’s in the Microsoft Azure DevOps issue.

This Issue Tracker server is hosted within a private network and cannot be reached directly by SD Elements.

Select this option if SD Elements does not have direct network access to the Microsoft Azure DevOps server.

For example, if you are using a hosted SD Elements instance but you want to integrate with an internal/protected Microsoft Azure DevOps system, choose this option and run the Remote Integration Agent to perform integration.

Filter Countermeasures

Select SD Elements Countermeasures to synchronize with the Microsoft Azure DevOps project.

Countermeasures having a minimum priority

Only synchronize Countermeasures with a minimum priority, such as 7 or above. This is useful if you want to limit the amount of work for users. (Default: 1)

Countermeasures with status meaning

Only synchronize Countermeasures with certain statuses, such as TODO or DONE. (Default: TODO)

Limit to Countermeasures having these phases

Only synchronize Countermeasures in certain phases, such as Requirements or Development. (Default: none selected, meaning Countermeasures from all phases will be synchronized)

Countermeasures having all of the following tags

Only synchronize Countermeasures containing certain SD Elements Countermeasure tags. (Optional)

Countermeasures with verification status

Only synchronize Countermeasures with a specific verification status, such as Pass or Fail. (Default: none selected, meaning Countermeasures with any verification status will be synchronized)

Advanced Issue Tracker options

Enter advanced configuration options.

Enforce Certificate Validation

Checks the certificate of the server when SD Elements connects to it (Default: on). Turn it off only for testing, because it is insecure. OAuth 2.0 (Microsoft Entra ID) needs it on.

Issue Tracker context

Bind a set of Countermeasures using a cetain value. This is applicable only when custom titles are selected having the entry "Context"

Issue Tracker parent issue

The issue identifier of a parent issue. SD Elements Countermeasures will be created as children of this issue.

Custom Priority Mapping

If the standard Microsoft Azure DevOps priorities have been customized, you must map the customized priority names in Microsoft Azure DevOps to their corresponding SD Elements numeric priorities.

This is a common option that will need to be set.

For example, map "1" issues to priority 10 in SD Elements, "2" to priorities 7-9, and so on.

Custom Fields Mapping

In addition to the default-assigned fields, you can map additional SD Elements fields to Microsoft Azure DevOps fields.

Fields that are not required or have default values do not need to be set.

For example, you may have a required field in your Microsoft Azure DevOps project that is not set by default. Custom field mappings can be set at both the system connection and project connection levels, and the mappings set in a project connection will override mappings set in the system connection.

For more details refer to section Advanced field support.

Sync frequency

Select how frequently the SD Elements and Microsoft Azure DevOps projects are synchronized. You can choose from the following options. The more frequently you run synchronization, the greater the performance impact on both the SD Elements and Microsoft Azure DevOps servers. This is generally only a concern for large organizations running many synchronizations at once.

Hourly, Daily, Weekly, or Monthly

The projects will synchronize automatically every hour, day, week or month. Daily synchronization is typically sufficient. However, you may want to select a more frequent interval if development moves quickly in your organization.

Manually

You must click the Sync button on the Issue Tracker Integrations page in order to synchronize the projects. This is the default value.

results matching ""

    No results matching ""