Conectarse a API protegidas por Azure AD en soluciones de SharePoint Framework

Artículo
04/08/2023

Al compilar soluciones de SharePoint Framework, es posible que tenga que conectarse a una API protegida mediante Azure Active Directory (Azure AD). SharePoint Framework permite especificar qué aplicaciones y permisos de Azure AD necesita la solución, y un administrador global o de SharePoint puede conceder los permisos necesarios si aún no se les ha concedido. Con AadHttpClient, puede conectarse fácilmente a las API protegidas mediante Azure AD sin tener que implementar el flujo de OAuth usted mismo.

Información general sobre los permisos de la API web

Azure AD protege diferentes recursos: desde Office 365 en sí, hasta aplicaciones de línea de negocio personalizadas creadas por la organización. Para conectarse a estos recursos, las aplicaciones necesitan obtener un token de acceso válido que les conceda acceso al recurso específico. Las aplicaciones pueden obtener un token de acceso como parte del flujo de autorización de OAuth.

Las aplicaciones del lado cliente (como las soluciones de SharePoint Framework) que no pueden almacenar un secreto usan un tipo específico de flujo de OAuth denominado flujo implícito de OAuth.

Los desarrolladores que creen soluciones del lado cliente son responsables de implementar la autorización con el flujo implícito de OAuth en la aplicación. En las soluciones de SharePoint Framework, esa tarea ya se realiza como parte del marco con MSGraphClient y AadHttpClient, que se introdujeron en SharePoint Framework versión 1.4.1.

Nota:

Si crea soluciones con una versión de SharePoint Framework anterior a la versión 1.4.1, aún podrá conectarse a los recursos protegidos con Azure AD. En este caso, debe implementar el flujo implícito de OAuth mediante el uso directo de bibliotecas de autenticación platfomr de identidad de Microsoft. Para obtener más información, vea el artículo Conectarse a una API protegida con Azure Active Directory.

Como parte de SharePoint Framework, hay un proceso específico que define cómo los desarrolladores pueden solicitar permisos y cómo los administradores pueden administrar los permisos a los recursos protegidos con Azure AD. En el esquema siguiente, se muestra este proceso.

Esquema donde se muestra el flujo de solicitar, conceder y usar permisos para aplicaciones de Azure AD

Los desarrolladores que creen una solución de SharePoint Framework y que necesiten obtener acceso a recursos específicos protegidos con Azure AD pueden mostrar una lista de estos recursos, además de los ámbitos de permiso necesarios, en el manifiesto de la solución. Al implementar el paquete de solución en el Catálogo de aplicaciones, SharePoint creará solicitudes de permisos y pedirá al administrador que administre los permisos solicitados. Por cada permiso solicitado, el Administrador de SharePoint o global puede decidir si desea conceder o denegar cada permiso específico.

Todos los permisos se conceden en el espacio empresarial, no en la aplicación específica que lo solicitó. Cuando el administrador concede un permiso específico, se agrega a la aplicación de Azure AD SharePoint Online Client Extensibility que Microsoft aprovisiona en todos los entornos de Azure AD y que SharePoint Framework usa en el flujo de OAuth para proporcionar soluciones con tokens de acceso válidos.

Descubrir permisos y aplicaciones disponibles

El entorno de Azure AD de destino que protege el espacio empresarial de Office 365 determina a qué aplicaciones puede solicitar permisos en la solución. La lista de aplicaciones disponibles puede depender de la licencia de Office 365 que use la organización y de las aplicaciones de línea de negocio registradas en su entorno de Azure AD. Si tiene permisos suficientes, hay distintas formas en las que puede ver los ámbitos de permiso y aplicaciones que están disponibles en el espacio empresarial.

Usar Azure Portal o el Centro de administración de Azure AD

Una forma de ver las aplicaciones disponibles en Azure AD es navegar a Azure Portal o al Centro de administración de Azure AD.

En el Centro de administración de Azure AD, en el panel de navegación izquierdo, seleccione el vínculo Aplicaciones empresariales.
En la hoja Aplicaciones empresariales, en el grupo Administrar, seleccione el vínculo Todas las aplicaciones.
Para encontrar rápidamente la aplicación a la que quiera conectarse, puede filtrar la lista por tipo de aplicación (Aplicaciones de Microsoft o Aplicaciones empresariales), o bien puede buscar por su nombre o id.

