Utilizar API de empresa protegidas con Azure AD en SharePoint Framework

Este artículo muestra cómo conectarse a una API de empresa protegida con Azure Active Directory desde una solución de SharePoint Framework. Trata sobre cómo crear y proteger la API, pero también sobre cómo desarrollar la solución de SharePoint Framework.

Crear una API de empresa protegida con Azure AD

Empiece creando una API de empresa protegida con Azure Active Directory. Aunque no existen restricciones sobre cómo debe implementarse la API desde el punto de vista de SharePoint Framework, en este tutorial se crea la API mediante Azure Functions y se protege con la autenticación en Azure App Service.

Aunque es probable que su organización ya cuente con API específicas que muestran las aplicaciones, esta sección le ofrece una introducción completa de los pasos de implementación y configuración.

Crear una función de Azure

En Azure Portal, cree una nueva Function App.

Para más información sobre cómo crear Function Apps en Azure, visite el artículo de ayuda Crear una aplicación de función desde Microsoft Azure Portal.

Creará una nueva función desencadenada por HTTP en Function App. En este ejemplo, creará la función utilizando C#, pero por lo general no existen restricciones con respecto al lenguaje de programación que debe usar.

En la aplicación de función, presione el botón Nueva función:

En la lista de plantillas, seleccione desencadenador HTTP:

En el panel Nueva función, especifique el nombre de la función, establezca el Nivel de autorización en Anónimo y haga clic en el botón Crear:

Las Azure Functions pueden protegerse de varias maneras. Dado que quiere proteger la función con Azure AD, y no la función en sí, tendrá que proteger la Function App subyacente. Es por eso que, en este momento, se decide no proteger la función en sí. La configuración de autenticación que se aplica a Function App se aplica a todas las funciones dentro de esa aplicación.

Una vez creada la función, reemplace el contenido por el fragmento de código siguiente:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    return (ActionResult)new OkObjectResult(new List<object> {
        new {
            Id = 1,
            OrderDate = new DateTime(2016, 1, 6),
            Region = "east",
            Rep = "Jones",
            Item = "Pencil",
            Units = 95,
            UnitCost = 1.99,
            Total = 189.05
        },
        new {
            Id = 2,
            OrderDate = new DateTime(2016, 1, 23),
            Region = "central",
            Rep = "Kivell",
            Item = "Binder",
            Units = 50,
            UnitCost = 19.99,
            Total = 999.50
        },
        new {
            Id = 3,
            OrderDate = new DateTime(2016, 2, 9),
            Region = "central",
            Rep = "Jardine",
            Item = "Pencil",
            Units = 36,
            UnitCost = 4.99,
            Total = 179.64
        },
        new {
            Id = 4,
            OrderDate = new DateTime(2016, 2, 26),
            Region = "central",
            Rep = "Gill",
            Item = "Pen",
            Units = 27,
            UnitCost = 19.99,
            Total = 539.73
        },
        new {
            Id = 5,
            OrderDate = new DateTime(2016, 3, 15),
            Region = "west",
            Rep = "Sorvino",
            Item = "Pencil",
            Units = 56,
            UnitCost = 2.99,
            Total = 167.44
        }
    });
}

Compruebe que la función funciona correctamente. Para ello presione el botón Guardar y ejecutar:

Si la función se ejecuta correctamente, verá la etiqueta Estado: 200 OK y la lista de pedidos que aparece en el panel de pruebas.

Proteger la función de Azure

Ahora que la función de Azure funciona, el siguiente paso es protegerla con Azure Active Directory para que solo se pueda acceder a ella iniciando sesión con su cuenta profesional.

En la hoja de Function App del panel lateral, seleccione la aplicación de la función:

En la sección superior, vaya a la pestaña Características de la plataforma:

Después, vaya al grupo Red y seleccione el vínculo Autenticación y autorización:

En la hoja Autenticación y autorización, habilite la autenticación del App Service cambiando el botón de alternancia Autenticación del App Service a Activado:

