Introducción
Los servicios OData incluyen una capa adicional de seguridad para validar las solicitudes de los clientes.
Cuando usted configura una aplicación OAuth 2 en Bizagi utilizando la opción Certificado de cliente, debe demostrar su identidad al invocar los servicios OData. Para ello, usted debe construir y enviar un JSON Web Token (JWT) firmado con su llave privada como parte de cada solicitud OData.
Usted envía este token en un encabezado HTTP llamado X‑ClientCertificate‑Token. Cuando Bizagi recibe la solicitud, lee el token y valida su firma utilizando la llave pública que usted cargó previamente al registrar la aplicación. Si tanto la firma del token como sus claims son válidos, Bizagi responde correctamente al servicio OData solicitado.
Este artículo explica:
•Cómo generar las llaves privada y pública requeridas
•Cómo registrar la llave pública en Bizagi
•Cómo usted debe construir, firmar y enviar el JWT necesario para invocar servicios OData
Qué necesita configurar
La autenticación mediante Certificado de cliente se basa en un par de llaves que usted genera y administra:
•Llave privada: Usted utiliza esta llave para firmar el JWT. Esta llave nunca se carga en Bizagi y debe mantenerse segura.
•Llave pública (.cer): Usted carga esta llave al registrar la aplicación OAuth 2. Bizagi la utiliza para validar la firma del token.
Ambas llaves se generan juntas y siempre deben corresponder entre sí.
Generación de las llaves del certificado
Para generar las llaves privada y pública requeridas para la autenticación mediante Certificado de cliente, usted necesita una herramienta capaz de crear pares de llaves RSA estándar y certificados X.509.
En este artículo se utiliza OpenSSL como ejemplo porque es ampliamente disponible y comúnmente utilizado en diferentes plataformas. Sin embargo, OpenSSL no es un requisito estricto. Usted puede utilizar cualquier herramienta o servicio que permita generar llaves privadas y certificados públicos compatibles.
Los únicos requisitos son que:
•El certificado público pueda exportarse en formato .cer
•El certificado público corresponda a la misma llave privada que usted utiliza para firmar el JWT
Mientras se cumplan estas condiciones, Bizagi podrá validar correctamente la firma del token.
Ejemplo usando OpenSSL
Los siguientes pasos muestran cómo generar las llaves requeridas utilizando OpenSSL.
Prerrequisitos
•OpenSSL instalado
•Acceso a una terminal de línea de comandos
•Una ubicación segura para almacenar archivos sensibles
Paso 1: Generar la llave privada
openssl genrsa -out private_key.key 2048
Este comando crea la llave privada.
Usted utiliza esta llave para firmar los tokens JWT. No comparta ni cargue este archivo.
Paso 2: Crear una solicitud de firma de certificado (CSR)
openssl req -new -key private_key.key -out request.csr
Durante este paso, se le solicita ingresar los detalles del certificado.
Preste especial atención al campo Common Name (CN). Posteriormente deberá utilizar exactamente este valor como el claim issuer (iss) al construir el JWT.
Paso 3: Generar la llave pública (.cer)
openssl x509 -req -days 365 -in request.csr -signkey private_key.key -out public_key.cer
Este comando crea el certificado público, que es el archivo que Bizagi requiere.
Paso opcional: Generar un archivo PKCS#12 (.p12)
Algunas herramientas requieren un único archivo que contenga tanto la llave privada como el certificado.
openssl pkcs12 -export \-out private_key.p12 \-inkey private_key.key \-in public_key.cer
Se le solicitará definir una contraseña para proteger el archivo.
Resumen de archivos generados
Archivo |
Propósito |
|---|---|
private_key.key |
Utilizado por usted para firmar tokens JWT |
public_key.cer |
Se carga en Bizagi |
private_key.p12 |
Paquete opcional utilizado por herramientas de firma |
Cargar la llave pública en Bizagi
Una vez que haya generado las llaves:
1.Abra el Portal de Trabajo
2.Vaya a Admin > Seguridad > Aplicaciones OAuth 2
3.Agregue o edite una aplicación
4.Seleccione Certificado de cliente como tipo de concesión
5.Cargue el archivo public_key.cer
6.Guarde la aplicación
Bizagi ahora está preparado para validar los tokens JWT que usted firme utilizando la llave privada correspondiente.
Construcción del token de Certificado de cliente (JWT)
Al utilizar la opción Certificado de cliente, Bizagi no genera el token por usted.
Usted es responsable de construir, firmar y enviar el JWT exactamente como se describe a continuación, antes de invocar cualquier servicio OData.
Estructura del JWT
Un JSON Web Token consta de tres partes, separadas por puntos (.):
header.payload.signature
Para referencia, consulte la RFC 7519: https://datatracker.ietf.org/doc/html/rfc7519
1. Encabezado (Header)
El encabezado define el tipo de token y el algoritmo de firma. Por ejemplo:
JSON
{
"alg": "HS256",
"typ": "JWT"
}
|
Al construir el JWT, usted debe utilizar uno de los siguientes algoritmos de firma: •RS256 •RS384 •RS512 •HS256 •HS384 •HS512
Si utiliza cualquier otro algoritmo, Bizagi rechaza el token durante la validación. Después de crear el encabezado, debe codificarlo utilizando Base64URL. |
2. Payload (Claims)
El payload contiene la información que Bizagi utiliza para validar y autorizar su solicitud. El payload del JWT debe contener únicamente los siguientes claims:
•iat: Fecha de creación del token, en formato Unix timestamp.
•exp: Fecha de expiración del token, en formato Unix timestamp.
•clientid: El Client ID de la aplicación OAuth 2 registrada en Bizagi.
•iss: Emisor de la llave pública. Este valor debe coincidir con el Common Name (CN) del archivo .cer.
•aud: Debe establecerse en odataquery.
Ejemplo de payload:
JSON
{
"iat": 1716239022,
"exp": 1716242622,
"clientid": "your_client_id",
"iss": "CN=your-certificate-common-name",
"aud": "odataquery"
}
|
No se permiten claims adicionales. Si incluye claims extra, Bizagi rechaza el token. |
|
Al definir la vigencia del token, usted debe cumplir las siguientes reglas. Si alguna se incumple, Bizagi rechaza el token: •El tiempo de vida máximo permitido es de 24 horas. •Si la diferencia entre el tiempo de creación (iat) y el tiempo de expiración (exp) excede 24 horas, el token se rechaza. •No se aceptan tokens cuya vigencia aún no haya iniciado. •El tiempo de creación (iat) no debe ser posterior a la fecha y hora actuales. •No se aceptan tokens vencidos.
Estas validaciones se aplican a cada solicitud. |
3. Firma
Usted debe generar la firma firmando el encabezado y el payload codificados en Base64URL utilizando su llave privada.
Conceptualmente:
HMACSHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
private_key
)
El resultado constituye la tercera parte del JWT.
Generación del token usando PowerShell
El siguiente ejemplo muestra cómo usted puede construir y firmar el JWT utilizando PowerShell.
Instalar el módulo JWT
Primero, verifique que el módulo esté instalado ejecutando el siguiente comando:
Get-InstalledModule -Name JWT | Select-Object Name, Version, InstalledLocation
Si no está instalado:
Install-Module -Name JWT
Cargar la llave privada
$Cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2( "C:\path\to\privatekey\private_key.pfx", "private key password")
Definir la vigencia del token
$Now = [System.DateTimeOffset]::UtcNow
$Exp = $Now.AddHours(1)
|
Usted puede ajustar el tiempo de expiración del token utilizando cualquiera de las siguientes funciones, siempre y cuando la vigencia resultante cumpla las reglas de validación de Bizagi: •AddSeconds(): agrega un número de segundos •AddMinutes(): agrega un número de minutos •AddHours(): agrega un número de horas •AddDays(): agrega un número de días •AddYears(): agrega un número de años
Por ejemplo: $Exp = $Now.AddMinutes(30) |
Crear el payload
$Payload = @{
"iat" = $Now.ToUnixTimeSeconds()
"exp" = $Exp.ToUnixTimeSeconds()
"clientid" = "your_client_id"
"iss" = "CN=your-certificate-common-name"
"aud" = "odataquery"
}
Generar el token firmado
$Jwt = New-Jwt -Cert $Cert -PayloadJson ($Payload | ConvertTo-Json)
Mostrar el token
$Jwt
Copie el valor resultante. Este es el JWT que usted debe enviar a Bizagi.
Envío del token a Bizagi
Usted debe incluir el JWT firmado en cada solicitud OData utilizando el siguiente encabezado HTTP:
X-ClientCertificate-Token
Ejemplo de solicitud OData
GET /Automation/odata/data/cases HTTP/1.1
Host: your-environment
X-ClientCertificate-Token: <signed_token>
|
Si existen múltiples encabezados de autenticación, Bizagi los evalúa en el siguiente orden: 1.Authorization 2.X-ClientCertificate-Token
Si el encabezado Authorization es válido, Bizagi lo utiliza. De lo contrario, utiliza el token de Certificado de cliente. |
Bizagi valida el token utilizando la llave pública que usted cargó y los claims requeridos.
Si la validación es exitosa, Bizagi responde correctamente al servicio OData.
Qué ocurre si la validación falla
Si Bizagi no puede validar el token, responde con:
HTTP 401 Unauthorized
Con el mensaje genérico: Client authentication failed, e.g. unknown client, no client authentication included, or unsupported authentication method
Por razones de seguridad, Bizagi no retorna detalles de validación en la respuesta HTTP. Sin embargo, los errores específicos se escriben en los Logs de Eventos de la Management Console (MC).
Mensajes de error registrados en los Logs de Eventos de la MC
Dependiendo del error detectado, Bizagi registra uno de los siguientes mensajes:
•clientid incorrecto
Certificate token validation failed: Unable to get OAuth2 Application by client id.
•aud incorrecto
Certificate token validation failed: Audience validation failed.
•iss incorrecto
Certificate token validation failed: Issuer validation failed.
•Token firmado con una llave privada incorrecta
Certificate token validation failed: Signature validation failed.
•Token no vigente
Certificate token validation failed: Lifetime validation failed. Token validity not started yet.
•Token vencido
Certificate token validation failed: Lifetime validation failed. Token already expired.
•Expiración del token mayor a 24 horas
Certificate token validation failed: Lifetime validation failed. Token expiration time exceeds the valid time range of 24 hours.
•Token con claims adicionales
Certificate token validation failed: Token contains extra claims: xxxx, xxxx
Estos mensajes le permiten validar si la estructura del token, los claims o el proceso de firma cumplen con los requerimientos de Bizagi.
Last Updated 5/8/2026 11:43:25 AM