Por ejemplo, para solicitar permisos adicionales para Microsoft Graph, escriba “graph” en el cuadro de búsqueda.
Cuando encuentre la aplicación, selecciónela para obtener más información. En la hoja de aplicaciones, en el grupo Administrar, seleccione Propiedades para abrir las propiedades de la aplicación.
En la lista de propiedades, copie el valor de la propiedad Id. de objeto, ya que lo necesitará para solicitar ámbitos de permiso adicionales para Microsoft Graph. En su lugar, puede copiar el Nombre de la aplicación y usarlo en la solicitud de permiso.

Nota:

Aunque el id. de objeto es único para cada espacio empresarial, el Nombre de la aplicación es el mismo en todos los espacios empresariales. Para crear una solución e implementarla en diferentes espacios empresariales, tiene que usar el Nombre de la aplicación al solicitar permisos adicionales en la solución.

Usar Azure PowerShell

Nota:

Antes de ejecutar los pasos siguientes, necesita instalar Azure PowerShell. Como alternativa, puede ejecutar los cmdlets mencionados en esta sección en el entorno de PowerShell de Azure Cloud Shell.

Para empezar, inicie sesión en su suscripción de Azure, ejecutando este comando en PowerShell (esto no es necesario si usa Azure Cloud Shell):
```
Login-AzureRmAccount
```
Después, escriba lo siguiente para mostrar la lista de aplicaciones disponibles en el espacio empresarial:
```
Get-AzureRmADServicePrincipal | sort DisplayName | ft DisplayName, Id
```
Al ejecutar este cmdlet, se muestra una lista de todas las aplicaciones disponibles en el espacio empresarial. Por cada aplicación, se muestra el nombre para mostrar y el id. de objeto, que puede usar en una solución de SharePoint Framework para solicitar permisos de aplicación.

Usar la CLI de Azure

Nota:

Antes de ejecutar los pasos siguientes, necesita instalar la CLI de Azure. Como alternativa, puede ejecutar la CLI de Azure desde Azure Cloud Shell o como un contenedor de Docker.

Si ejecuta la CLI en un equipo o en un contenedor de Docker, ejecute este comando para conectarse a su suscripción de Azure AD:
```
azure login
```
Una vez conectado, ejecute el comando siguiente para mostrar todas las aplicaciones de Azure AD disponibles:
```
azure ad sp list --query "sort_by([*].{displayName: displayName, objectId: objectId}, &displayName)" -o table
```
Al ejecutar este comando, se mostrará una lista de todas las aplicaciones de Azure AD disponibles en el espacio empresarial, ordenadas por displayName. Por cada aplicación, el comando mostrará los valores de displayName y objectId. Además, el resultado tendrá un formato de tabla.

Obtener la lista de ámbitos de permiso expuestos por la aplicación

Cada aplicación de Azure AD expone diferentes ámbitos de permiso. Con frecuencia, estos ámbitos de permiso están relacionados con recursos u operaciones específicos dentro de la aplicación. Para obtener la lista de permisos disponibles para la aplicación, conéctese a su documentación o consúltela. Para obtener la lista de ámbitos de permiso disponibles en Microsoft Graph, vea Referencia de permisos de Microsoft Graph.

Solicitar permisos a una aplicación de Azure AD

Si la solución de SharePoint Framework necesita permisos para recursos específicos protegidos con Azure AD (como Microsoft Graph o aplicaciones empresariales), puede especificar estos recursos, además de los permisos necesarios, en la configuración de la solución.

En el proyecto de SharePoint Framework, abra el archivo config/package-solution.json.
En la propiedad solution, agregue la propiedad webApiPermissionRequests, que muestra una lista de todos los recursos y los permisos correspondientes que necesita la solución.

