Integración con la RA API

Descripción general

En esta guía, aprenderás a integrarte con la RA API para gestionar el ciclo de vida completo de los certificados: autenticar usuarios, generar CSR en el servidor Redtrust, y emitir y renovar certificados digitales.

Esta guía está dirigida a desarrolladores de partners de Redtrust con capacidad para emitir certificados. Para seguirla, necesitas conocimientos básicos de las API HTTP, la autenticación mediante tokens bearer y los certificados digitales.

Antes de empezar

Para integrar el servicio, necesitas la siguiente información proporcionada por el cliente de Redtrust:

• Dirección IP o nombre del host del servidor Redtrust.
• El puerto utilizado para acceder al servicio (el valor por defecto es 8082).
• Nombre del usuario de aplicación para el servicio.
• (Opcional) Nombre de dominio.

Si usas el flujo de redirección HMAC, también necesitas:

• Una URL de redirección a la que Redtrust envía el token temporal tras la autenticación. Un administrador debe registrar esta dirección en Redtrust antes de empezar.

Paso 1: Obtén un token de acceso

La RA API admite dos métodos de autenticación. Elige el que se adapte a tu integración.

Inicio de sesión directo

Usa esta opción para integraciones servidor a servidor y pruebas con Postman.

Envía una solicitud POST a /raapi/v1/auth/login con las credenciales del usuario:

POST /raapi/v1/auth/login

{
  "username": "string",
  "password": "string",
  "domain": "string"
}

La respuesta incluye el accessToken y el refreshToken:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "expiration": "string"
  }
}

Usa el accessToken en todas las solicitudes siguientes. Continúa con el paso 2.

Redirección HMAC

Usa esta opción cuando los usuarios se autentiquen mediante la interfaz web de Redtrust.

El flujo de redirección usa el mismo mecanismo HMAC que la Sign API, con una diferencia: el parámetro Consumer debe ser RA_API.

Redirige el navegador del usuario a:

https://TU_IP_REDTRUST:PUERTO/authclient/auth/loginrequest?Consumer=RA_API&Domain=TU_DOMINIO&RedirectUrl=URL_REDIRECCIÓN&timestamp=TIMESTAMP&partner=NOMBRE_PARTNER&hmac=FIRMA_HMAC

Donde:

• TU_IP_REDTRUST es la dirección IP o el nombre de host de tu servidor Redtrust.
• PUERTO es el puerto de acceso al servicio (por defecto 8082).
• TU_DOMINIO es el dominio de los usuarios (opcional).
• URL_REDIRECCIÓN es la URL a la que se redirige tras la autenticación. Aplica UrlEncode.
• TIMESTAMP es la marca de tiempo en formato UNIX.
• NOMBRE_PARTNER es el nombre en mayúsculas de la aplicación cliente.
• FIRMA_HMAC es la firma HMAC-SHA256 generada con la clave compartida.

Si la autenticación se completa correctamente, Redtrust redirige el navegador del usuario a tu URL de redirección:

https://TU_URL_REDIRECCIÓN/TOKEN_TEMPORAL

Intercambia el token temporal

Intercepta el parámetro tkn de la URL redirigida. Tu aplicación debe hacer una llamada al servidor para intercambiarlo por un token de acceso permanente:

POST /authapi/v1/login_by_temp_token

{
  "temporalToken": "TOKEN_TEMPORAL"
}

Donde TOKEN_TEMPORAL es el valor del parámetro tkn de la URL redirigida.

La respuesta incluye el accessToken y el refreshToken:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "expiration": "string"
  }
}

Usa el accessToken para autenticar todas las llamadas a la RA API. Continúa con el paso 2.

Paso 2: Emisión del certificado

Para emitir un certificado, llama a dos endpoints en secuencia.

1. Crea el CSR

POST https://TU_IP_REDTRUST:PUERTO/raapi/v1/csr/create

Donde TU_IP_REDTRUST y PUERTO son la dirección y el puerto de tu servidor Redtrust.

Consulta la descripción completa del endpoint, con los campos del body y ejemplos, en la referencia de la RA API.

El servidor devuelve un CSR y un requestCode. Guarda el requestCode: lo necesitas en el siguiente paso.

2. Finaliza la emisión

PUT https://TU_IP_REDTRUST:PUERTO/raapi/v1/csr/finalize

Consulta la descripción completa del endpoint en la referencia de la RA API.

Paso 3: Renovación del certificado

El flujo de renovación usa los mismos endpoints que la emisión. La única diferencia es que debes incluir el campo thumbprintToRenew en el body de la llamada a POST /raapi/v1/csr/create:

{
  "...": "...",
  "thumbprintToRenew": "THUMBPRINT_DEL_CERTIFICADO_A_RENOVAR"
}

Donde THUMBPRINT_DEL_CERTIFICADO_A_RENOVAR es el thumbprint del certificado existente que quieres renovar.

Tras la creación del CSR, llama al mismo endpoint de finalización (PUT /raapi/v1/csr/finalize) con el requestCode obtenido. El nuevo certificado reemplaza al anterior, conservando su configuración y asociaciones.

Consulta la descripción completa de ambos endpoints en la referencia de la RA API.