APIs de Office 365 (I)

Este es el primer post de una serie que quiero centrar alrededor de las APIs de Office 365 y donde revisaremos y explicaremos en detalle todo lo relativo a este tema desde el punto de vista del desarrollo de aplicaciones. Como es un tema extenso, no quiero hacer posts demasiado largos y sí hacer posts más breves (dentro de lo posible) que vayan cubriendo determinados aspectos del tema (registro, autenticación, permisos, desarrollo app web, desarrollo app nativas, etc.).

Una de las novedades más importantes mostradas en la SharePoint Conference 2014 fue la presentación de las nuevas APIs REST de Office 365. Inicialmente fue liberada una versión Preview de las mismas, pero actualmente ya disponemos de la primera versión en Release.

La principal ventaja de estas APIs es precisamente que son un API REST, es decir, podemos consultar Office 365 independientemente de la plataforma donde se ubique nuestra aplicación y de la tecnología que usemos. Al final estamos usando peticiones HTTP que contienen toda la información que necesitamos para ejecutar una operación concreta.

En la versión actual, las APIs de Office 365 proporcionan acceso a varios servicios: Exchange (correo, calendarios y contactos), SharePoint Online y OneDrive for Business (archivos y carpetas) y Azure Active Directory.

Para poder acceder a los servicios, previamente debemos haber registrado nuestra aplicación en Azure Active Directory, ya sea mediante el portal de Azure o bien a través de Visual Studio 2013.
Las APIs de Office 365 cumplen el estándar Odata 4.0, así como Oauth 2.0 para autorización y autenticación.

Primeros pasos

Muy bien, pues ya tengo una idea general de lo que es esto de las APIs REST de Office 365 y ¿ahora qué? ¿Por dónde empiezo? ¿Cómo puedo aprovecharlas?
Con estas APIs REST de Office 365 vamos a desarrollar lo que se denomina una app de Office 365, ¿y cómo podríamos definir ese tipo de app?
Un app de Office 365 es una aplicación web o un web api, también puede ser un App de Office (Word o Outlook), también puede ser un app de Windows o de Windows Phone o incluso un app en dispositivos no Microsoft tal como IOS o Android.
¿Qué tienen en común aplicaciones tan distintas para ser todas denominadas apps de Office 365? Principalmente que todas y cada una de ellas deben ser correctamente registradas en Azure AD y que todas se comunican con Office 365 a través de las APIs REST.

Registro de una app de Office 365 en Azure Active Directory

Cuando queremos desarrollar una app de Office 365 uno de los primeros pasos que tenemos que dar es registrar dicha app en Azure Active Directory. Actualmente Microsoft nos ofrece dos vías para hacerlo: Azure Management Portal y Visual Studio.

Registrando una app de Office 365 a través de Visual Studio

El proceso de registro a través de Visual Studio es muy sencillo y nos abstrae realmente de todo el proceso completo que hay por debajo. Esto es muy de agradecer, ya que al empezar a abordar el tema de desarrollo de las apps de Office 365, nos hace centrarnos en el desarrollo más en sí mismo que en los detalles de seguridad que rodean el funcionamiento del API y Oauth.

Para empezar necesitamos crear un proyecto nuevo o abrir uno existente. Como hemos comentado antes, puede ser tanto un proyecto web, como un proyecto de App de Windows, etc. Para mostrar el proceso optaremos por una aplicación web MVC.

Una vez tengamos en Visual Studio nuestra solución con el proyecto, hacemos clic derecho sobre el proyecto y seleccionamos “Add>Connected Service”:

Nos aparece la siguiente ventana, en donde vemos que tenemos un enlace para registrar nuestra app:

Hacemos clic sobre el enlace y nos aparece una ventana donde se nos piden nuestras credenciales de administrador global de la suscripción de Office 365 donde queremos registrar nuestra app. Introducimos nuestras credenciales e iniciamos sesión:

Tras un pequeño intervalo de espera en el que Visual Studio está realizando operaciones en background, se actualiza la ventana del “Services Manager” y vemos lo siguiente:

En este punto nuestra app ya se encuentra registrada en el Azure Active Directory de la suscripción de Office 365. Fácil, ¿no? Sobre todo cuando veamos posteriormente cómo se hace manualmente el registro y lo comparemos.

Si hacemos clic sobre el enlace “App properties” nos aparecerá una nueva ventana con las propiedades del app:

Estas propiedades las ha rellenado Visual Studio automáticamente, pero desde aquí podemos modificarlas según lo necesitemos.

La propiedad “Name” es simplemente una etiqueta para poder distinguir unas apps de otras al registrarlas, en principio podemos poner el nombre que queramos.

En la propiedad “Make this app available to” indicaremos si nuestra app es single tenant o multitenant, es decir, si únicamente va a ser accedida por usuarios en la suscripción de Office 365 en la que estamos registrando el app, o si bien también puede ser accedida por usuarios de otras suscripciones. El tema de las apps multitenant lo trataremos con más detalle en un post futuro de esta misma serie.

La propiedad “Redirect URIs” como vemos la ha rellenado VS por defecto con la url desde donde depuraremos nuestro proyecto de aplicación web. Esta propiedad debe contener la url real donde los usuarios podrán acceder y logarse a nuestra aplicación. Por el momento la dejaremos así, pero una vez publiquemos nuestra aplicación web con una url real, debemos cambiar esta propiedad.

