Bogotá - Colombia
Microsoft Graph es la puerta de enlace a datos y la inteligencia de Microsoft 365. Microsoft Graph proporciona un modelo de programación unificado que puede usar para aprovechar la gran cantidad de datos. Esta es la herramienta poderosa que nosotros los desarrolladores tenemos para la construcción de excelentes soluciones de servicio utilizando servicio de microsoft y todo con un API-REST y sera la herramienta que usare para Office 365 la asignación de licencias de office 365
Actualmente muchas organizaciones utilizan Office 365 y suelen comprar las licencias a proveedores o terceros y no directamente a Microsoft; en la compañía que trabajo se invierte en la compra de licencias de Office 365 para uso propio y hasta el momento no se ha tenido problema haciendo la compra directamente a Microsoft.
Sin embargo este proceso sigue siendo manual, es necesario ejecutar comandos de PoweShell que por cierto aca se hace una buena explicación de como se lograría hacer y donde creo que es necesario usar Microsoft Online Services Sign-In así que no entrare en detalle.
Tabla de contenido
Contexto
Es importante tratar algo de teoría antes de entrar a hacer la explicación.
Tenant
Este es un proceso que a un no se como funciona ya lo realiza mi jefe y es la creación del tenant que es como un apartamento de nuestro edificio(compañía) en la nube azure aca se explica con mas detalle.
Ejemplo
En el siguiente ejemplo muestro como se vería el dominio del tenant furiosojack
furiosojack.onmicrosoft.com
Usuarios
Hacen parte del dominio del tenant y se crean dentro del Directorio Activo de Azure.
Licencias
Son las que se le asignan a los usuarios y pueden ser de vario tipos sin embargo la que no interesa es Office 365 Business
Por cada tenent tendremos un usuario y clave para administrar todos los servicios de ese tenant en la nube de azure, asi que se tendrá acceso al portal de azure y se vera algo como esto.
Sin embargo la parte que nos va interesar es la de Azure Active Directory.
Resumiendo las licencias de office 365 son asignadas a usuarios del directorio activo de azure de esa forma cuando se descarga el instalador de office 365 en el equipo final para la activación se hace con el username y password del usuario.
Aclaración dudas antes de continuar
Creo que es pertinente hacer una pequeña aclaracion, explicacion por si voy rápido.
Me ayudare de la siguiente imagen, tómense un momentos y analicenla
 |
