Registrar un complemento de Office que use el inicio de sesión único (SSO) con el Plataforma de identidad de Microsoft

  • Artículo

En este artículo se explica cómo registrar un complemento de Office con el Plataforma de identidad de Microsoft para que pueda usar el inicio de sesión único. Registre el complemento cuando empiece a desarrollarlo para que, cuando avance a las pruebas o a la producción, pueda cambiar el registro existente o crear registros independientes para las versiones de desarrollo, pruebas y producción del complemento.

En la tabla siguiente se detallan la información que necesita para llevar a cabo este procedimiento y los marcadores de posición correspondientes que aparecen en las instrucciones.

Información Ejemplos Marcador de posición
Un nombre en lenguaje natural para el complemento. (Se recomienda que sea único, pero no es necesario). Contoso Marketing Excel Add-in (Prod) <add-in-name>
Identificador de aplicación que Azure genera automáticamente como parte del proceso de registro. c6c1f32b-5e55-4997-881a-753cc1d563b7 <app-id>
El nombre de dominio completo (excepto para protocolo) del complemento. Debe usar un dominio del que sea propietario. Por este motivo, no puede usar determinados dominios conocidos como azurewebsites.net o cloudapp.net. El dominio debe ser el mismo, incluidos los subdominios, como se usa en las direcciones URL de la <sección Recursos> del manifiesto del complemento. localhost:6789, addins.contoso.com <fully-qualified-domain-name>
Permisos para el Plataforma de identidad de Microsoft y Microsoft Graph que necesita el complemento. (profile siempre es necesario.) profile, Files.Read.All N/D

Precaución

Información confidencial: el URI del identificador de aplicación (<fully-qualified-domain-name>) se registra como parte del proceso de autenticación cuando se activa un complemento con SSO en Office que se ejecuta dentro de Microsoft Teams. El URI no debe contener información confidencial.

Registre el complemento con Plataforma de identidad de Microsoft

Debe crear un registro de aplicación en Azure que represente el servidor web. Esto permite la compatibilidad con la autenticación para que se puedan emitir tokens de acceso adecuados al código de cliente en JavaScript. Este registro admite tanto el inicio de sesión único en el cliente como la autenticación de reserva mediante la biblioteca de autenticación de Microsoft (MSAL).

  1. Inicie sesión en el Azure Portal con las credenciales de administrador en el inquilino de Microsoft 365. Por ejemplo, MyName@contoso.onmicrosoft.com.

  2. Seleccione Registros de aplicaciones. Si no ve el icono, busque "Registro de aplicaciones" en la barra de búsqueda.

    Página principal Azure Portal.

    Aparece la página Registros de aplicaciones.

  3. Seleccione Nuevo registro.

    Nuevo registro en el panel Registros de aplicaciones.

    Aparece la página Registrar una aplicación.

  4. En la página Registrar una aplicación, establezca los valores siguientes.

    • Establezca Nombre como <add-in-name>.
    • Establezca Tipos de cuenta admitidosen Cuentas en cualquier directorio organizativo (cualquier directorio de Azure AD: multiinquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox).
    • Establezca el URI de redirección para usar la aplicación de página única (SPA) de la plataforma y el URI en https://<fully-qualified-domain-name>/dialog.html.

    Registre un panel de aplicación con el nombre y la cuenta admitida completadas.

  5. Seleccione Registrar. Se muestra un mensaje que indica que se creó el registro de la aplicación.

    Mensaje que indica que se creó el registro de la aplicación.

  6. Copie y guarde los valores para el identificador de aplicación (cliente) y el identificador de directorio (inquilino). Deberá usar ambos en procedimientos posteriores.

    Panel de registro de aplicaciones para Contoso que muestra el identificador de cliente y el identificador de directorio.

Adición de un secreto de cliente

A veces denominado contraseña de aplicación, un secreto de cliente es un valor de cadena que la aplicación puede usar en lugar de un certificado para la identidad propia.

  1. En el panel izquierdo, seleccione Certificados & secretos. A continuación, en la pestaña Secretos de cliente, seleccione Nuevo secreto de cliente.

    El panel Certificados & secretos.

    Aparece el panel Agregar un secreto de cliente .

  2. Agregue una descripción para el secreto de cliente.

  3. Seleccione una expiración para el secreto o especifique una duración personalizada.

    • La duración del secreto de cliente está limitada a dos años (24 meses) o menos. No se puede especificar una duración personalizada de más de 24 meses.
    • Microsoft recomienda establecer un valor de expiración de menos de 12 meses.

    Agregue un panel secreto de cliente con la descripción y expire completado.

  4. Seleccione Agregar. Se crea el nuevo secreto y se muestra temporalmente el valor.

