Autenticación del API de Bizagi

<< Clic para mostrar Tabla de Contenidos >>

Navegación:  Bizagi Studio > Bizagi desde aplicaciones externas > API de Bizagi para aplicaciones externas > Servicios RESTful OData >

Autenticación del API de Bizagi

Seguridad en el API de Bizagi

Los servicios de OData en Bizagi están protegidos y cuentan con un mecanismo de autenticación estándar: OAuth version 2.0.

Las solicitudes presentadas a estos servicios necesitan ser concedidas con derechos a los recursos, utilizando las llaves OAuth previamente generadas.

Con la especificación de OAuth version 2.0, Bizagi soporta los dos flujos de OAuth, que son los más utilizados:

 

Código de autorización:

Esto permite a la aplicación del cliente autenticar a los usuarios con las credenciales introducidas en tiempo de ejecución (a través de una página de inicio de sesión).

Este flujo es diseñado para la interacción humana, dónde las solicitudes utilizan la suplantación de los usuarios finales.

Para más información sobre esta especificación, refiérase a https://tools.ietf.org/html/rfc6749#section-1.3.1.

 

Credenciales del Cliente:

Esto permite la integración de servidor a servidor sin el uso adicional de credenciales específicos de usuarios finales.

Para más información sobre esta especificación, consulte https://tools.ietf.org/html/rfc6749#section-1.3.4.

 

Bearer Token:

Esto permite a la aplicación del cliente autenticar utilizando un token.

Para más información sobre esta especificación, refiérase a https://tools.ietf.org/html/rfc6750.

 

Lo que debe hacer

Para invocar los servicios OData de Bizagi, tenga en cuenta este esquema a alto nivel:

 

1. Registrar una aplicación OAuth

Este primer paso consiste en otorgar acceso a la aplicación externa, mientras se crean las llaves de acceso adecuadas.

Esto es un requisito para poder hacer uso de los servicios OData.

2. Obtener el token de autorización

Este paso hace uso de Postman para establecer una comunicación autenticada con los servicios OData.

Una vez se haga uso de las llaves de acceso, se le dará un token de acceso para realizar más peticiones.

 

Pasos

1. Registrar una aplicación OAuth.

Diríjase al Portal de trabajo. Haga clic sobre la opción Aplicaciones OAuth2 en el menú Admin, bajo la sección de Seguridad, para poder otorgarle permiso a una aplicación externa.

 

OData_Workportal1

 

Note que esta opción muestra una lista de todos los servicios que son accedidos por dispositivos Bizagi, y le permite agregar aplicaciones adicionales que representan los accesos otorgados al tener las llaves de acceso adecuadas. Haga clic sobre la opción para agregar un nuevo registro en la tabla.

 

OData_Workportal2

 

Cuando defina una nueva aplicación, asegúrese de considerar los siguientes detalles:

Nombre: Dé un nombre único y significativo

Tipo de Permiso: Los valores posibles son: Código de autorización, Credenciales de cliente, Todos o Bearer token.

Pagina Web: Especifique una URL asociada.

Scope permitido: Las posibles casillas para marcar son: API o Login.

oSe recomienda siempre habilitar API para poder otorgar los permisos necesarios para poder sacar el máximo provecho a los servicios OData.

oActive Login cuando elige Código de autorización como Tipo de permiso.

oActive User Sync cuando sincronice usuarios con SCIM.

oActive OData query cuando utilice el recurso Consultas de los servicios OData.

oActive RPA cuando utilice Callbacks de Automation Anywhere.

Nombre de usuario: (Aplica cuando se hace uso de Credenciales de cliente). Escriba el nombre de un usuario Bizagi existente y asegúrese que lo seleccione de la lista de usuarios sugeridos que coinciden (incluye información del dominio).

Estrategia de Redirección:  (Aplica cuando se hace uso de Código de autorización). Valores posibles: Aplicación Web, Navegador Móvil de Barras de Título, y Puerto Local Móvil.

oAplicación Web: Redirige al usuario a una URI web utilizando el código obtenido del servidor de autorización.

oNavegador Móvil de Barras de Título: Valor utilizado cuando la aplicación redirige al usuario a una aplicación de dispositivo móvil. Como los dispositivos móviles no tienen un punto final, la solicitud se redirige enviando el código de autorización en la etiqueta HTML del título. Así que el dispositivo móvil puede obtenerlo desde allí.

oPuerto Local Móvil: Bizagi envía el código a https://localhost:puerto/ donde un dispositivo móvil puede obtener el que fue enviado por el servidor de autorización.