Si volvemos a la ventana del Services Manager vemos una lista con una columna de servicios y otra columna de permisos que inicialmente está en blanco. Desde aquí configuraremos los permisos que tendrá nuestra app sobre servicios existentes. Pero esto lo veremos con más detalle en el próximo post.

Lo último que nos queda reseñar de este proceso es que si nos vamos al web.config de nuestra aplicación web podemos observar que tras el proceso de registro VS ha añadido varias nuevas propiedades al mismo:

<add key=»ida:ClientID» value=»794a9953-b078-4b61-a1f5-f845f03635c5″ />
<add key=»ida:Password» value=»SfCVe5YLUHnbd0389kEUz8smVPEgGwVLIPCCVxkY7cM=» />
<add key=»ida:AuthorizationUri» value=»https://login.windows.net» /></appSettings>

Ya veremos en detalle en futuros posts para qué sirven todos estos valores y que son muy importantes de cara al tema de autorización y autenticación de nuestra app.

Registrando una app de Office 365 a través del Azure Management Portal

Ni que decir tiene que necesitamos una cuenta válida de Azure con la que acceder al Azure Management Portal y, por supuesto, una suscripción de Office 365. De hecho, si únicamente dispusiéramos de la suscripción de Office 365, tenemos la posibilidad de generar una suscripción de Azure vinculada directamente a la de O365 y en la que el Azure Active Directory principal sería el de O365. Lamentablemente, el caso inverso de momento no es posible, el tener una suscripción válida de Azure y poder crear una de O365 asociada.

En cualquier caso, vamos a ponernos en el peor caso, tenemos una suscripción de azure por un lado y por otro una suscripción de Office 365 y queremos realizar el proceso de registro de nuestro app. Antes de entrar en materia, me gustaría comentar que si no dispones de ninguna cuenta de Azure ni de O365, pero quieres probar el registro de apps puedes hacerte cuenta trial tanto de Azure (http://azure.microsoft.com/es-es/pricing/free-trial/), como de O365 con una suscripción de desarrollador de 30 días (Office 365 Free Trial).

Accedemos al Azure Management Portal, seleccionamos “Active Directory” en la columna izquierda,  pulsamos sobre “New” para crear un nuevo directorio activo en Azure. A continuación se nos despliega el menú tal y cómo vemos en la imagen de abajo y la única opción que tenemos es “Custom Create” sobre “Directory”. Hacemos clic sobre ella.

A continuación se nos muestra una ventana flotante tal y como la de la imagen siguiente:

Seleccionamos “Use existing directory” y la ventana cambia a la siguiente imagen:

Una vez marquemos el check “I am ready to be signed out now” y pulsemos el botón “Ok”, el navegador procederá a hacernos “sign out” de nuestro usuario de Azure y a continuación pedirnos las credenciales del administrador global de la suscripción de Office 365. Una vez nos hemos autenticado nos aparece el siguiente mensaje:

Hacemos clic sobre “continuar” y a continuación nos aparece el siguiente mensaje:

En este mensaje se nos confirma que podremos acceder al directorio activo de la suscripición de Office 365 a través del portal de Azure. Cerramos sesión y volvemos a logarnos con nuestra cuenta de Azure.

A partir de este momento, cuando entremos en la sección “Active Directory” en el Azure Management Portal veremos incorporado el directorio activo de la suscripción que acabamos de vincular:

En adelante, haciendo clic sobre el directorio activo, lo tendremos disponible para registrar nuestra aplicación, así como para muchas otras operaciones comunes del directorio activo.

Pero después de todo este proceso, ¿qué ha sucedido realmente? ¿Por qué ahora podemos gestionar este directorio activo desde nuestra suscripción de Azure? Realmente lo que ha ocurrido entre bastidores es algo muy simple, ahora mismo nuestra cuenta de Azure es administrador global de la suscripción de Office 365. Si vamos a la sección de “Usuarios” del directorio activo veremos que la cuenta de Azure se encuentra entre ellos.

En este punto podemos comenzar a registrar nuestra aplicación de Office 365. Para ello, hacemos clic sobre el directorio activo en el que queremos registrar la app, una vez dentro del directorio activo nos vamos a la sección “Applications” y pulsamos en la sección inferior de comandos sobre el botón “Add”. Una vez pulsado se nos muestra la siguiente ventana:

Seleccionamos “Add an application my organization is developing”. Y a continuación nos aparece la siguiente ventana donde escribiremos el nombre de nuestra app, así como eligiremos el tipo de app que queremos registrar, si es una aplicación web (o web api) o una aplicación nativa (dispositivo móvil, app windows, etc.).

En este caso, rellenamos el nombre,  seleccionamos aplicación web y pulsamos sobre el botón de “Siguiente” y llegamos a esta ventana:

En esta ventana nos solicita dos datos más, por un lado nos pide “Sign-On Url” que es la dirección física de nuestra app, donde los usuarios se pueden logar para usarla. Inicialmente como lo que queremos es empezar a desarrollarla y probar, únicamente pondremos una url local “http://localhost:2938”. Por otro lado, se nos pide un “App Id URI” que no es más que un identificador lógico para nuestra app, no tiene que resolver necesariamente ningúna dirección real.

Pulsamos el botón de “Listo” y ya tenemos nuestro app registrada en AAD:

¿Hemos terminado con el proceso de registro? Realmente no, todavía nos faltan una serie de pasos relativos a seguridad y permisos, pero eso lo vamos a dejar para el siguiente post de la serie.