Azure AD (III): Graph API
A lo largo de esta serie de post hemos visto qué es el Directorio Activo de Azure y cómo desarrollar aplicaciones que lo utilicen. Ahora vamos a ver cómo utilizar Graph API para acceder y hacer operaciones en él. Como ya comentamos anteriormente existen diversos protocolos para realizar la comunicación con el directorio activo, Graph API utiliza OData.
Graph API permite acceder al Directorio Activo a través de los endpoints de la API REST. Las aplicaciones pueden usar Graph API para realizar operaciones de creación, lectura, actualización y borrado (CRUD) sobre los objetos y los datos del directorio. Algunas de las cosas que se pueden hacer a través de la API son:
- Crear un nuevo usuario en un directorio
- Recuperar las propiedades de un usuario, como por ejemplo a qué grupos pertenece
- Actualizar las propiedades de los usuarios
- Comprobar el role de un usuario para la autenticación basada en roles
- Deshabilitar una cuenta de un usuario o borrarla
A parte de operaciones sobre usuarios se pueden realizar operaciones sobre otros tipos de objetos como grupos o aplicaciones. Para que una aplicación pueda hacer llamadas a Graph API ha de estar registrada en el directorio y configurada para tener acceso al mismo.
Graph API tiene las siguientes características:
- Es un servicio RESTful compuesto de endpoints a los que se accede usando peticiones HTTP estándar. Soporta los tipos XML y JSON para las peticiones y respuestas.
- Todas las peticiones a Graph API han de ser autenticadas añadiendo un JSON Web Token (JWT) en la cabecera de autorización de la petición.
- Permite autenticación basada en roles (RBAC).
- Permite las consultas diferenciales para saber los cambios que se han producido en el directorio en un periodo de tiempo.
Respecto al funcionamiento, en Graph API para acceder a los datos y los objetos del directorio para realizar operaciones CRUD, se usan URLs basadas en el protocolo OData. Las URLs consisten en cuatro partes principales: la raíz del servicio, el identificador del tenant, la ruta del recurso y los parámetros de la consulta.
https://graph.windows.net/{tenant-identifier}/{resource-path}?\[query-parameters\].
La raíz del servicio es siempre https://graph.windows.net.
El identificador del tenant puede ser un dominio verificado, un ID de un objeto tenant o un alias.
La ruta del recurso representa el recurso con el que se va a interactuar (usuario, grupo, un usuario particular o un grupo particular, etc).
Los parámetros de la consulta se separan de la ruta del recurso por el símbolo ?. El parámetro “api-version” es obligatorio en todas las peticiones. Graph API también soporta $filter, $orderby, $expand, $top, y $format.
Para poder realizar pruebas mientras vas construyendo la aplicación se puede utilizar Graph Explorer.
En la parte superior de la derecha de la pantalla vemos que tenemos la opción de acceder a la documentación y de usar una compañía de demo. La compañía de demo nos permite hacer pruebas con un directorio de demo que ya está creado.
Por ejemplo, si queremos consultar los usuarios que hay en el directorio ponemos: https://graph.windows.net/graphdir1.onmicrosoft.com/users?api-version=1.5 .
Al ejecutar la petición vemos que nos indica el tiempo que ha tardado en hacer la petición. También nos permite ver las cabeceras de la respuesta lo que resulta muy útil a la hora de solucionar errores derivados de las peticiones.
Es posible seleccionar si queremos ver la respuesta como texto plano o como JSON.
En el cuadro de texto aparecen varios modelos de consultas que podemos probar.
Para utilizar esta herramienta contra nuestro directorio y no con una empresa de demo, debemos pulsar en Sign In e introducir las credenciales de nuestra cuenta del directorio activo de Azure.
Si aún no tenemos creado un directorio con al menos un usuario debemos crearlo primero desde el portal clásico de Azure. Para más información de cómo crear un directorio puedes ir al primer post de esta serie.
Una vez ya tienes el directorio creado, al pulsar sobre Sign In se abrirá una ventana para introducir las credenciales (estas credenciales son las credenciales que tengas como usuario del directorio activo).
La primera vez que realices el acceso es necesario que autorices el acceso.
Una vez autorizado podrás hacer las consultas desde Graph Explorer contra tu propio directorio.
Esto lo que te permite es probar las consultas antes de implementarlas en el código y ver el tipo de respuesta que envía la API en cada caso.
Graph Api soporta el uso de los alias “me” y “myorganization”. Por ejemplo, si queremos consultar los datos del usuario que ha iniciado sesión podemos poner https://graph.windows.net/demodirectory2016.onmicrosoft.com/me?api-version=1.5 y nos devolverá los datos sobre el usuario.
El alias de “myorganization” facilita la construcción de la URL de petición. Por ejemplo, si queremos saber todos los usuarios de nuestra organización podemos poner
https://graph.windows.net/myorganization/users?api-version=1.5. 
Cuando estamos desarrollando nuestra aplicación y necesitamos realizar operaciones sobre el directorio activo utilizando Graph API hemos de hacerlo utilizando peticiones HTTP con el formato mostrado anteriormente. Todos los detalles sobre qué operaciones están disponibles a través de la API y cómo hacerlas desde el código de la aplicación están en la siguiente página: https://msdn.microsoft.com/Library/Azure/Ad/Graph/api/api-catalog. Los ejemplos de código están hechos en varios lenguajes: C#, Curl, Java, Python, Javascript, ObjC, PHP y Ruby.
Para ver proyectos completos que utilizan Graph API puedes acceder a la siguiente página: https://azure.microsoft.com/en-us/documentation/articles/active-directory-code-samples/ en el apartado Calling Azure AD Graph API. Una vez selecciones el lenguaje en el que te gustaría ver el ejemplo te redireccionará a una página de GitHub donde se encuentra el proyecto en la que además del código, hay información detallada de cómo crear un proyecto desde cero.
Beatriz García Roces
Technical Evangelist Intern