Compatibilidad con proyectos públicos mediante extensiones de Azure DevOps Services

Artículo
07/20/2023

Azure DevOps Services

Antes del soporte técnico del proyecto público, todos los proyectos de Azure DevOps Services eran privados. Los proyectos privados solo autenticaron a los usuarios con acceso al proyecto, por lo que el público no pudo ver ni interactuar con él. Un proyecto público permite a los usuarios que no son miembros ver el contenido de ese proyecto en un estado de solo lectura.

Un usuario no miembro es anónimo (no autenticado en Azure DevOps Services) o público (se autentican en Azure DevOps Services, pero no pertenecen a la organización).

Los usuarios que no son miembros suelen ver las mismas vistas que los usuarios autenticados, pero la funcionalidad no pública está oculta o deshabilitada. Un ejemplo de funcionalidad no pública, como la configuración y las acciones, incluye una compilación de cola.

Nota:

Azure DevOps Services compatibilidad con proyectos públicos se encuentra actualmente en versión preliminar limitada. Póngase en contacto con vsts-public@microsoft.com si está interesado en desarrollar extensiones que admitan proyectos públicos. Para obtener más información sobre los proyectos públicos, consulte Azure DevOps Services versión preliminar limitada de proyectos públicos.

Decidir si una extensión es visible para los usuarios que no son miembros

Como desarrollador de extensiones, puede hacer que toda o parte de la extensión esté disponible para los usuarios que no son miembros. Estos usuarios solo pueden usar la extensión desde un proyecto público. Si decide no hacer que la extensión esté disponible para los usuarios que no son miembros, no se requiere ningún cambio y no hay ningún impacto en los miembros, si usan la extensión desde un proyecto público.

Use esta lista de comprobación para ayudar a decidir si debe hacer que la extensión esté disponible para los usuarios que no son miembros:

Los datos presentados por la extensión son relevantes para los usuarios que no son miembros
La extensión contribuye a las funcionalidades en el nivel de proyecto
La extensión contribuye a las áreas del producto a las que pueden acceder los usuarios que no son miembros
La extensión no amplía ni depende de las características que no están disponibles para los usuarios que no son miembros, por ejemplo, el servicio de datos o ciertas API rest de Azure DevOps Services. Para más información, consulte la sección Limitaciones de este artículo.

Visibilidad de la contribución

De forma predeterminada, las contribuciones solo son visibles para los miembros de la organización. Para proporcionar visibilidad a los usuarios que no son miembros de una contribución, establezca el restrictedTo atributo en esa contribución. El valor es una matriz de cadenas que enumera qué tipos de usuarios deben tener visibilidad para la contribución. Los valores posibles son:

member un usuario autenticado que es miembro de la organización
public un usuario autenticado que no es miembro de la organización
anonymous un usuario no autenticado

Ejemplo: hacer que un centro sea visible para usuarios anónimos, públicos y miembros

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

También puede establecer la visibilidad predeterminada para todas las contribuciones de la extensión estableciendo el restrictedTo atributo en la raíz del manifiesto de extensión. A continuación, puede invalidar este valor predeterminado en contribuciones individuales.

Ejemplo: hacer todas las contribuciones, excepto para una, visibles para todos los usuarios

{
    "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": {  
                ...              
            }
        }            
    ]
}

Limitaciones

Si desea que algunos o todos los aspectos de su contribución estén disponibles para los usuarios públicos, tenga en cuenta las siguientes limitaciones.

Métodos del SDK de VSS

El script principal del SDK, VSS.SDK.js, permite que las extensiones web se comuniquen con el marco primario para realizar operaciones como inicializar la comunicación y obtener información de contexto sobre el usuario actual. No se admiten los siguientes métodos del SDK de VSS para usuarios que no son miembros:

VSS.getAccessToken()
VSS.getAppToken()

Servicio de datos de extensión

Dado que los datos administrados por el servicio de datos de extensión no tienen ámbito ni están protegidos para un proyecto, los usuarios que no son miembros no pueden leer ni escribir ningún tipo de datos de extensión.

Ejemplo: control de errores de acceso a datos

Si el servicio de datos no puede acceder al servicio de datos debido a las limitaciones de permisos por parte del usuario que realiza la llamada, se rechaza la promesa devuelta de la llamada a getValue . El error pasado a la función reject tiene un nombre, que puede ayudarle a comprender por qué la llamada no pudo leer o escribir datos.

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

