Azure AD aplicaciones para complementos de Office y SSO
Las herramientas de desarrollo proporcionadas por Microsoft para crear complementos de Office con ASP.NET o Node.js utilidades incluidas para registrar la aplicación Microsoft Entra necesaria. Esta herramienta, configure-sso, simplifica no solo el registro de aplicaciones, sino también la configuración de la estación de trabajo del desarrollador.
En esta unidad, aprenderá a crear el registro de la aplicación Microsoft Entra para un complemento de Office que implementa el inicio de sesión único (SSO). También aprenderá algunos procedimientos recomendados por Microsoft al crear complementos de Office que implementan SSO.
Registro de una aplicación de Microsoft Entra para el inicio de sesión único del complemento de Office
Echemos un vistazo a los requisitos para registrar una aplicación de Microsoft Entra que usa un complemento de Office que implementa el inicio de sesión único.
Microsoft Entra registro de aplicaciones
El primer paso es registrar una aplicación Microsoft Entra en el centro de administración de Microsoft Entra (https://aad.portal.azure.com).
Al registrar la aplicación, asegúrese de establecer los tipos de cuenta admitidos como cuentas en cualquier aplicación de directorio organizativo (cualquier directorio Microsoft Entra multiinquilino).
Importante
Las aplicaciones de complementos de Office no pueden ser de un solo espacio empresarial; deben ser multiempresa.
Autenticación
El paso siguiente consiste en configurar las opciones de la autenticación para la aplicación.
La aplicación debe tener al menos dos URI de redirección enumerados:
- la página de complementos, como la dirección URL de la página HTML del panel de tareas
- la página de reserva, como la página fallbackauthdialog.html
Las opciones de token de concesión implícita y flujos híbridos deben estar habilitadas porque los complementos de Office suelen ser aplicaciones del lado cliente:
- Tokens de acceso (usados para flujos implícitos)
- Tokens de identificador (usados para flujos implícitos e híbridos)
Permisos API
Otra parte importante de la aplicación Microsoft Entra son los permisos que necesita para funcionar.
A cada aplicación se le deben conceder los permisos de OpenID openid y profile. Algunas bibliotecas requieren permisos adicionales. Por ejemplo, Microsoft Authentication Library para .NET requiere el permiso de office_access.
Si el complemento necesita permisos para Microsoft Graph, también deben agregarse aquí.
Aunque no es necesario, al registrar la aplicación, como administrador, usted puede dar su consentimiento previo en nombre de todos los usuarios de su espacio empresarial para estos permisos. Esto simplifica el flujo de autenticación para que los usuarios no tengan que dar su consentimiento al complemento cuando lo usen por primera vez.
Exponer una API
La aplicación debe exponer sus propios permisos para Microsoft Entra id. y clientes de Office. En la pantalla Exponer una API , establezca el URI del identificador de aplicación. De forma predeterminada, esto es api://<APP_ID>, pero debe actualizarlo para incluir el dominio donde se hospeda el código base del complemento.
Incluya la dirección URL antes de la parte <APP_ID> del URI. Por ejemplo: api://addin.contoso.com/<APP_UD>. Este dominio debe coincidir con el dominio desde el que se sirven todos los recursos definidos en el archivo manifest.xml del complemento.
El siguiente paso consiste en exponer un permiso, también denominado ámbito. Los clientes de Office usarán este ámbito, access_as_user, para indicar que pueden actuar en nombre del usuario que ha iniciado sesión al proporcionar el token de arranque para Microsoft Graph al iniciar el flujo en nombre de OAuth2.
Por último, debe conceder este permiso a todas las aplicaciones cliente de Office. Esto configura la aplicación para que confíe en todas las aplicaciones cliente de Office para obtener el permiso de access_as_user.
Cada tipo de cliente de Office se representa mediante un identificador único. Asegúrese de incluir la siguiente aplicación. Al hacerlo, asegúrese de habilitar el permiso de access_as_user:
ea5a67f6-b6f3-4338-b240-c655ddc3cc8e(Microsoft Office)
Importante
El servicio ea5a67f6-b6f3-4338-b240-c655ddc3cc8e es una autorización de grupo que incluye todos los demás hosts de Office, por lo que puede incluir esta en lugar de enumerar cada una de las siguientes aplicaciones individuales:
d3590ed6-52b3-4102-aeff-aad2292ab01c(Microsoft Office)57fb890c-0dab-4253-a5e0-7188c88b2bb4(Office en la Web)08e18876-6177-487e-b8b5-cf950c1e598c(Office en la Web)bc59ab01-8403-45c6-8796-ac3ef710b3e3(Outlook en la Web)93d53678-613d-4013-afc1-62e9e444a0a5(Office en la Web)
El último servicio enumerado anteriormente, 93d53678-613d-4013-afc1-62e9e444a0a5, es un nuevo servicio SSO introducido en enero de 2022.
Procedimientos recomendados para el desarrollo de SSO de complementos de Office
Microsoft recomienda lo siguiente al crear complementos de Office que implementen SSO.
Usar allowConsentPrompt si solo necesita el perfil del usuario
En algunos escenarios, el complemento de Office solo puede usar SSO para obtener el perfil del usuario. En estos casos, considere la posibilidad de invalidar el comportamiento predeterminado del proceso de inicio de sesión pasando la opción { allowConsentPrompt: true } al llamar a getAccessToken() en el SDK de Office.js.
El valor predeterminado de la propiedad es false. Esta propiedad permite que Office obtenga de forma silenciosa un token de acceso o mediante un consentimiento interactivo si se requiere uno. Cuando la propiedad se establece en false, si Office no puede obtener un token porque el usuario no ha dado su consentimiento, recibirá un error descriptivo.
Sin embargo, cuando se establece en true, Office mostrará un consentimiento interactivo después de que no obtenga un token de acceso de forma silenciosa.
Importante
Recuerde que Office solo puede solicitar al usuario que dé su consentimiento al permiso profile de OpenID, pero ningún permiso de Microsoft Graph.
Implementar un método de autorización de reserva
La autenticación y la autorización con complementos de Office no siempre son un camino directo hacia el éxito. Como se ha explicado en este módulo, hay varios escenarios en los que puede producirse un error en el complemento durante el proceso de autorización.
Esto puede incluir el escenario en el que el usuario no ha aceptado permisos de Microsoft Graph que necesita el complemento. En ese caso, es mejor si el complemento puede producir un error rápidamente para solicitar al usuario que dé su consentimiento a los permisos necesarios. Este enfoque es mejor que esperar hasta más tarde en el proceso para notificar al usuario.
Implementar el enfoque de "fracasar rápido" para la autorización
Al repetir la sección anterior, recuerde lo que ha aprendido en una lección anterior. Cuando Office solicita el token de arranque inicial, puede incluir la opción de autorización { forGraphAccess: true } al llamar a getAccessToken() en el SDK de Office.js.
Cuando Microsoft Entra identificador recibe esto, realiza otra comprobación para ver si el usuario ya ha dado su consentimiento a los permisos solicitados de Microsoft Graph. Si no es así, Microsoft Entra identificador responde con un código de error específico que el complemento puede controlar en el sistema de autorización de reserva para pedir al usuario que dé su consentimiento a los permisos de Microsoft Graph.
Autorización previa de todos los clientes de Office con el complemento
Como se muestra en esta unidad, puede autorizar previamente el registro de la aplicación Microsoft Entra que usa el complemento de Office para confiar en todas las aplicaciones cliente de Office. Esto incluye todos los clientes de Office de escritorio, móviles y web.
Esto garantiza que el complemento funcionará en el número máximo de escenarios.