Importante

Registre el valor del secreto para usarlo en el código de la aplicación cliente. Este valor secreto nunca se vuelve a mostrar después de salir de este panel.

Exponer una API web

  1. En el panel izquierdo, seleccione Exponer una API.

    Aparece el panel Exponer una API .

    El panel Exponer una API de un registro de aplicación.

  2. Seleccione Establecer para generar un URI de identificador de aplicación.

    Botón Establecer en el panel Exponer una API del registro de la aplicación.

    La sección para establecer el URI del identificador de aplicación aparece con un URI de identificador de aplicación generado con el formato api://<app-id>.

  3. Actualice el URI del identificador de aplicación a api://<fully-qualified-domain-name>/<app-id>.

    Edite el panel URI del identificador de aplicación con el puerto localhost establecido en 44355.

    • El URI de id. de aplicación se rellena previamente con el identificador de aplicación (GUID) con el formato api://<app-id>.
    • El formato uri del identificador de aplicación debe ser: api://<fully-qualified-domain-name>/<app-id>
    • Inserte el fully-qualified-domain-name valor entre api:// y <app-id> (que es un GUID). Por ejemplo, api://contoso.com/<app-id>.
    • Si usa localhost, el formato debe ser api://localhost:<port>/<app-id>. Por ejemplo, api://localhost:3000/c6c1f32b-5e55-4997-881a-753cc1d563b7.

    Para obtener más detalles sobre el URI del identificador de aplicación, consulte Identificador de manifiesto de aplicaciónInquilinouris.

    Nota:

    Si recibe un error que indica que el dominio ya tiene propietario, pero es usted su propietario, siga el procedimiento de Inicio rápido: agregar un nombre de dominio personalizado a Azure Active Directory para registrarlo y repita este paso. (Este error también puede producirse si no ha iniciado sesión con las credenciales de un administrador en el inquilino de Microsoft 365. Consulte el paso 2. Cierre la sesión e inicie sesión de nuevo con las credenciales de administrador y repita el proceso desde el paso 3).

Agregar un ámbito

  1. En la página Exponer una API , seleccione Agregar un ámbito.

    Seleccione el botón Agregar un ámbito.

    Se abre el panel Agregar un ámbito .

  2. En el panel Agregar un ámbito , especifique los atributos del ámbito. En la tabla siguiente se muestran los valores de ejemplo para y el complemento de Outlook que requieren los profilepermisos , openid, Files.ReadWritey Mail.Read . Modifique el texto para que coincida con los permisos que necesita el complemento.

    Campo Descripción Valores
    Nombre de ámbito Nombre del ámbito. Una convención de nomenclatura de ámbito común es resource.operation.constraint. Para el inicio de sesión único, debe establecerse en access_as_user.
    Quién puede dar su consentimiento Determina si se requiere el consentimiento del administrador o si los usuarios pueden dar su consentimiento sin la aprobación del administrador. Para aprender el inicio de sesión único y los ejemplos, se recomienda establecerlo en Administradores y usuarios.

    Seleccione Solo administradores para permisos con privilegios superiores.
    Administración nombre para mostrar del consentimiento Una breve descripción del propósito del ámbito visible solo para los administradores. Read/write permissions to user files. Read permissions to user mail and profiles.
    Administración descripción del consentimiento Una descripción más detallada del permiso concedido por el ámbito que solo ven los administradores. Allow Office to have read/write permissions to all user files and read permissions to all user mail. Office can call the app's web APIs as the current user.
    Nombre para mostrar del consentimiento del usuario Breve descripción del propósito del ámbito. Se muestra a los usuarios solo si establece Who can consent to Admins and users (Quién puede dar su consentimiento a administradores y usuarios). Read/write permissions to your files. Read permissions to your mail and profile.
    Descripción del consentimiento del usuario Descripción más detallada del permiso concedido por el ámbito. Se muestra a los usuarios solo si establece Who can consent to Admins and users (Quién puede dar su consentimiento a administradores y usuarios). Allow Office to have read/write permissions to your files, and read permissions to your mail and profile.

  3. Establezca Estadoen Habilitado y, a continuación, seleccione Agregar ámbito.

    Establezca el estado en habilitado y seleccione el botón Agregar ámbito.

    El nuevo ámbito definido se muestra en el panel.

    Nuevo ámbito que se muestra en el panel Exponer una API.

    Nota:

    La parte del dominio del Nombre de ámbito que aparece justo debajo del campo de texto debe coincidir automáticamente con el URI de identificador de aplicación establecido en el paso anterior, con /access_as_user anexado al final; por ejemplo, api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_user.

  4. Seleccione Agregar una aplicación cliente.

    Seleccione Agregar una aplicación cliente.

    Aparece el panel Agregar una aplicación cliente .

  5. En Id . de cliente , escriba ea5a67f6-b6f3-4338-b240-c655ddc3cc8e. Este valor autoriza previamente todos los puntos de conexión de aplicación de Microsoft Office. Si también desea autorizar previamente Office cuando se usa dentro de Microsoft Teams, agregue 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (escritorio de Microsoft Teams y dispositivos móviles de Teams) y 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams en la web).

    Nota:

    El ea5a67f6-b6f3-4338-b240-c655ddc3cc8e identificador autoriza previamente a Office en todas las plataformas siguientes. Como alternativa, puede escribir un subconjunto adecuado de los siguientes identificadores si, por cualquier motivo, desea denegar la autorización a Office en algunas plataformas. Si lo hace, deje fuera los identificadores de las plataformas desde las que desea retener la autorización. Los usuarios del complemento en esas plataformas no podrán llamar a las API web, pero otras funciones del complemento seguirán funcionando.

    • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
    • 93d53678-613d-4013-afc1-62e9e444a0a5 (Office en la Web)
    • bc59ab01-8403-45c6-8796-ac3ef710b3e3 (Outlook en la Web)

  6. En Ámbitos autorizados, active la api://<fully-qualified-domain-name>/<app-id>/access_as_user casilla .

  7. Seleccione Agregar aplicación.

    Panel Agregar una aplicación cliente.