Una estrategia de redirección define cuales clientes podrán hacer uso de la aplicación.

Para esta prueba inicial, y para uso general, se puede hacer uso de la configuración con Aplicación Web.

Sin embargo, el enfoque usualmente recomendado es efectivamente hacer uso de Aplicación Web para que el servidor (que puede procesar las peticiones por medio de endpoints) invoca el API de Bizagi, mientras se tiene en cambio, aplicaciones móviles o cualquier otro tipo de clientes invocar servicios del servidor.

URI de redirección: (Aplica cuando se hace uso de Código de autorización). Define la URL a la cual se debe redireccionar cuando haya callback una vez el usuario haya ingresado sus credenciales.

Deberá utilizar siempre una URL que haga uso del protocolo HTTPS.

Tiempo de vida del Token: Define el número de minutos en los cuales un token es válido y puede ser reutilizado para otra invocación (usualmente para mejorar la seguridad mientras se evitan ataques replay)

 

note_pin

Se recomienda hacer uso de estas dos combinaciones, que usualmente involucran dos aplicaciones diferentes:

 

Para Servicios de Datos:

Tipo de Permiso: Código de autorización, Scope permitido: Login y API.  

 

Para Servicios de Metadata:

Tipo de Permiso Credenciales de Cliente, Scope permitido: API.

 

OData_Workportal3

 

En estos ejemplos la aplicación registrada será autenticada en nombre del usuario agilityCorp\TomH.

 

Una vez haya terminado, haga clic sobre Guardar.

Notará que la aplicación recién registrada está en la lista con sus llaves de acceso.

Las llaves que deben ser usadas y copiadas en el portapapeles son: Client Id y Client Secret.

 

OData_Workportal4

 

2. Obtener el token de autorización

Una vez haya copiado las llaves Client Id y Client Secret, estableceremos la comunicación autenticada por medio de Postman.

Antes de hacerlo, tenga en cuenta que Bizagi espera las credenciales como una cadena de texto codificada en base64.

 

2.1 Para cifrar estas llaves como una sola cadena de texto, lleve a cabo lo siguiente:

Copie la llave Client Id primero y agréguele dos puntos (:) para añadir después el Client Secret.

El siguiente formato muestra la estructura, ignorando los caracteres []:

[ID Cliente]:[Secreto Cliente]

Codifique esta cadena con base64.

Para lograrlo, puede hacer uso de páginas web como https://www.base64encode.org/, o hacer uso de su propio programa.

 

Al final, tendrá la cadena de texto con las credenciales, vamos a referirnos a este como las Credenciales cifradas:

 

OData_Postman0

 

2.2 Abra el plug-in de Postman y utilice la credencial cifrada para autenticarse con el servicio OAuth.

 

OData_Postman0b

 

2.3 Antes que todo, asegúrese que ingrese la URL del servicio para su proyecto Bizagi.

Asegúrese de usar una acción HTTP POST con la URL de la manera: [url_del_proyecto_bizagi]/oauth2/server/token

 

Siendo:

[url_del_proyecto_bizagi]: Corresponde a la URL donde los usuarios finales acceden al Portal de trabajo de Bizagi.

Por ejemplo, para proyectos de Bizagi en sus instalaciones, esta URL sería:

https://[su_servidor]/[su_proyecto]/oauth2/server/token

Mientras que para proyectos de Automation Service, esta URL sería:

https://[ambiente_del_proyecto]-[su_proyecto]-[su_compañía].bizagi.com/oauth2/server/token

 

Especifique que No Auth es empleado.

 

OData_Postman2

 

2.4 Pase a la pestaña Headers y especifique:

Content-Type: application/x-www-form-urlencoded

Authorization: Ingrese la palabra Basic, seguida por un espacio y agregue las Credenciales cifradas que obtuvo en el paso anterior.

 

Este es el formato empleado, ignorando los caracteres []:

Basic [Credenciales cifradas]

 

OData_Postman2b

 

2.5 Finalmente, en la pestaña Body seleccione la configuración raw y agregue esta linea en la caja de texto:

grant_type=client_credentials&scope=api

 

OData_Postman3

 

 

note_pin

Note que los valores posibles de grant_type son: client_credentials o authorization_code.

De manera similar, los valores posibles para scope son: login, api y all.

Sin embargo, authorization_code debe usarse desde un cliente donde se implemente debidamente su uso (con el envío de credenciales).

 

Ya puede hacer clic sobre Send, que dispara la petición para autenticar.

Una respuesta exitosa devuelve un token_acceso con información relevante a este:
 

OData_Postman5