Utilizar API de empresas multinquilino protegidas con Azure AD en SharePoint Framework

Este artículo muestra cómo conectarse a una API empresarial multinquilino protegida con Azure Active Directory de un producto 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 multinquilino protegida con Azure AD

Empiece creando una API de empresa multinquilino protegida con Azure Active Directory. Aunque no hay restricciones sobre cómo se debe implementar la API desde el punto de vista SharePoint Framework, en este tutorial, compilará la API mediante Azure Functions y la protegerá mediante la autenticación de 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.

Creación de una función de Azure

En el Azure Portal, cree una nueva aplicación de funciones.

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, lo compilará con C#, pero no hay ninguna restricción con respecto al lenguaje de programación que puede usar.

En Function App, seleccione el botón Agregar y, en la lista de tipos de función disponibles, elija Desencadenador HTTP.

En la configuración de la función, especifique el nombre de la función y establezca el nivel de autorización en Anónimo.

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.

Para confirmar la configuración y crear la función, seleccione el botón Crear función .

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

using System.Net;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)
{
    log.Info("C# HTTP trigger function processed a request.");

    return req.CreateResponse(HttpStatusCode.OK, 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, seleccione el botón Probar y ejecutar y haga clic en 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.

Protección de la función de Azure

Ahora que la función de Azure funciona, el siguiente paso es protegerla con Azure Active Directory para que, para acceder a ella, tenga que iniciar sesión con la cuenta de la organización.

En la hoja Aplicación de funciones, en el panel lateral, seleccione el vínculo Autenticación/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 la lista desplegable Acción que se realizará cuando la solicitud no se autentique , cambie el valor a Iniciar sesión con Azure Active Directory.

Esta configuración garantiza que no se permiten 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, para la primera opción Modo administración, elija Rápido. Para la segunda opción Modo administración, elija Crear nueva App de AD.

Confirme la selección haciendo clic en Aceptar.

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 usará para proteger la API, y que necesitará más adelante, para solicitar permisos para acceder a la API desde el proyecto de SharePoint Framework.

Actualice la configuración de la autenticación y autorización de Function App haciendo clic en Guardar.

Confirme que la API está protegida correctamente abriendo una nueva ventana del navegador en modo privado y yendo a la API. 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.

Haga la aplicación de Azure AD multinquilino

De forma predeterminada, cuando se protege una función de Azure mediante una aplicación de Azure AD, solo pueden usar esa función Azure los usuarios de la misma Azure AD que en la que se encuentra la aplicación. Si quiere usar la API con espacios empresariales diferentes, debe cambiar la aplicación de Azure AD a multinquilino.

Cambiar la aplicación para que sea multinquilino

Vaya a la página principal de la Azure Portal y busque Azure Active Directory.

En la hoja izquierda, seleccione Registros de aplicaciones y seleccione la aplicación que se creó automáticamente cuando se creó la aplicación de función.

En el campo Exponer una API, actualice el campo URI del identificador de aplicación, cambie el identificador de la aplicación de Azure AD para que comience por https://yourtenant.onmicrosoft.com, por ejemplo, . https://contoso.onmicrosoft.com/contoso-api Este cambio es necesario, porque la app de Azure AD se usará por otros espacios empresariales y será necesario para asegurar su singularidad en todos los Azure Active Directories.

En información general , haga clic en el vínculo Tipos de cuenta admitidos , que será Solo mi organización. Tenemos que cambiarlo para que la aplicación sea multiinquilino.

Cambie el valor del campo Multiinquilino a Sí:

Por último, confirme los cambios de la barra de herramientas seleccionando la opción Guardar.

Permite que los usuarios de otros Azure AD usen sus aplicaciones

Dado que protege su API con la configuración rápida de Azure AD, solo los usuarios del mismo Azure AD, como en el que se encuentra la aplicación, pueden usarla. Dado que quiere que la API también la utilicen usuarios de otros espacios empresariales, debe ajustar la configuración de seguridad.

Cierre todas las hojas abiertas hasta que vuelva a la hoja Autenticación o autorización de la aplicación De función. Escoja Azure Active Directory en la lista de proveedores de autenticación.

En la hoja Configuración de Azure Active Directory, cambie el campo Modo administración, a Avanzado.

A continuación, elimine lo que aparezca en el campo de la URL del emisor. Esto permitirá a los usuarios de otros Azure Active Directories autentificarse en su API.

Antes de confirmar los cambios, copie lo que aparezca en el campo Id. de cliente. Lo necesitará al compilar el elemento web para solicitar un token de acceso para la API.

Confirme los cambios con el botón Aceptar y confirme los cambios mediante el botón Guardar .

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, las API implementadas con Azure Function Apps no se pueden llamar desde otros dominios. Si quiere cambiarlo, ajuste la configuración de CORS de Function App.

En function app, haga clic en el vínculo CORS .

A la lista de orígenes permitidos, agregue la dirección URL del inquilino de SharePoint, por ejemplo, https://contoso.sharepoint.com.

Confirme los cambios haciendo clic en Guardar.

Aceptar el uso de la API en su espacio empresarial

Antes de que los usuarios del inquilino puedan usar la API de otro inquilino, la API debe aprobarse. La aprobación, también conocida como consentimiento, puede realizarse en dos niveles: usuarios y administrador (organización). En este escenario, usará el consentimiento del administrador para aprobar la API para que la use toda la organización.

Nota:

Normalmente, el sitio en el que se muestra la API le guía por el proceso de dar su consentimiento a la API en su espacio empresarial. En este ejemplo, realizará los pasos necesarios manualmente para comprender mejor cómo funciona el proceso.

En la hoja de Function App, seleccione la función.

Para obtener la dirección URL de la función, seleccione en la barra de herramientas la opción Obtener la dirección URL de la función.

En el cuadro de diálogo Obtener la dirección URL de la función, copie la URL de la función mediante la opción Copiar.

En una nueva ventana del explorador, vaya a la dirección URL de la función que ha copiado. Cuando se le pida que inicie sesión, use la cuenta de administrador del espacio empresarial de Office 365, en la que quiere usar la API.

Después de iniciar sesión, se le pedirá que dé su consentimiento con el uso de esta API.

Esto, en cambio, es el consentimiento del usuario. Para cambiar al consentimiento del administrador y aprobar la API para que la use toda la organización, anexe a la dirección URL &prompt=admin_consent. Una vez más, se le pedirá un cuadro de diálogo de consentimiento, pero observe que, esta vez, el cuadro de diálogo indica que la aplicación tendrá acceso a los recursos especificados para todos los usuarios de la organización y que no se le pedirá a nadie más.

Confirme que quiere que los usuarios de su organización usen la API seleccionando la opción Aceptar.

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á esta 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 ha instalado el generador globalmente, puede comprobar la versión instalada ejecutando en la línea de comandos: npm ls -g --depth=0.

Crear un proyecto de SharePoint Framework

Empiece creando un nuevo proyecto de SharePoint Framework. En la línea de comandos, cree una nueva carpeta para el proyecto:

md contoso-api

Cambie el directorio de trabajo ejecutando lo siguiente en la línea de comandos:

cd contoso-api

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

yo @microsoft/sharepoint

Cuando se le pida, use los siguientes valores:

• contoso-api como el nombre de la solución
• SharePoint Online solo (más reciente) como los paquetes de línea base
• Usar la carpeta actual como la ubicación para colocar los archivos
• Y como la opción para habilitar la implementación en todo el espacio empresarial
• WebPart como el tipo de componente que va a crear
• Pedidos como el nombre del elemento web que se va a crear
• Muestra pedidos recientes como la descripción del elemento web
• Sin marco de JavaScript como el marco que se va a utilizar

Una vez que se ha creado el proyecto, ábralo en el 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 empresariales, aunque estén registradas en la misma instancia de 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.

A la propiedad solution, agregue una nueva sección 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,
    "webApiPermissionRequests": [
      {
        "resource": "contoso-api",
        "scope": "user_impersonation"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/contoso-api.sppkg"
  }
}

El valor de la propiedad de recurso hace referencia solo al nombre de la aplicación de Azure AD que se usa para proteger la API. El valor de la propiedad scope especifica el ámbito de permiso que la solución necesita 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 expone la aplicación y la audiencia en la que está 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('https://contoso-api.azurewebsites.net')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  // shortened for brevity
}

El URI que se pasa al getClient() método es el URI del identificador de aplicación de la aplicación de Azure AD que se usa para proteger la API empresarial.

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('https://contoso-api.azurewebsites.net')
        .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.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
}

Implementación de 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, compile y empaquete el proyecto mediante la ejecución en 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.

En el explorador web, vaya al catálogo de aplicaciones del inquilino en el inquilino de Office 365.

Agregue el archivo recién generado.sppkg** arrastrándolo y soltándolo desde el explorador al catálogo de aplicaciones del inquilino.

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 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 haciendo clic en 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.

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.

Agregar el elemento web Pedidos a la página

Para comprobar que todo funciona según lo esperado, agregue a la 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 Orders 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.