| Proceso de autenticacion y autorización del usuario |
La imagen no es la mejor explicación pero da un idea Jajaja
La aplicacion que vamos a crear como intermediario es la que esta esta entre nosotros(Solution Provider) y Office 365 Management API y sera la encargada de entregarnos el Access Token para usar Microsft Graph y crear los usuarios y signare licencias a ellos.
El flujo del proyecto se veria de la siguiente manera.
1: Login
Comenzamos teniendo una pagina donde aremos que el usuario sera redireccionado hacia una pagina espefica de autenticacion de microsoft descrita mas adelante-
entonces bueno yo para efectos prácticos puse un hipervinculo y ira a una pagina como esta
aca es donde el pone el usuario y clave del tenant donde se van a crear las licencias, cuando se logue correctamente sera redireccionado nuevamente al nuestro proyecto
2: Callback
Como dije antes al usuario autenticarse en la pagina de microsoft sera redireccionado nuevamente a nuestro proyecto pero en esa redireccion microsoft nos entregara un el Auth Code que se ve en la imagen del proceso de autenticacion y autorización del usuario.
Acá se hace un proceso interno que es trasparente para el usuario y es donde hacemos una petición con el Auth Code y en donde como respuesta obtendremos el tan preciado Access Token que se muestra en la imagen del proceso de autenticacion y autorización del usuario.
3: Portal Creacion
Cuando ya tengamos el Acceso Token se le muestra al usuario un portal donde pueda interactuar, básicamente el que yo cree es este
aca el usuario puede seleccionar el tipo de licencia que se van a crear, ingresar el numero de licencias a crear, el prefijo de los usuarios y el password que van a tener los usuarios(todos van a tener el mismo password).
Ejemplo
Tipo de licencia: O365_BUSSINESS
Cantidad: 2
Prefijo Usuarios: Furioso
Password: holamundo51sdF
Entonces se crearían 2 Usuario en directorio Activo de Azure y se verían así
- Furioso_1@furiosojack.onmicrosoft.com
- Furioso_2@furiosojack.onmicrosoft.com
Ahora entenderán por que digo prefijo ya que lo programe de tal forma que le concatene _1, _2, _3 según el numero de usuarios que se creen y furiosojack seria el nombre del dominio del tenant.
Asi lo vería el usuario cuando se crea
Asi se vería en el directorio Activo de Azure
y el usuario con su licencia asignada
Este proceso de creación de usuario y asignación de licencias ya se hace directamente con Microsoft Graph mientras el Access Token no expire
Manos a la obra
Para comenzar obviamente ya teniendo un tenant con su usuario y password lo primero que se hace es crear una aplicación la cual nos va a proveer el medio para autenticarnos con OAuth2 y nos entregue el token necesario para usar Microsoft Graph.
Para ello en la pagina https://apps.dev.microsoft.com nos logueamos con el usuario y password del tenant, tendremos algo como esto
Yo me imagino que es la primera vez que ingresan, asi click en el boton de Add an app
Yo le voy a llamar a la aplicación furiosojack y doy click en el boton de Create
En esta parte es importante ya que es donde vamos a configurar los permisos que va a requerir la aplicacion y donde obtenemos el ClientID y el Secret para la autenticacion OAuth2.
Comenzamos guardando la Application Id (El que esta en resaltado en amarillo) que sera nuestro ClientID, luego generamos el Secret asi que click en Generate New Password para que nos genere algo como esto y no lo copiamos y guardamos bien.
como paso siguiente click en Add Platform y llegamos un punto donde se puede explorar la plataforma a la que va dirigida sin embargo yo use Web
Aca se solicitara 2 Url, la primera de redireccion cuando el usuario lo loguea en la pagina de microsft y este va a rediccionar al usuario a la url que especifiquemos y la segunda que es cuando el usuario cierra la cecion sin embargo hasta el momento no la he usado.
Cabe resaltar que me deja ingresar las url con HTTP pero cuando ya este en producción las url tiene que ser con HTTPS.
Guardamos los cambios dando click en el boton Save
Para finalizar nos vamos a la sección de permisos
y nos encontramos que existen dos tipos de permisos, los permisos delegados y los permisos de aplicación, saber que permisos tiene que tener la aplicacion no los va a indicar los metodos de Microsoft Graph que vamos a usar.
Por ejemplo ya dije que necesitamos crear usuarios a los cuales le asignamos la licencia entonces dirigiéndose a la documentacion de los usuarios de Microsoft Graph que esta en github tenemos.
yo diria que podria llegar a usar esos metodos y entrando el metodo de crear usuario
me dice que tengo que tener 5 Permisos (hasta el momento creo que no se va requerir otro permiso mas en nuestra aplicación).
- Delegados
- User.ReadWrite.All
- Directory.ReadWrite.All
- Directory.AccessAsUser.All
- Aplicacion
- User.ReadWrite.All
- Directory.ReadWrite.All
entonces pues dando en el boton de Add de cada tipo de permiso buscamos seleccionamos y damos en ok.
y se vería algo como esto
y pues ya saben click en el botón Save par guardar los cambios
Llegados a este punto ya tenemos lo necesario para construir el proyecto para la creacion de las licencias pero lo correcto seria decir crear usuarios y asignarles licencias. Cabe aclarar que esta aplicación va a servir para cualquier tenant, osea si yo se que se crea con un tenant pero va estar disponible para que cualquier tenan como medio para obtener el Access Token, por ejemplo ustedes podrían usar mi aplicación para loguearse y crear sus licencias con sus tentant ya que como he dicho varias veces esta aplicación solo es el medio para obtener el Access Token, microsoft tiene otras formas de hacerlo pero para mi tiene tantas cosas que eso esta hecho un desorden ya que uno no sabe si hacerlo por esta forma o por la otra y ademas la información no esta facil de encontrarla.
Pruebas
Para hacer pruebas y ver que la aplicacion funcione se puede usar el siguiente ejemplo en python https://github.com/microsoftgraph/python-sample-auth en el cual simplemente se listan los usuarios del directorio activo de azure. Se clonan el repositorio y cambian en el archivo config.py los datos que ya tenemos, obviamente añadirnos la url de redireccion que pone en el archivo en nuestra app para que funcione.
Luego corremos el script para que lance el servidor
ingresamos al navegador y damos en connect
Ya nos muestra el listado de usuarios y asi comprobamos que funcione.
Proyecto
Hasta el momento ya tenemos claro que para las «crecion de licencias de office 365» lo que necesitamos es: Autenticacion por OAuth2, Creación de Usuarios, Asignación de licencias a usuarios.
Dejare estos dos manuales que seran de ayuda
- https://docs.microsoft.com/es-es/azure/active-directory/develop/active-directory-graph-api-quickstart
- https://msdn.microsoft.com/Library/Azure/Ad/Graph/api/api-catalog
El segundo fue el que me fue de mas utilidad ya que esta el catalogo de los metodos que puedo usar y como armar las peticiones.
Paso 1: Autenticacion
Es la parte mas importante, tenemos que programar el cliente OAuth2 para que haga el proceso de redireccion para la autenticacion, luego la autorizacion para obtener el Accesso Token, lo bueno es que actualmente exiten infinidad de clientes OAuth2 con licencia MIT para que usen, en GitHub Existen 13K en repositorios, es alucinante.
En mi caso no fue tan bonito por que el cliente que yo tenia que tener deberia correr en antiguo PHP 5.3 🙁
Sin embargo para mi caso de php5.3 encontré paquete de composer llamado PHPoAuthLib no tenia el cliente de MicroSoft Graph asi que le hice un Fork y le cree el cliente como lo pueden ver en aca. Ya le hice el pull Request para que el creador del paquete pueda añadir los cambios en la siguiente versión pero como que no volvio a conectarse por que ya pasaron 8 dichas y no ha hecho nada. Aca también pueden ver un ejemplo de como se usa.
Continuando con el tema los datos que todo cliente OAuth Requiere son:
- ClientID
- SecretID
- Url Rediccion o CallBack
- Url de Autorizacion
- Url EndPoint para obtener el Access Token
Ya tenemos 3 de las 5 y ahora lo que falta
- Url de Autorizacion: https://login.microsoftonline.com/common/oauth2/authorize
- Url EndPoint: https://login.microsoftonline.com/common/oauth2/token
y puede que lleguemos a necesitar la url de resource que es https://graph.windows.net/
Paso 2: Creación del Usuario
Para crear el usuario nos dirigimos al catalogo y en la sección de crear usuario https://msdn.microsoft.com/Library/Azure/Ad/Graph/api/users-operations#CreateUser se muestra que para crear el usuario necesitamos hacer una petición POST a la url https://graph.windows.net/myorganization/users?api-version
pasando como unico dato por la url el api-version la cual a dia de hoy es la 1.6 quedando la url
ademas la peticion en las cabeceras debe tener el Content-Typecon valor application/json y obviamente también la cabecera de Authorization que se explica con mas detalle en el manual uno que deje pero que ya el cliente que usen automáticamente ya sabe que debe poner esas cabeceras.
y en el body de la petición debe ir el son con el formato como este:
{ «accountEnabled»: true, «displayName»: «Alex Wu», «mailNickname»: «AlexW», «passwordProfile»: { «password»: «Test1234», «forceChangePasswordNextLogin»: false }, «userPrincipalName»: «Alex@a830edad9050849NDA1.onmicrosoft.com» }
Con fines prácticos usare la siguiente aplicación que provee Microsoft para las pruebas https://graphexplorer.azurewebsites.net/
Simplemente se loguean(que es lo que hace mi aplicación que mostré anteriormente).
Ingresamos lo datos(no es necesario poner el api-version ya que el lo hace por nosotros) quedando algo asi
Ahora simplemente si le doy Go se hace todo el proceso.
No olviden cambiarle el dominio de su tenant para que no les pase como ami que deje el mismo dominio que sale en el ejemplo Jajaj
Entonces cuando la petición es correcta y se crea el usuario en directorio activo la respuesta de la solicitud como especifica la documentación responderá con el resource del Usuario creado viéndose algo asi:
y si reviso el Directorio Activo de Azure ya debe aparecer
Sin embargo como es de esperarse no tiene ninguna licencia asignada
y es aca donde entra el metodo assignLicense el cual indica que se tiene que hacer una peticion POST a la url
donde el user_id seria en mi caso Alex@furiosojack.onmicrosoft.com y en el body de la peticion que valla un json como el siguiente
{ «addLicenses»: [ { «disabledPlans»: [], «skuId»: «6fd2c87f-b296-42f0-b197-1e91e994b900» } ], «removeLicenses»: [] }
donde el skuId el el id del tipo de licencia a asignarle al usuario.
Para saber cual es ese id, tenemos que listar todos los tipos de licencias que el tenenat tiene asi que no valemos del método subscribedSkus que ese si no se encuentra en la documentación del segundo catalogo que puse, se especifica directamente en la documentacion de Microsoft Graph.
En esa documentacion se indica que la peticion se tiene que hacer a la url
sin embargo aca es donde nos damos cuenta que no estamos usando directamente microsoft graph Jajaja
entonces adaptando ese método a la url que hemos manerado a la que nosotros tenemos hacer hacerle una peticion GET es a la url
y se vería como esto
Sin embargo en la imagen no se ve el skuId, toca bajar un poco
y ya lo tenemos dice que tengo un tipo de licencia tipo O365_BUSINESS, copiamos ese skuID y pues asignándosela al usuario, la petición se vería algo asi
Puede pasar dos casos que no retorne nada la petición como se especifica en el segundo catalogo o se devuelva el resource del usuario al que se le asigno la licencia.
Asi se vería en el directorio activo de Azure
FIN
Y eso es todo ahora solo hace falta descarar el software de office 365 instalarla en el equipo y activarla con el usuario y password del usuario que creamos, yo creo que con eso es suficiente para comenzar.