Adición de permisos de Microsoft Graph

  1. En el panel izquierdo, seleccione Permisos de API.

    Panel Permisos de API.

    Se abre el panel Permisos de API .

  2. Seleccione Agregar un permiso

    Agregar un permiso en el panel permisos de API.

    Se abre el panel Solicitar permisos de API .

  3. Seleccione Microsoft Graph.

    El panel Solicitar permisos de API con el botón Microsoft Graph.

  4. Seleccione Permisos delegados

    El panel Solicitar permisos de API con permisos delegados.

  5. En el cuadro de búsqueda Seleccionar permisos , busque los permisos que necesita el complemento. Por ejemplo, para un complemento de Outlook, puede usar profile, openid, Files.ReadWritey Mail.Read.

    Nota:

    El permiso User.Read podría aparecer ya de forma predeterminada. Se recomienda solicitar solo los permisos necesarios, por lo que se recomienda desactivar la casilla para este permiso si el complemento no lo necesita realmente.

  6. Active la casilla para cada permiso tal como aparece. Tenga en cuenta que los permisos no permanecerán visibles en la lista a medida que seleccione cada uno de ellos. Después de seleccionar los permisos que necesita el complemento, seleccione Agregar permisos.

    El panel Solicitar permisos de API con algunos permisos seleccionados.

  7. Seleccione Conceder consentimiento de administrador para [nombre de inquilino]. Seleccione Sí para la confirmación que aparece.

Configuración de la versión del token de acceso

Debe definir la versión del token de acceso que sea aceptable para la aplicación. Esta configuración se realiza en el manifiesto de aplicación de Azure Active Directory.

Definición de la versión del token de acceso

La versión del token de acceso puede cambiar si elige un tipo de cuenta distinto de Cuentas en cualquier directorio organizativo (cualquier directorio de Azure AD: multiinquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox). Siga estos pasos para asegurarse de que la versión del token de acceso es correcta para el uso del inicio de sesión único de Office.

  1. En el panel izquierdo, seleccione Manifiesto.

    Seleccione Manifiesto de Azure.

    Aparece el manifiesto de aplicación de Azure Active Directory.

  2. Introduzca 2 como valor de la accessTokenAcceptedVersion propiedad.

    Valor de la versión del token de acceso aceptado.

  3. Seleccione Guardar.

    Aparece un mensaje en el explorador que indica que el manifiesto se actualizó correctamente.

    Mensaje actualizado del manifiesto.

Enhorabuena. Ha completado el registro de la aplicación para habilitar el inicio de sesión único para el complemento de Office.