Este es un ejemplo de una solución de SharePoint Framework que solicita acceso para leer los calendarios de los usuarios con Microsoft Graph:
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}
```
Nota:

Para el valor de la propiedad resource, necesita especificar el valor de displayName de la aplicación para la que quiera solicitar permisos. Si especifica el recurso con su objectId, obtendrá un error al intentar aprobar la solicitud de permisos.

Para solicitar varios ámbitos de permiso para un recurso concreto, especifique cada ámbito en una entrada separada, como en el ejemplo siguiente:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "User.ReadBasic.All"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}

Cuando la solución se implemente en el Catálogo de aplicaciones de SharePoint, se le pedirá al administrador que compruebe los permisos solicitados y que los conceda o deniegue.

Nota:

No importa si el administrador rechaza o aprueba los permisos solicitados: la solución se podrá implementar y usar en los sitios. Al crear soluciones que necesitan permisos adicionales, nunca dé por hecho que se concedieron los permisos solicitados.

Administrar solicitudes de permisos

Al implementar las soluciones de SharePoint Framework que solicitan permisos a las aplicaciones de Azure AD, se les pide a los administradores que administren la solicitud de permiso proporcionada con la solución. Las solicitudes de permisos se pueden administrar de varias formas.

Administrar permisos en el nuevo Centro de administración de SharePoint

Para obtener información sobre cómo usar la página de acceso a la API en el nuevo Centro de administración de SharePoint, consulte Administrar el acceso a las API protegidas por Azure AD.

Administrar permisos con PowerShell

Los administradores de SharePoint y globales también pueden usar el Shell de SharePoint Online Management para administrar permisos y solicitudes de permisos en SharePoint Online.

Para ver todas las solicitudes de permisos pendientes, use el cmdlet Get-SPOTenantServicePrincipalPermissionRequests. Por cada solicitud de permiso, el cmdlet mostrará su id. (necesario para aprobar o denegar la solicitud), el recurso para el que se solicitaron los permisos, y los permisos solicitados.

Nota:

SharePoint no comprueba si los permisos solicitados ya se concedieron o no; por lo tanto, antes de aprobar o rechazar una solicitud de permiso, compruebe los permisos que se concedieron en el espacio empresarial.
Para aprobar la solicitud de permiso específica, use el cmdlet Approve-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid> , especificando el identificador de la solicitud de permiso que desea aprobar.

Nota:

Si intenta aprobar la solicitud de un permiso que ya se concedió, recibirá un error.
Para denegar una solicitud de permiso (si ya se ha concedido el permiso solicitado o si la solicitud está en contra de las directivas de la organización), use el cmdlet Deny-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid> , especificando el identificador de la solicitud de permiso que desea denegar.

Nota:

Aunque se deniegue una solicitud de permiso emitida por una aplicación de SharePoint Framework, esto no impide que esta aplicación se pueda implementar en el Catálogo de aplicaciones y se puede instalar en los sitios.
Para ver los permisos que se concedieron en el espacio empresarial, use el cmdlet Get-SPOTenantServicePrincipalPermissionGrants. Por cada concesión, el cmdlet mostrará la siguiente información:
- ClientId: el valor de objectId de la entidad de servicio a la que se proporcionó el consentimiento para suplantar al usuario al obtener acceso al recurso (representado por el valor de resourceId).
- ConsentType: indica si el administrador proporcionó el consentimiento en nombre de la organización, o bien si lo proporcionó un usuario. Los valores posibles son “AllPrincipals” o “Principal”.
- ObjectId: el identificador único de la concesión de permiso.
- Resource: el recurso para el que se concedió el acceso.
- ResourceId: el valor de objectId de la entidad de servicio de recursos para el que se concedió el acceso.
- Scope: el valor de la notificación de ámbito que la aplicación del recurso espera encontrar en el token de acceso de OAuth 2.0.
Para revocar un permiso concedido anteriormente, use el cmdlet Revoke-SPOTenantServicePrincipalPermission -ObjectId <String> . En el parámetro ObjectId, debe especificar el valor de objectId de la concesión que quiera revocar, el cual puede obtener con el cmdlet Get-SPOTenantServicePrincipalPermissionGrants.

Nota:

Al revocar un permiso, no se desencadena ningún cambio en el Catálogo de aplicaciones ni en ninguna de las aplicaciones implementadas. La única consecuencia de revocar un permiso es que cualquier aplicación usada en el espacio empresarial no podrá conectarse a los recursos cuyo permiso se revocó.

Administrar permisos con la CLI para Microsoft 365

Los administradores de SharePoint y globales pueden usar la CLI para Microsoft 365 para administrar permisos y solicitudes de permisos en SharePoint Online.

Nota:

La CLI de Microsoft 365 es una solución de código abierto con una comunidad activa que ofrece su soporte. No hay ningún contrato de nivel de servicio para el soporte de la herramienta de código abierto de Microsoft.

Para ver todas las solicitudes de permisos pendientes, use el comando spo serviceprincipal permissionrequest list. Por cada solicitud de permiso, el comando mostrará su id. (necesario para aprobar o denegar la solicitud), el recurso para el que se solicitaron los permisos, y los permisos solicitados.

Nota:

SharePoint no comprueba si los permisos solicitados ya se concedieron o no; por lo tanto, antes de aprobar o rechazar una solicitud de permiso, compruebe los permisos que se concedieron en el espacio empresarial.
Para aprobar una solicitud de permiso específica, use el comando spo serviceprincipal permissionrequest approve, y especifique el Id. de la solicitud de permiso que quiera aprobar.

Nota:

Si intenta aprobar la solicitud de un permiso que ya se concedió, recibirá un error.
Para denegar una solicitud de permiso (si el permiso solicitado ya se concedió o si la solicitud no cumple con las directivas de la organización) puede usar el comando spo serviceprincipal permissionrequest deny y especificar el Id. de la solicitud de permiso que quiera rechazar.

Nota:

Aunque se deniegue una solicitud de permiso emitida por una aplicación de SharePoint Framework, esto no impide que esta aplicación se pueda implementar en el Catálogo de aplicaciones y se puede instalar en los sitios.
Para ver los permisos que se concedieron en el espacio empresarial, use el comando spo serviceprincipal grant list. Por cada concesión, el comando mostrará la siguiente información:
- ObjectId: el identificador único de la concesión de permiso.
- Resource: el recurso para el que se concedió el acceso.
- ResourceId: el valor de objectId de la entidad de servicio de recursos para el que se concedió el acceso.
- Scope: el valor de la notificación de ámbito que la aplicación del recurso espera encontrar en el token de acceso de OAuth 2.0.
Para revocar un permiso concedido anteriormente, use el comando spo serviceprincipal grant revoke. En el parámetro grantId, debe especificar el valor de objectId de la concesión que quiera revocar, el cual puede obtener con el comando spo serviceprincipal grant list.

Nota:

Al revocar un permiso, no se desencadena ningún cambio en el Catálogo de aplicaciones ni en ninguna de las aplicaciones implementadas. La única consecuencia de revocar un permiso es que cualquier aplicación usada en el espacio empresarial no podrá conectarse a los recursos cuyo permiso se revocó.

Conectarse a aplicaciones de Azure AD con AadHttpClient

SharePoint Framework (presentado en la versión 1.4.1) simplifica la conexión a las API protegidas con Azure AD. Con el nuevo AadHttpClient, puede conectarse fácilmente a API protegidas con Azure AD, sin tener que implementar la autenticación y la autorización por su cuenta.

Internamente, AadHttpClient implementa el flujo de OAuth de Azure AD aprovechando Plataforma de identidad de Microsoft bibliotecas de autenticación mediante la entidad de servicio de extensibilidad de cliente de SharePoint Online para obtener un token de acceso válido. Microsoft aprovisiona la entidad de servicio SharePoint Online Client Extensibility, que está disponible en el entorno de Azure AD de todos los espacios empresariales de Office 365.

Para usar AadHttpClient en una solución de SharePoint Framework, agregue la siguiente cláusula import al archivo de elementos web principal:
```
import { AadHttpClient, HttpClientResponse } from '@microsoft/sp-http';
```

Cree una instancia de AadHttpClient y pase el recurso al que quiera conectarse con estos parámetros:

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        // connect to the API
      });
  }

  // ...
}

Nota:

Cada instancia de AadHttpClient está vinculada al recurso específico, que es el motivo por el que necesita crear una instancia del cliente por cada recurso al que quiera conectarse.

Después de crear una instancia de AadHttpClient para su recurso, puede emitir una solicitud web para comunicarse con la API; en este ejemplo, la API devuelve una lista de pedidos representada por la interfaz personalizada Order definida en otra ubicación del proyecto:

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        client
          .get('https://contoso.azurewebsites.net/api/orders', AadHttpClient.configurations.v1)
          .then((response: HttpClientResponse): Promise<Order[]> => {
            return response.json();
          })
          .then((orders: Order[]): void => {
            // process data
          });
      });
  }

  // ...
}

Consideraciones

Abajo encontrará algunas consideraciones que necesita tener en cuenta al trabajar con los permisos de API web.

Solicitar permisos con soluciones de SharePoint Framework

En este momento, solo se pueden solicitar permisos adicionales con una solución de SharePoint Framework. La solicitud se inicia cuando el paquete de solución (.sppkg) que contiene la solicitud de permisos se implementa en el catálogo de aplicaciones. Después de iniciarse la solicitud, el Administrador de SharePoint o global puede aprobarla o denegarla.

Los permisos concedidos se aplican en todas las soluciones

Aunque los permisos para los recursos de Azure AD se soliciten por una solución de SharePoint Framework, una vez concedidos, se aplican en todo el espacio empresarial y cualquier solución del espacio empresarial podrán usarlos.

Al quitar una solución, no se revocan los permisos

Al quitar la solución que solicitó inicialmente un permiso específico, no se revoca el permiso concedido. Los administradores deben revocar manualmente los permisos concedidos a través de las solicitudes de la aplicación SharePoint Framework.

Al revocar permisos concedidos anteriormente, no se invalidan los tokens de acceso emitidos

Al revocar los permisos concedidos anteriormente, no se invalidan los tokens de acceso emitidos a los usuarios. En su lugar, estos tokens de acceso seguirán siendo válidos hasta que expiren.

La solicitud de permisos no afecta a la implementación de soluciones

Aunque el administrador rechace o apruebe los permisos solicitados por la solución, la solución se podrá implementar y usar en sitios. Al crear soluciones que necesitan permisos adicionales, nunca dé por hecho que se concedieron los permisos solicitados.

Controlar la entidad de servicio del cliente de SharePoint Online

Todos los permisos concedidos con las solicitudes de API web se almacenan con la aplicación de Azure AD SharePoint Online Client Extensibility. Si los administradores no desean que los desarrolladores usen el modelo de solicitudes de API web, en el MSGraphClient ni AadHttpClient en sus soluciones, pueden deshabilitar la entidad de servicio SharePoint Online Client Extensibility a través de PowerShell mediante el cmdlet Disable-SPOTenantServicePrincipal.

Después, la entidad de servicio se puede volver a habilitar mediante el cmdlet Enable-SPOTenantServicePrincipal. En su lugar, también se puede habilitar y deshabilitar la entidad de servicio SharePoint Online Client Extensibility con la CLI para Microsoft 365 mediante el comando spo serviceprincipal set.

Compartir a través de

Conectarse a API protegidas por Azure AD en soluciones de SharePoint Framework

Información general sobre los permisos de la API web

Descubrir permisos y aplicaciones disponibles

Usar Azure Portal o el Centro de administración de Azure AD

Usar Azure PowerShell

Usar la CLI de Azure

Obtener la lista de ámbitos de permiso expuestos por la aplicación

Solicitar permisos a una aplicación de Azure AD

Administrar solicitudes de permisos

Administrar permisos en el nuevo Centro de administración de SharePoint

Administrar permisos con PowerShell

Administrar permisos con la CLI para Microsoft 365

Conectarse a aplicaciones de Azure AD con AadHttpClient

Consideraciones

Solicitar permisos con soluciones de SharePoint Framework

Los permisos concedidos se aplican en todas las soluciones

Al quitar una solución, no se revocan los permisos

Al revocar permisos concedidos anteriormente, no se invalidan los tokens de acceso emitidos

La solicitud de permisos no afecta a la implementación de soluciones

Controlar la entidad de servicio del cliente de SharePoint Online

Recursos adicionales