En el menú desplegable Acción cuando la solicitud no se ha autenticado, cambie el valor a Inicio de sesión con Azure Active Directory. Esta configuración garantiza que no se conceda permiso a las solicitudes anónimas a la API:

A continuación, en la lista de proveedores de autenticación seleccione Azure Active Directory:

En la hoja Configuración de Azure Active Directory, establezca la opción Modo administración en Avanzado. Establezca la segunda opción de Modo administración en Crear nueva App de AD:

Importante

Antes de continuar, anote el valor que aparece en el campo Crear aplicación. Este valor representa el nombre de la aplicación de Azure AD que se usará para proteger la API y lo necesitará más adelante para solicitar permisos de acceso a la API del proyecto de SharePoint Framework.

Confirme la selección haciendo clic en Aceptar.

Una vez en la hoja Autorizaci?n/autenticaci?n, actualice la configuraci?n de autenticaci?n y autorizaci?n de la Function App haciendo clic en el bot?n Guardar:

Confirme que la API está protegida correctamente abriendo una nueva ventana del navegador en modo privado y yendo a la API. La URL de su Function App se puede encontrar en la secci?n Informaci?n general de la hoja de Function App. Si la configuración de autenticación se ha aplicado correctamente, se le redirigirá a la página de inicio de sesión de Azure AD:

Obtener un identificador de aplicación de Azure AD

Para solicitar un token de acceso para conectarse a la API, necesitará el identificador de la aplicación de Azure AD que se utiliza para proteger dicha API.

En Function App, vaya a la configuración de Autenticación. Si el vínculo Autenticación no está disponible bajo el encabezado Funciones configuradas, haga clic en el botón Actualizar junto a la Function App en el panel izquierdo:

Seleccione Azure Active Directory en la lista de proveedores de autenticación:

En la hoja Configuración de Azure Active Directory, presione el botón Administrar aplicaciones:

En la hoja de aplicación de Azure AD, copie el valor de la propiedad Application ID:

Habilitar CORS

Se llamará a Function App desde JavaScript, que se ejecuta en una página de SharePoint. Como la API no está hospedada en el mismo dominio que el portal de SharePoint, las restricciones de seguridad entre dominios se aplicarán a la llamada de la API. De forma predeterminada, no se puede llamar a las API implementadas con instancias de Function Apps de Azure desde otros dominios. Puede cambiar esto ajustando la configuración de CORS de Function App.

Importante

Si se est? autenticando con la API utilizando la cookie de SharePoint Online en lugar de OAuth, no puede cambiar la configuraci?n de CORS a trav?s de Azure Portal. Para que la autenticaci?n funcione, debe desactivar toda la configuraci?n de CORS en Azure Portal y especificarlas en su API.

En Function App, vaya a la pestaña Características de la plataforma.

Desde el grupo API, seleccione el vínculo CORS:

En la lista de orígenes permitidos, agregue la dirección URL de su espacio empresarial de SharePoint, por ejemplo, https://contoso.sharepoint.com:

Confirme los cambios presionando Guardar.

Utilizar la API de empresa protegida con Azure AD desde SharePoint Framework

Una vez que la API está configurada y funciona, el siguiente paso es crear la solución de SharePoint Framework que utilizará la API.

Antes de continuar, asegúrese de que ha instalado la versión 1.4.1 o posterior del generador de Yeoman de SharePoint Framework. Si tiene instalado el generador de forma global, puede comprobar la versión instalada ejecutando npm ls -g --depth=0 en la línea de comandos.

Crear un proyecto de SharePoint Framework

A continuaci?n, crear? un nuevo proyecto de SharePoint Framework para consumir la API.

En la línea de comandos, cree una nueva carpeta para el proyecto:

md contoso-api

Cambie el directorio de trabajo:

cd contoso-api

Para crear un proyecto nuevo, inicie el generador de Yeoman de SharePoint Framework:

yo @microsoft/sharepoint

Cuando se le pida, use los siguientes valores:

