Una imagen en la que se muestran los recursos y relaciones principales que forman parte del gráfico

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.

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.

eHZHgh8xb pm1H0gepfL5s9hB6lLmYg7uuttpcYSlUV2QpFc6LKU5No3hhN456E1zVmBvCXu0ePa0ovDEJhRWPNat 1pm540bMla1Nu9UUj8dLymSVcrwSanO0LtJb8mrcvMqlim

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

uhqvrepX4A03xLERUgVt5kgXgTn

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.

fV56V3uH9yHY EszbjQFTPuLxLZMdG3Yx1yap8XXCvC3E2yD1DvUzfAcoGJQVIC9WvwYnLv8jAkGOfVAt5t0p5HQc1RdwgR6kMPDenoS47wuMPOnxsmFdeS flv8WWDfRp1Ava g

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

Management APIs getting started authorization flow
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-

9Sx5IMsupOJ8xN8lpFCI2CXHAIfZTymQXGcGz64

entonces bueno yo para efectos prácticos puse un hipervinculo y ira a una pagina como esta

ORhVbPPYc8PQT6HnL8yGRFQiyaNrMprpw7jK8ahF6nEW39nlQU caSZF0Q54WCTOsZLQUY0

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

7nDT r4V fjI0jombGgisphl0hIBpedif h6Fxs8OkmcNTeM2OgDfcjMc LHRx7BBHwV61a L4SZbb5PXXhbwOVh4fKZvTSZQpIKvVY7QRfhHpo0E8PgiMQFMCnFBaK4InJD0 2

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

zXKuWMUeZtXwIGInD2XndMlga776o1ajQAqTj43UD3VilwxC9RPx5 YDDC4z 51sN60THpHrxJDlCcNJABfFiN5TWaDZ15fjvh5S7Xb3rtdXOuzynO9drynsSggPgI PopvEorIn

Asi se vería en el directorio Activo de Azure

y4ufWW18MKOiozUtDzF MajYZttV24YKyGf4Zppn9YS5dXoaLgL5yy6DtKy6B0XyPcHdCNunNoNJiuwg 0Z21L7Zo5TOFRDNiyTBU0eoUv67jsuXP0NtBGUA0JgfJLWZgmGenZW7

y el usuario con su licencia asignada

xL993 bCuKJFVRXH1G0zxpUBe7hETVzW9tZ5ZoN2HWT53SkPDKSH1fy F2zL1s54oUtzDoICsMTQ31QbAqwlO2LExa40gxFdE943YQEV XeLMUHdMdShE9JHjYid3JzFzEX GA3c

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

eW1G1IyDJVA0ZH7qqvIELD 80NmVt1NxooD3lDOLOM

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

5wG57jBKVffRlzXSwrFzqVt9pA76nizLMSUjnqkGKBXVphkdkBpn6Obhkgix4U qJPfDxrUIsB09NJHG7iQg CqFEmgotm9ZuFWcnpVmMANy2LXSQujm8sdvVCaIhEFyErwUAbFa

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.

JdcxXfdzHfN8xGIQi q aDbAaL 4572jriiQPJCf43hxLK9Y7 cDPf0UUCr15 TheHeEsb9 2URUW7vgD1OzNaio0f1N8PGQeHI0D9h4roO6G0Zl 7OgH2wQKKHvWx Nou z3pCj

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

xv TDQoEA KpdFqL17Aw KZIQOT7O73jqZB6DopnWN2t5

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

VHX aLSfouYMjj9 z9XU x7eS5agGTxdkcmjSQE4qosAklD4vxTPoNt8u 0 sAyLZwmvoAmv4vxekPG61dDg7XWhidzqyPNtHe8 ji2FyCc8XfEnru 7lXqjpB9FPb3Q9zlhVQ6

Para finalizar nos vamos a la sección de permisos

nkv4gHl0ykqysTJ9xOxi2uL4ugtK1yHy7L4UfxtPw2TsojtqarKm8hPzQDEKkN9HfQ0vofql21wayiXjkVnEkeVxf2GKvIeQOjBFhl3n 5pPepN0Fw RMn8yYUpWPVsqTt7 Oerw

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.

UQuHqsLCFWlSPnIstXxRlY5j5YQKSvYL7lSKYzK Be62VIem

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.

nRXb kR2w1EnyI480sYjijc3pV8ZzTvu10G5wHOiHz1aZj BM5g6fGc4RnvBhYH1JJJ l55kCAEHX45k1nqnq1aiOzTAJlpUS8ETbqWmnGtJdSiw2ANXBkv8YYUk2ouFbEnOMwLq

y se vería algo como esto

ZukY fARMpfSiyST0CsBZ9TeJfMU245t CRNzk9pkhsFzPOHCcKGo6buXVADw uAUHDXUOrLbFU48vq rXXAcuzpVKnB4pn v0Cbq4c8k TDauqIdlfWH4WJBsrGZ0grV3N7ZIeP

y pues ya saben click en el botón Save par guardar los cambios

56EdTtO1hfgqQk4N6QEOq52aekTGxNsMKBu912Mqk1yxASum7ImhHFZ l1Wa4jLtmDWnWoOR3DinK9b oml945sZ4y9zrulaCACgaeY8kMgaYJ2TIXd 66XqajbIK EuXwuInzny

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.

F5rGVcTX4RtuV bKHJH MMtpu1QU3JOCLZatxyX5qPra ZcwYBkbkgLWcdKb 4oaxEFB10NCol27n1HCTPXdPCZYZfAXAstWVXrxDm XhrZN5AFClY blpCcaMhuIsp2bRj0Tlu

Luego corremos el script para que lance el servidor

xYhQhL6TgR6Ru1Vf 11ZiJyt2Jq6BhlypgD EwzeV5IsVrOzk 1WNq 8dRXd3zUzwK6r03dQ4fcTig RAwlKTPUc5J6RzSpbdd7yqcR9 iQmxqSQ4zd4 qMXqBd25dfKW Czi Pa

ingresamos al navegador y damos en connect

JYDTk75noAS5BcrhOnJRKBzxggZ8rCUFn2scmuSLBeAPX4PKEQFPAWhPfj8yfAxRGk8VUxP7 K1fzwgCpM LTg beQHHZBmUY5m8EQ68 Sn711FdvK1CKrcfJwDLLU8 q3fvCKH

Ya nos muestra el listado de usuarios y asi comprobamos que funcione.

N2wPDdsI CsSKHc gSyB ht5Dx8wCvhmBGvPeAjYi9rWgjHnfSKNfvwPJSBP0EmkPSfHGh8SUG lqKGtDy4gALnt9mE9nn3S2Smflmlr6FmprySv72i7Bya6Bq

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

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. 

4l3Lafrq9U21xaYJvUK DKR07zrKDKBiQRYlaIBlL80V8ICATi4bXGkTPpPeShrZP0C9AXaS5MS9nO0GNEDIFGMZ5yixFwTMHjDiWFH4xjuiM9Co1

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

https://graph.windows.net/myorganization/users?api-version=1.6

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/

JP6nOAwIxvLLbDhTKWy5dH8XMq8SV2E9E9zkWqrHxmx37u vjwHQKg5UX49f0EXWAndraDDzRvpIQnTh4NSa9MX06MLoJSpucq TFKMiyHc1xo lOnfKMErUKD2l3jseNUhg0Sjg

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

MtKknhbE bxaTsOzNXhBAxk5NaZFEEWSD2j3WIR1NbuQMmfUmGv RiM50FsCCg19q1FLm67K

Ahora simplemente si le doy Go se hace todo el proceso.

iEgSb6XNiO5KTsfnpS5njj QZvZzq3KoOWcZbyrV5w94AOlqoUOW14rWzQ87 LmU942PD8eClyWZ1SVN35gUH z3aWXxF8zAw3KzCSZrNTu0T4nE1o79vBs9t2q IaYH1Fhng0G

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:

n8abd1WtZgYzryPue OF5iufq9kB VBpeuLxWMU1ykAx8J1vrXLIzsPtvyLYhd955es9n4VdtZw5gYi2u0ExbNHUczFXYLAob7FJsQ iFkT9vr

y si reviso el Directorio Activo de Azure ya debe aparecer

d31 iaj04f7mjjPJ4kk17tDZ9bYJR1iPjt5Uqi8xxBxKj cZJFXyxL9SN9nrKugcgjsXJ1reYVHwGwi T zwWHzna N0aRhiwyO9BJcMr0HREeqksR3uJIukizc MvrozEHWGgMY

Sin embargo como es de esperarse no tiene ninguna licencia asignada

h4Wh6gYVYblR4ibI wVICFxJL8C9mben

y es aca donde entra el metodo assignLicense el cual indica que se tiene que hacer una peticion POST a la url

https://graph.windows.net/myorganization/users/{user_id}/assignLicense?api-version

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

https://graph.microsoft.com/v1.0/subscribedSkus

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

https://graph.windows.net/myorganization/subscribedSkus?api-version

y se vería como esto

CuAuf Ufk83DuGkvKLZsAyLkod2 XD2efAjRoPZSsMzHEQy8Pm71LukcrGz3Em Mfq7WOZ62R76BmSxgYG3Ki7S6MM10MCYNP0qWzTdfuRTMz FzEWcsegKUV9UB3KnZ0ddVNri

Sin embargo en la imagen no se ve el skuId, toca bajar un poco

K8SQKVzAezyTl5Fx er8ktmvS3 ASmqAC UJnLTz IrnDtyTM7VpBHG5SwGBcu4NemIwNWx3lcoNwJLfydFys2dYZ x6a3Q1OOz Cus

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

a3Bi9KOeSny eK6K NmaNMCYFYb64k0KZy31bLfZr6Y1N6Td08Cc hI

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

wEt9c9yb68fQz8ThL7UJpoouLd3aSJnd1y9t9z9w k

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.