Développer des extensions pour des projets publics

Azure DevOps Services

Azure DevOps Services prend en charge les projets privés et publics. Les projets privés limitent l’accès aux utilisateurs authentifiés disposant d’autorisations explicites. Les projets publics permettent aux utilisateurs non membres d’afficher le contenu du projet dans un état en lecture seule.

Un utilisateur non membre peut être :

• Anonyme : non authentifié auprès d’Azure DevOps Services
• Public : Authentifié auprès d’Azure DevOps Services, mais n'est pas membre de l’organisation

Les utilisateurs non membres authentifiés voient la même interface que les utilisateurs authentifiés, mais Azure DevOps masque ou désactive les fonctionnalités non publiques telles que les paramètres, les actions et les opérations de la file d'attente des builds.

Décider s’il faut rendre une extension visible pour les utilisateurs non membres

En tant que développeur d’extensions, vous pouvez rendre tout ou partie de votre extension disponible pour les utilisateurs non membres. Ces utilisateurs peuvent uniquement utiliser votre extension à partir de projets publics. Si vous choisissez de ne pas rendre votre extension disponible pour les utilisateurs non membres, vous n’avez pas besoin de modifications et la décision n’a aucun impact sur les membres qui utilisent votre extension dans les projets publics.

Utilisez cette liste de contrôle pour déterminer si vous devez rendre votre extension disponible pour les utilisateurs non membres :

Configurer la visibilité des contributions

Par défaut, Azure DevOps affiche uniquement les contributions aux membres de l’organisation. Pour donner une visibilité aux utilisateurs non membres d’une contribution, définissez l’attribut restrictedTo sur cette contribution. La valeur est un tableau de chaînes qui répertorie les types d’utilisateurs qui doivent voir la contribution. Les valeurs possibles sont les suivantes :

• member: utilisateur authentifié membre de l’organisation
• public: utilisateur authentifié qui n’est pas membre de l’organisation
• anonymous: utilisateur non authentifié

Rendre un hub visible par les utilisateurs anonymes, publics et membres

{
    "contributions": [
        {
            "id": "my-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-code-web.code-hub-group"
            ],
            "restrictedTo": [
                "member",
                "public",
                "anonymous"
            ],
            "properties": {
                ...            
            }
        }
    ]
}

Vous pouvez également définir la visibilité par défaut de toutes les contributions de votre extension en définissant l’attribut restrictedTo à la racine de votre manifeste d’extension. Vous pouvez ensuite remplacer cette valeur par défaut sur les contributions individuelles.

Rendre toutes les contributions, à l’exception d’une, visibles à tous les utilisateurs

{
    "id:": "my-extension",
    "name": "My Extension",
    "version": "1.0.0",
    ...
    "restrictedTo": [
           "anonymous",
           "public",
           "member"
    ],
    "contributions": [
        {
            "id": "my-member-only-widget",
            "type": "ms.vss-dashboards-web.widget",
            "restrictedTo": [
                "member"
            ],
            "properties": {
                ...
            }
        },
        {
            "id": "my-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-code-web.code-hub-group"
            ],
            "properties": {  
                ...              
            }
        },
        {
            "id": "my-second-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-work-web.work-hub-group"
            ],
            "properties": {  
                ...              
            }
        }            
    ]
}

Comprendre les limitations pour les utilisateurs non membres

Si vous souhaitez rendre certaines ou toutes les aspects de votre contribution à la disposition des utilisateurs publics, tenez compte des limitations suivantes.

Restrictions de méthode du Kit de développement logiciel (SDK) VSS

Le script du Kit de développement logiciel (SDK) principal, VSS.SDK.js, permet aux extensions web de communiquer avec l’image parente pour effectuer des opérations telles que l’initialisation de la communication et l’obtention d’informations de contexte utilisateur actuelles. Les méthodes du Kit de développement logiciel (SDK) VSS suivantes ne prennent pas en charge les utilisateurs non membres :

• VSS.getAccessToken()
• VSS.getAppToken()

Limitations du service de données d’extension

Étant donné que le service de données d’extension gère les données qui ne sont pas délimitées ou sécurisées pour un projet, les utilisateurs non membres ne peuvent pas lire ou écrire n’importe quel type de données d’extension.

Gérer les erreurs d’accès aux données

Lorsque le service de données ne peut pas accéder aux données en raison de limitations d’autorisation par l’utilisateur appelant, la promesse retournée par l'appel à getValue est rejetée. L’erreur passée à la fonction de rejet a une propriété de nom, ce qui vous permet de comprendre pourquoi l’appel n’a pas pu lire ou écrire des données.

VSS.getService(VSS.ServiceIds.ExtensionData).then(function(dataService) {
    dataService.getValue("someKey").then(function(value) {
         // Process the value
    }, function(error) {
       if (error.name === "AccessCheckException") {
           alert(error.message);
       }
    });
});

Accès à l’API REST

Azure DevOps Services fournit un ensemble limité d’API REST aux utilisateurs non membres. Ces API incluent la plupart des API au niveau de l’organisation et des API au niveau du projet pour les fonctionnalités auxquelles les utilisateurs non membres peuvent généralement accéder. Tenez compte de ces informations lorsque vous décidez s’il faut mettre votre extension à la disposition des utilisateurs non membres.

Nous vous recommandons d’utiliser les API 5.0 et ultérieures, car Azure DevOps rend certaines API disponibles pour les utilisateurs non membres uniquement à partir de la version 5.0.

Références d’identité

La plupart des API REST Azure DevOps Services utilisent un « contrat » commun pour représenter un utilisateur ou un groupe. Pour protéger les informations de membre, telles que les adresses e-mail, Azure DevOps omet certains champs, par exemple uniqueName, lorsqu’un utilisateur anonyme ou public appelle une API REST.