API de REST

Hay disponible un conjunto limitado de API REST de Azure DevOps Services para usuarios que no son miembros. Estas API incluyen la mayoría de las API de nivel de organización y de nivel de proyecto para las características que no están disponibles para los usuarios que no son miembros en general. Tenga en cuenta esta información cuando decida si quiere que la extensión esté disponible para los usuarios que no son miembros.

Se recomienda usar la versión 5.0 y las API posteriores, ya que determinadas API solo están disponibles para usuarios que no son miembros a partir de la versión 5.0.

Referencias de identidad

La mayoría de las API REST de Azure DevOps Services usan un "contrato" común para representar a un usuario o grupo. Para proteger la información de los miembros, como las direcciones de correo electrónico, cuando un usuario anónimo o público invoca una API REST, se omiten determinados campos, como uniqueName .

Comprobación de los permisos de usuario

Use permisos para decidir si desea exponer o habilitar una funcionalidad en la extensión. La API rest de seguridad se usa desde el código de extensión web para comprobar si el usuario actual tiene permiso en Azure DevOps Services para completar la tarea. De este modo, el usuario no cree que tiene permiso para hacer algo, solo para encontrar que no lo hacen.

Ejemplo: comprobación de si el usuario tiene permiso para las compilaciones de cola

En este ejemplo se muestra cómo usar el cliente REST de seguridad para comprobar si el usuario tiene permisos para poner en cola compilaciones en el proyecto actual. De forma predeterminada, los usuarios que no son miembros no tienen este permiso.

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);
  });
});

Al igual que otros tipos de contribuciones, la visibilidad de las contribuciones del widget de panel se controla con la restrictedTo propiedad de contribución. Por ejemplo, para que un widget sea visible para los usuarios que no son miembros y miembros:

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

Al controlar la visibilidad del widget a los usuarios que no son miembros, el marco del panel también proporciona un mecanismo de almacenamiento opcional de formato abierto para la configuración del widget. Hay dos mecanismos disponibles para indicar si la configuración del widget está disponible para su uso por parte de usuarios que no son miembros en proyectos públicos.

Un widget con opciones de configuración configurables que sean visibles para los usuarios que no son miembros debe seguir uno de los siguientes patrones. Al no hacerlo, se impide que el widget se desuse a estos usuarios.

Establezca la propiedad de contribución del canStoreCrossProjectSettings widget en false, lo que indica que la configuración del widget es específica del proyecto.

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

Las instancias de widget individuales también pueden indicar que su configuración es específica del proyecto y está disponible para los usuarios que no son miembros. Al guardar la configuración, el widget debe establecer en hasCrossProjectSettingsfalse en la cadena JSON con cadenas:

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

Consideraciones de compilación y versión

Si la extensión contribuye a una tarea de compilación o versión, no se requiere ningún cambio para usar esa tarea desde una canalización en un proyecto público.

Consideraciones de seguimiento de elementos de trabajo

Las extensiones no funcionan para los usuarios que no son miembros en el contexto de un proyecto público sin cambios. Esto incluye el formulario de elemento de trabajo, otras experiencias de elemento de trabajo o la interacción con las API REST de seguimiento de elementos de trabajo.

Formulario de elemento de trabajo

Todas las actualizaciones o eliminaciones de elementos de trabajo producen un error en los usuarios que no son miembros.

Identities

En Azure DevOps Services API REST versión 5.0 y posteriores, las identidades se devuelven como IdentityRef objetos en lugar de cadenas. Como se ha descrito anteriormente, ciertos campos, como uniqueName no se devuelven en estos objetos si un usuario que no es miembro realizó la llamada a la API.

API existentes

Solo una extensión puede invocar las API REST con ámbito de proyecto cuando el usuario actual no es miembro de la organización. Se rechazan todas las llamadas API REST que no tienen como ámbito un proyecto.

Consultas

Existen las siguientes limitaciones para los usuarios que no son miembros relacionados con las consultas de elementos de trabajo:

Los usuarios que no son miembros pueden ejecutar consultas conocidas por identificador o ruta de acceso
Las consultas deben tener como ámbito el proyecto actual. Se excluyen todos los elementos de trabajo que no pertenezcan al proyecto actual.
El usuario que no es miembro no puede crear nuevas consultas ni ejecutar consultas WIQL