En el último Collab365 pudimos compartir una charla en el que se explica cómo extender Office a través de los Add-in de Office. Para ello utilizamos un ejemplo basado en un Add-in de Outlook en el que se consumía Office Graph para consultar los datos del perfil del usuario que nos envía un correo. Como la interfaz de los add-in se incrusta dentro de Office debemos asegurarnos la mejor experiencia, para lo que disponemos de Office UI Fabric con el que poder utilizar estilos y componentes similares a la interfaz estándar de Office y SharePoint.

Podéis consultar el vídeo desde https://www.youtube.com/watch?v=9Xk8quLJoB8&feature=youtu.be

Podéis encontrar la presentación desde http://www.slideshare.net/MarioFlores1/extensin-de-office-con-adaljs-y-office-ui-fabric

Los Add-in de Office se basan en páginas HTML con las que podemos interactuar con nuestros documentos a través del Windos Extensibility Framewok, que nos proporciona el API office.js con la que poder leer y editar determinadas secciones de los documentos, correos, contactos,… de Office. Al cargarse el Add-in, por debajo se iniciará una instancia del navegador que a su vez cargará por un lado el WEF y un iframe a la página home de nuestro Add-in.

Aunque nuestro Add-in se encuentre dentro del contexto de Office, éste se ejecuta en un entorno aislado de manera que no comparte los tokens de autorización asignados previamente a nuestro usuario, por lo que para poder consumir desde nuestro Add-in el api de Office Graph tendremos que iniciar el proceso de autenticación y autorización cómo si fuera una página aislada de Office. Utilizaremos entonces Adal.JS para facilitar este proceso.

Adal.JS

Consiste en una biblioteca JavaScript con la que facilitar la autenticación e intercambio de tokens de seguridad OAuth. En este caso lo utilizaremos para obtener los tokens de autorización de uso en Office Graph.

Adal.JS está pensado para realizar todas las operaciones de autenticación y autorización desde la parte frontal en aquellos escenarios donde queramos realizar todas las operaciones de consulta desde el frontal, bien por descargar al servidor o bien por que carecemos de una capa de servicios.

Para poder utilizar los servicios de Office365 debemos pasar en cada llamada un bearer que se utilizar para validar que nuestra aplicación o página desde la que se consume el servicio tiene permisos para hacerlo. Debemos registrar entonces nuestra solución como una aplicación de WAAD (Windows Azure Active Directory) donde indicaremos las url’s de autenticación, así como los servicios que le permitiremos consumir (Graph, OneDrive, AD, SharePoint,…) además de los permisos u objetos disponibles sobre cada servicio. Como resultado obtendremos un clientid que utilizaremos durante el proceso de autenticación y autorización. Este registro se puede realizar bien desde la página de administración de WAAD o accediendo a http://dev.office.com/getting-started/office365apis

Encontraréis un mayor detalle del proceso de autorización con WAAD y el detalle del flujo de llamadas en el artículo Authentication Scenarios for Azure AD

Para añadir Adal.JS a nuestra página solo debemos añadirla como referencia:

<script src=”https://secure.aadcdn.microsoftonline-p.com/lib/1.0.0/js/adal.min.js”></script>

Una vez añadido dispondremos del objeto AuthenticationContext el cual tendremos que inicializar con un objeto de configuración en el que indiquemos:

  • subscriptionId: El identificador de la suscripción sobre la que queremos autenticarnos.
  • tenant: El nombre del tenant.
  • clientId: El client id generado para nuestra aplicación.
  • postLogoutRedirectUri: La dirección url de la página de vuelta que se utilizará como resultado durante el proceso de autenticación.
  • endpoints: Las url de los servicios que se consumirán.
  • cacheLocation: Sistema de almacenamiento de cache, en nuestro caso utilizaremos el localStorage del navegador.

Quedando por ejemplo:

window.config = {
 

 subscriptionId: xxxxxxxx -xxxx-xxxx-xxxx- xxxxxxxxxxxx',
 

 tenant: 'mitenant.onmicrosoft.com',
 

 clientId: xxxxxxxx-xxxx–xxxx-xxxx-xxxxxxxxxxxx',
 

 postLogoutRedirectUri: window.location.origin,
 

 endpoints: {
 

 officeGraph: 'https://graph.microsoft.com'
 

 },
 

 cacheLocation: 'localStorage'
 

 };

var authContext = new AuthenticationContext(config);

Una vez inicializado debemos hacer un login sobre AD mediante el método “login“. Como resultado de esta llamada se llamará a la página “postLogoutRedirectUri” que en nuestro caso es la propia página, por lo que debemos tener en cuenta que la página puede haberse cargado previamente, para lo que utilizaremos el método “getCachedUser” con el que comprobaremos si estamos logados.

Una vez logados, obtendremos un token de autorizción para uno de los endpoints configurados mediante el método asíncrono “acquireToken”.

O365.acquireToken = function (errorCallBackFunction) {
 

 var authContext = new AuthenticationContext(config);
 

 var isCallback = authContext.isCallback(window.location.hash);
 

 authContext.handleWindowCallback();
 

 if (isCallback && !authContext.getLoginError()) {
 

 window.location = authContext._getItem(authContext.CONSTANTS.STORAGE.LOGIN_REQUEST);
 

 }
 

 var user = authContext.getCachedUser();
 

 if (user) {
 

 authContext.acquireToken(config.endpoints.officeGraph, function (error, token) {
 

 if (error || !token) {
 

 errorCallBackFunction("No token: " + error);
 

 }
 

 });
 

 } else {
 

 authContext.login();
 

 }
 

 }

Como resultado de la llamada acquireToken obtendremos el token bearer que utilizaremos en las llamadas a los endpoints para los que hemos obtenido la autorización:

O365.getUserProfile = function (userPrincipalName, callBackFunction, errorCallBackFunction) {
 

 $.ajax({
 

 url: baseUrl + '/users/' + userPrincipalName,
 

 type: 'GET',
 

 dataType: "json",
 

 success: callBackFunction,
 

 error: errorCallBackFunction,
 

 headers: {
 

 'Authorization': 'Bearer ' + O365.token,
 

 }
 

 });
 

 }

 

Disponéis de más recursos: