OAuth2.0 & Business Central Service to Service. Ejemplo de uso con .net

 nivel: developer

OAuth2.0.  Como llamar a las API de Business Central sin intervención humana

Hasta ahora, muchos de nosotros usabamos Web Key (básica), como autenticación para acceder a nuestras API's o servicios web.  Como seguro ya sabéis, Business Central lleva ya tiempo avisando de que va a eliminar el uso de esta autenticación en la release de Abril de 2022 por lo que antes de que nos pille el toro, vamos a ir cambiando nuestros programas para evitar problemas.

Tenemos tres pasos a seguir para usar la autenticación OAuth2.0 con Business Central:

- Registrar y dar permisos a la aplicación desde el portal de Azure
- Registrar y obtener el consentimiento desde Business Central

- Hacer la llamada desde el exterior

Registar la aplicación en Azure 

Lo primero que debemos hacer es registrar nuestra aplicación en Azure.  Para eso iremos al portal de azure (https://portal.azure.com) y buscaremos por Azure Active Directory.  Una vez allí entraremos en Registro de aplicaciones y en nuevo registro.

El registro de una nueva aplicación nos pedirá:

- Nombre: Nombre que le daremos a nuestra aplicación.

- Tipo de cuenta: Si la llamada va a efectuarse desde fuera de nuestro tenant, deberá ser "Cualquier directorio de Azure AD: Multiinquilino")

- URI de redirección: Nos indicará la web de redirección una vez autenticado.  En nuestro caso: https://businesscentral.dynamics.com/OAuthLanding.htm

Al pulsar el botón registrar y tras unos instantes, nos genera el registro:

El ID de aplicación (cliente) generado, lo utilizaremos posteriormente tanto en Business Central, como en nuestra llamada.

Para completar nuestro registro debemos añadirle permisos a la API.  Para ello, pulsaremos en "Permisos de API" y buscaremos "Agregar un permiso".  En la ventana que nos aparece seleccionaremos "Dynamics 365 Business Central":

Si lo que queremos es que la API tenga sus propios permisos y no dependa de un usuario, seleccionaremos la opción "Permisos de la aplicación":

Seguidamente, el permiso a seleccionar es API.ReadWrite.All.   El resto no son necesarios, salvo que usemos las API de automatización.

Para finalizar en Azure, deberemos de crear una clave secreta.  Eso lo haremos desde "Certificados y secretos". Nos pedirá un nombre y una fecha de caducidad.  Como máximo podemos ponerle dos años de validez.

Esto nos genera la clave secreta disponible para acceder a la API. 

Atención, copia en lugar seguro el valor (Clave secreta) ya que posteriormente ya no se puede volver a visualizar.  El dato necesario es valor.  El Id. de secreto no nos hace falta.

Con ésto, hemos finalizado de registrar la aplicación en Azure.  Ahora iremos a Business Central para configurar el acceso.

Configurar la aplicación externa en Business Central

Para configurar la aplicación iremos a "Aplicaciones de Azure Active Directory" y pulsamos nuevo:

    

Allí como ID de cliente, pondremos el "ID de aplicación (Cliente)" generado en Azure al registrar la aplicación.  Pulsaremos editar para indicarle una descripción así como añadir los permisos necesarios a nuestro acceso, como si de un usuario se tratase:

Consideraciones importantes.

- La aplicación debe registrarse en el mismo tenant que el Business Central al que vamos a llamar.  

- En función de los requerimientos de nuestra API le asignaremos los permisos necesarios. La "ventaja" es que si no se puede ejecutar por permisos de Business Central, el propio mensaje de respuesta de "no autorizado" nos indica a qué objetos no se ha podido acceder.

- No se permite asignar permisos SUPER a una aplicación, por lo que deberemos de definir un conjunto de permisos más restrictivo.

Una vez configurados los permisos, pulsar en "Conceder consentimiento" para solicitarlo a Azure.

En este punto, en cuanto obtengamos el consentimiento, ya tenemos configurada nuestra aplicación y ya podemos llamar a nuestra API desde Postman o desde cualquier software externo.

Acceder a las API desde un software externo

El flujo del funcionamiento sería el siguiente:

Los pasos 1 y 2, ya los hemos realizado desde Business Central al registrar la aplicación, por lo que aquí los que nos quedarán son el 3, 4, 5 y 6.

Para llamar a nuestra API lo haremos desde una pequeña aplicación en vb.net, en la que mediante dos botones, solicitaremos el token (paso 3) y haremos la solicitud a la API (paso 5):

  

Obviamente estos dos pasos se pueden combinar para hacerlo directamente o incluso verificar si el token solicitado anteriormente ha caducado o no antes de solicitar uno nuevo, pero para facilitar su comprensión aquí los he separado.

Paso 3 (botón token).  Solicitar token de acceso. 

El token de acceso es una "clave" que nos suministra la plataforma de autenticación (en este caso Azure Active Directory) para que podamos acceder a la API.  Para conseguirlo usaremos el siguiente código vb.net:

Línea 65: Creamos una variable httpClient

Línea 66: Hacemos la llamada a la entidad autorizadora.  En nuestro caso será Azure indicando el correspondiente tenant a través de la url:

https://login.microsoftonline.com/YourTenant/oauth2/v2.0/token

Línea 67: Indicamos en la cabecera que el mensaje llevará codificados una serie de valores en la URL.

Líneas 70 a 75: Generamos los comandos que añadiremos a la URL:

- Client_id : corresponderá a la ID de aplicación (Cliente) generada en el registro de la aplicación de Azure.

- Scope: Indicará el ambito donde se usará el token

- Tipo de credenciales: Para que no nos solicite ningún popup para autentificarnos (caso claro de máquina a máquina) debemos de poner "client_credentials".

- Client_secret: El valor de la clave secreta generada en Azure.

Línea 77: añadimos los valores al contenido del webclient

Línea 79: hacemos la llamada POST para recibir el token y guardamos la respuesta en una variable response.  En caso de que la respuesta sea correcta (status 200), nos devolverá un JSON con el valor del token y el tiempo de vida :

Paso 5 (Botón llamada).  Llamada a la API con el token.

En este caso, usaremos el token rebido y no caducado, para hacer la llamada:

Línea 19: creamos la variable httpClient

Línea 20: asignamos la url correspondiente a la API de nuestro tenant a la que qeremos llamar

Línea 22: Añadimos a la cabecera la autenticación con el token.  Sería "Bearer " + Token recibido.

Línea 25: Hacemos la llamada con un GET.  En caso satisfactorio, recibimos un JSON con el resultado de la llamada.

Aquí puedes verlo en acción:

  

Conclusiones.

Es necesario actualizar las llamadas a nuestras APIs lo antes posible para evitar problemas con nuestros clientes.  Espero que este post os ayude a ir avanzando.

Se podría usar una autenticación Password en lugar de Client_credentials, pero eso supondría tener que vincular un usuario concreto a nuestra API con el consiguiente riesgo.

Finalmente me gustaría agradecer a Arend-Jan Kauffman, por su apoyo cuando me han surgido problemas y a sus blogs que me han ayudado a completar mis pruebas.

Cualquier duda, podéis contactarme por los medios habituales de twitter  o linkedin.