• ¿Cuál es el nombre de la solución? contoso-api
• ¿Qué paquetes de línea de base desea que se destinen al componente o los componentes? Solo SharePoint Online (versiones más recientes)
• ¿Dónde desea ubicar los archivos? Use la carpeta actual.
• ¿Desea permitir que el administrador de inquilinos pueda implementar la solución en todos los sitios inmediatamente sin ejecutar ninguna implementación de características ni agregar aplicaciones en sitios? Yes
• ¿Los componentes de la solución necesitarán permisos para acceder a las API web que son exclusivas y no se compartirán con otros componentes en el espacio empresarial?: No
• ¿Cuál es el tipo de componente del lado cliente que se va a crear? WebPart
• ¿Cómo se llama su elemento web? Pedidos
• ¿Cuál es la descripción del elemento web? Mostrar pedidos recientes
• ¿Qué marco desea utilizar? No es un marco de JavaScript

Una vez que se ha creado el proyecto, ábralo en un editor de código. En este tutorial, usará Visual Studio Code:

Solicitar permisos para la API de empresa

De forma predeterminada, SharePoint Framework no tiene acceso a las API de empresa, a pesar de estar registradas en el mismo Azure Active Directory que Office 365. Esto es por motivos de diseño y permite a las organizaciones escoger conscientemente las API que se exponen a las secuencias de comandos y las soluciones por parte del cliente implementadas en SharePoint. Para acceder a sus API de empresa, deberá emitir una solicitud de permiso desde el proyecto de SharePoint Framework que está creando.

En el editor de código, abra el archivo config/package-solution.json:

En la propiedad solution, agregue una nueva propiedad denominada webApiPermissionRequests que haga referencia a la aplicación de Azure AD utilizada para proteger la API:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "contoso-api-client-side-solution",
    "id": "8cbc01fb-bab6-48fc-afec-2c2053759771",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "webApiPermissionRequests": [
      {
        "resource": "contoso-api-dp20191109",
        "scope": "user_impersonation"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/contoso-api.sppkg"
  }
}

El valor de la propiedad resource debe hacer referencia al nombre de la aplicación de Azure AD que se utiliza para proteger la API. El valor de la propiedad scope especifica el ámbito de permisos que necesita su solución para comunicarse con la API. En este tutorial, Azure AD se usa solo para proteger la API, por lo que el ámbito que se usará es user_impersonation.

Nota:

Si quiere conectarse a una API de empresa creada anteriormente, póngase en contacto con su administrador para que le proporcione los datos de la aplicación de Azure AD utilizada para protegerla. Necesitará información como el identificador de la aplicación, los permisos que muestra la aplicación y el público para el que ha sido configurada.

Conéctese a la API de empresa

La última parte del proceso es implementar la conexión a la API de empresa.

En el editor de código, abra el archivo src\webparts\orders\OrdersWebPart.ts:

En la sección superior del archivo, haga referencia a las clases AadHttpClient y HttpClientResponse agregando el fragmento de código siguiente:

import { AadHttpClient, HttpClientResponse } from '@microsoft/sp-http';

En la clase OrdersWebPart, agregue una nueva variable de clase llamada ordersClient:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  // shortened for brevity
}