Vérifiez les autorisations de l’utilisateur

Utilisez des autorisations pour décider s’il faut exposer ou activer une fonctionnalité dans votre extension. Utilisez l’API REST de sécurité à partir du code d’extension web pour vérifier si l’utilisateur actuel dispose d’autorisations dans Azure DevOps Services pour effectuer la tâche. Cette approche empêche les utilisateurs de penser qu’ils ont l’autorisation de faire quelque chose, uniquement pour découvrir qu’ils ne le font pas.

Vérifier si l’utilisateur a l’autorisation de mettre en file d’attente les builds

Cet exemple montre comment utiliser le client REST de sécurité pour vérifier si l’utilisateur dispose des autorisations nécessaires pour mettre en file d’attente les builds dans le projet actuel. Par défaut, les utilisateurs non membres n’ont pas cette autorisation.

VSS.require(["VSS/Service", "VSS/security/RestClient"], function(VSS_Service, Security_RestClient) {
   var client = VSS_Service.getCollectionClient(Security_RestClient.SecurityHttpClient3);
 
   var securityToken = VSS.getWebContext().project.id;
 
   client.hasPermissionsBatch({
    evaluations: [
       {
           "securityNamespaceId": "33344D9C-FC72-4d6f-ABA5-FA317101A7E9",
           "token": securityToken,
           "permissions": 128 /* queue builds */
       }
    ],
    alwaysAllowAdministrators: true
}
).then(function(response) {
     console.log("Can user queue builds in this project? " + response.evaluations[0].value);
  });
});

Prendre en compte les exigences du widget de tableau de bord

Tout comme d’autres types de contributions, la restrictedTo propriété de contribution contrôle la visibilité des contributions du widget de tableau de bord. Par exemple, pour rendre un widget visible à la fois pour les utilisateurs non membres et membres :

{
  "contributions": [
    {
      "id": "HelloWorldWidget",
      "type": "ms.vss-dashboards-web.widget",
      "targets": [
        "ms.vss-dashboards-web.widget-catalog"
      ],
      "restrictedTo": [
        "member",
        "public",
        "anonymous"
      ],
      "properties": {
          ...
      }
    }
  ]
}

Configurer les paramètres du widget

Lorsque vous contrôlez la visibilité des widgets pour les utilisateurs non membres, l’infrastructure de tableau de bord fournit également un mécanisme de stockage de formulaire ouvert facultatif pour les paramètres du widget. Deux mécanismes indiquent si les paramètres de widget sont disponibles pour les utilisateurs non membres dans les projets publics.

Un widget avec des paramètres configurables visibles pour les utilisateurs non membres doit suivre l’un des modèles suivants. Le fait de ne pas suivre ces modèles empêche le widget d’apparaître à ces utilisateurs.

Modèle 1 : le widget déclare que ses instances ne stockent que les paramètres spécifiques au projet.

Définissez la propriété canStoreCrossProjectSettings de la contribution du widget sur false, indiquant que les paramètres du widget sont spécifiques au projet.

{
    "id:": "HelloWorldWidget",
    "type": "ms.vss-dashboards-web.widget",
    ...
    "properties": {
        "canStoreCrossProjectSettings": false
    }
}

Modèle 2 : une instance de widget déclare que ses paramètres sont spécifiques au projet

Les instances de widget individuelles peuvent également indiquer que leurs paramètres sont spécifiques au projet et disponibles pour les utilisateurs non membres. Lors de l’enregistrement des paramètres, le widget doit être défini hasCrossProjectSettingsfalse sur la chaîne JSON stringified :

{
    "hasCrossProjectSettings": false,
    "hypotheticalWidgetOption": true,
    "backlogLevel": "Stories"
}

Prendre en compte les exigences de génération et de mise en production

Si votre extension contribue à une tâche de build ou de mise en production, vous n’avez pas besoin d’apporter de modifications pour utiliser cette tâche à partir d’un pipeline dans un projet public.

Gérer les considérations relatives au suivi des éléments de travail

Les extensions ne fonctionnent pas pour les utilisateurs non membres dans le contexte d’un projet public sans modification. Cela inclut le formulaire d’élément de travail, d’autres expériences d’élément de travail et l’interaction avec les API REST de suivi des éléments de travail.

Limitations du formulaire d’élément de travail

Azure DevOps échoue toutes les mises à jour ou suppressions d’éléments de travail pour les utilisateurs non membres.

Gestion des identités

Dans l’API REST Azure DevOps Services version 5.0 et ultérieure, le service retourne des identités en tant qu’objets IdentityRef au lieu de chaînes. Comme décrit précédemment, Azure DevOps ne retourne pas certains champs, tels que uniqueName, dans ces objets si un utilisateur non membre effectue l’appel d’API.

Restrictions d’étendue d’API

Les extensions peuvent appeler uniquement les API REST délimitées par le projet lorsque l’utilisateur actuel n’est pas membre de l’organisation. Azure DevOps rejette les appels d’API REST non limités à un projet.

Limitations des requêtes

Les utilisateurs non membres sont confrontés aux limitations suivantes liées aux requêtes d’élément de travail :

• Les utilisateurs non membres peuvent exécuter des requêtes connues par ID ou chemin d’accès uniquement
• Les requêtes doivent être étendues au projet actuel. Azure DevOps exclut tous les éléments de travail qui n’appartiennent pas au projet actuel
• Les utilisateurs non membres ne peuvent pas créer de requêtes ou exécuter des requêtes WIQL

Contenu connexe

• Stockage des données d’extension
• Informations de référence sur l’API REST Azure DevOps Services
• Vue d’ensemble des projets publics
• Référence du manifeste d’extension