Gestión de certificados de Camerfirma

Descripción general

En este tutorial aprenderás a integrarte con la RA API de Redtrust para emitir y renovar certificados de Camerfirma: autenticar tu aplicación, generar el par de claves y el CSR en el servidor, y completar la emisión.

Este tutorial va dirigido a desarrolladores de partners de Redtrust con capacidad para emitir certificados de Camerfirma. Para seguirlo, necesitas conocimientos básicos de las API HTTP y la autenticación mediante tokens bearer.

Al final de este tutorial habrás emitido un certificado de Camerfirma almacenado en el servidor Redtrust.

Antes de empezar

Necesitas la siguiente información proporcionada por el cliente de Redtrust:

• Dirección IP o nombre del host del servidor Redtrust.
• El puerto de acceso al servicio (el valor por defecto es 8082).
• Las credenciales 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 registrarla 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 tu nombre de usuario, contraseña y, si aplica, el nombre de dominio. La respuesta contiene un accessToken y un refreshToken.

Incluye el accessToken como Bearer token en todas las solicitudes siguientes y continúa con el paso 2.

Redirección HMAC

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

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.

Cuando la autenticación se completa, Redtrust redirige al usuario a tu URL con un token temporal en el parámetro tkn. Intercámbialo por un token de acceso enviando una solicitud POST a /authapi/v1/login_by_temp_token con el valor de tkn en el campo temporalToken. La respuesta contiene el accessToken.

Incluye el accessToken como Bearer token en todas las solicitudes siguientes y continúa con el paso 2.

Paso 2: Emite el certificado

La emisión se realiza en dos llamadas consecutivas.

1. Crea el CSR

Llama a POST /raapi/v1/csr/create con los datos del titular. Incluye "provider": "CAMERFIRMA":

{
  "dn": [
    { "attribute": "cn", "value": "NOMBRE_TITULAR" }
  ],
  "hashType": "SHA384",
  "keyLength": 2048,
  "keyType": "RSA",
  "provider": "CAMERFIRMA"
}

Donde NOMBRE_TITULAR es el nombre completo del titular del certificado.

Redtrust genera el par de claves en el servidor y devuelve el CSR junto con un requestCode. Guarda el requestCode: lo necesitas en el paso siguiente.

Para la lista completa de campos del body, consulta la referencia de la RA API.

2. Finaliza la emisión

Llama a PUT /raapi/v1/csr/finalize con el requestCode obtenido en el paso anterior. La respuesta contiene el idCertificate y el thumbprint del certificado emitido, que queda almacenado en Redtrust.

Paso 3: Renueva un certificado

El flujo de renovación es idéntico al de emisión. La única diferencia es que debes incluir el thumbprint del certificado existente en el campo thumbprintToRenew de la llamada a POST /raapi/v1/csr/create. El nuevo certificado reemplaza al anterior y conserva su configuración y asociaciones.

Resumen

Has completado el flujo de integración con Camerfirma a través de la RA API: autenticaste tu aplicación, generaste el par de claves y el CSR en el servidor Redtrust, y finalizaste la emisión. El certificado queda almacenado en Redtrust y disponible para su uso.

Próximos pasos

• Referencia de endpoints de la RA API — documentación completa de todos los endpoints, campos y ejemplos
• Integración con Camerfirma