A continuación, en la clase OrdersWebPart, reemplace el método onInit() para crear una instancia de la AadHttpClient:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  protected onInit(): Promise<void> {
    return new Promise<void>((resolve: () => void, reject: (error: any) => void): void => {
      this.context.aadHttpClientFactory
        .getClient('6bc8bca8-5866-405d-b236-9200bdbb73c0')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  // shortened for brevity
}

El GUID usado como el segundo parámetro del constructor AadHttpClient es el identificador de la aplicación de Azure AD que se utiliza para proteger la API.

Por último, amplíe el método render() para cargar y mostrar los pedidos que se han recuperado de la API de empresa:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  protected onInit(): Promise<void> {
    return new Promise<void>((resolve: () => void, reject: (error: any) => void): void => {
      this.context.aadHttpClientFactory
        .getClient('6bc8bca8-5866-405d-b236-9200bdbb73c0')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  public render(): void {
    this.context.statusRenderer.displayLoadingIndicator(this.domElement, 'orders');

    this.ordersClient
      .get('https://contoso-api-dp20191109.azurewebsites.net/api/Orders', AadHttpClient.configurations.v1)
      .then((res: HttpClientResponse): Promise<any> => {
        return res.json();
      })
      .then((orders: any): void => {
        this.context.statusRenderer.clearLoadingIndicator(this.domElement);
        this.domElement.innerHTML = `
          <div class="${ styles.orders}">
            <div class="${ styles.container}">
              <div class="${ styles.row}">
                <div class="${ styles.column}">
                  <span class="${ styles.title}">Orders</span>
                  <p class="${ styles.description}">
                    <ul>
                      ${orders.map(o => `<li>${o.rep} $${o.total}</li>`).join('')}
                    </ul>
                  </p>
                  <a href="https://aka.ms/spfx" class="${ styles.button}">
                    <span class="${ styles.label}">Learn more</span>
                  </a>
                </div>
              </div>
            </div>
          </div>`;
      }, (err: any): void => {
        this.context.statusRenderer.renderError(this.domElement, err);
      });
  }

  // shortened for brevity
}

Implementar la solución en el catálogo de aplicaciones de SharePoint

Después de completar la implementación de la solución de SharePoint Framework, el siguiente paso es implementarla en SharePoint.

En primer lugar, cree y empaquete el proyecto usando la línea de comandos:

gulp bundle --ship && gulp package-solution --ship

A continuación, en el explorador, abra la carpeta del proyecto y vaya a la carpeta sharepoint/solution:

Use el navegador web para ir al catálogo de aplicaciones del inquilino de su espacio empresarial de Office 365:

Agregue el archivo .sppkg recién generado arrastrándolo y soltándolo desde el explorador en el catálogo de aplicaciones del espacio empresarial:

Cuando se le solicite, seleccione la casilla Hacer que esta solución esté disponible en todos los sitios de la organización. Además, recuerde que deberá ir a la Página de administración de permisos de entidad de servicio para aprobar las solicitudes de permiso pendientes. Confirme la implementación haciendo clic en el botón Implementar:

Conceder acceso a la API de empresa

En el navegador web, vaya al sitio de administración de espacios empresariales haciendo clic en Administración en el iniciador de aplicaciones de Office 365:

En el menú, en el grupo Centros de administración, elija SharePoint:

En el Centro de administración de SharePoint, vaya a la nueva vista previa del Centro de administración de SharePoint usando el vínculo Probar la nueva vista previa del Centro de administración de SharePoint:

En el nuevo centro de administración, en el menú, elija la opción Administración de la API:

En la página de administración de la API, en el grupo Pendientes de aprobación, seleccione la solicitud de permiso recién agregada para acceder a la API contoso-api (se mostrará el nombre de la API):

A continuación, en la barra de herramientas, seleccione la opción Aprobar o rechazar:

En el panel lateral, conceda acceso a la API haciendo clic en Aprobar:

Nota:

Es posible crear un elemento web aislado del dominio que se conecte a la API protegida con AAD. En este caso, la CORS para la API tiene que volver a configurarse de forma adecuada, ya que todas las instancias del elemento web aislado del dominio se ejecutan en la aplicación web dedicada con un dominio único.

Agregar el elemento web Pedidos a la página

Para comprobar que todo funciona según lo esperado, agregue a una página el elemento web Pedidos creado previamente.

En el navegador web, vaya a un sitio de su espacio empresarial. En la barra de herramientas, seleccione la opción Editar:

En el lienzo, elija una sección a la que agregar el elemento web:

Seleccione la opción + para abrir el cuadro de herramientas. En el cuadro de búsqueda, escriba Pedidos para encontrar rápidamente el elemento web Pedidos:

Seleccione el elemento webPedidos para agregarlo a la página. Verá la lista de pedidos que se ha recuperado de la API de empresa:

Si recibe un error con los detalles t?cnicos de "Error al abrir ventana emergente", tiene habilitado un bloqueador de elementos emergentes. Deber? deshabilitar el bloqueador de elementos emergentes del navegador para su sitio con el fin de mostrar la p?gina correctamente.