Integración del certificado en el sitio web del emisor

Introducción

El objetivo de esta página es describir cómo puede mostrar los certificados de BCdiploma en un dominio distinto de bcdiploma.com, por ejemplo el suyo.

De forma predeterminada, los certificados de BCdiploma son accesibles y se muestran en las siguientes URL, según el entorno:

• Staging: https://certificate-staging.bcdiploma.com
• Producción (datos ubicados en la zona UE): https://certificate.bcdiploma.com
• Producción (datos ubicados en la zona EE. UU.): https://certificate-cus.bcdiploma.com

Aquí se documentan 4 métodos diferentes para que los certificados puedan consultarse en el dominio del emisor, por ejemplo: https://certificate.your-domain.com o https://digitalcredential.your-domain.com

1. Solución recomendada 1: la configuración de su proxy inverso (necesaria si desea una ruta del tipo your-domain.com/certificates)
2. Solución recomendada 2: el proxy inverso operado por BCdiploma (su dominio personalizado mediante unos pocos registros DNS, sin ninguna infraestructura por su parte)
3. Solución recomendada 3: la delegación de su subdominio a BCdiploma (una sola operación DNS, una sola vez; después nos encargamos de todo, renovaciones incluidas)
4. Solución no recomendada: la implementación de un sistema de iframe

Método 1 recomendado: con su proxy inverso

Funcionamiento

Este artículo describe cómo configurar un proxy inverso (reverse proxy) para que los certificados de BCdiploma se muestren en su dominio en lugar de en el dominio bcdiploma.com. En concreto, se trata de establecer, a nivel de red, un intermediario (proxy) transparente entre su dominio (p. ej., certificates.your-domain.com) y el dominio bcdiploma.com.

Cabe señalar que existe una multitud de soluciones de proxy inverso en el mercado (nginx, apache, etc.) y otros tantos tipos de implementación en los sistemas de información. Por ello, la documentación siguiente describe únicamente los principios que deben aplicarse en su infraestructura, con la ayuda de su equipo de TI, que conoce sus particularidades.

Ventajas:

• Permite utilizar una ruta en un dominio existente (p. ej., your-domain.com/certificates)
• Compatibilidad máxima con las redes sociales
• Poco mantenimiento una vez implementado
• Compatibilidad máxima con todos los navegadores
• Transparencia para el usuario final

Inconvenientes:

• Requiere una intervención inicial de su equipo de TI/infraestructura

Requisito previo: parámetros relativos al tamaño de los encabezados

Para admitir los encabezados CSP, debe modificar algunos parámetros de su proxy inverso:

proxy_busy_buffers_size   32k;
proxy_buffers   4 16k;
proxy_buffer_size   16k;

Paso 1: configure una redirección para el entorno de pruebas (staging)

Debe redirigir las solicitudes que lleguen a un dominio específico de su red, que se utilizará para las pruebas (p. ej., certificate-staging.your-domain.com), hacia el dominio de pruebas de BCdiploma, es decir, certificate-staging.bcdiploma.com. Esta redirección debe ir acompañada de un encabezado custom-host cuyo valor sea su nombre de dominio your-domain.com.

Ejemplos de archivo de configuración para diferentes servidores de proxy inverso:

• nginx

# BEGIN SERVER certificate-staging.your-domain.com:443
server {
    listen WWW.XXX.YYY.ZZZ:443 ssl;

    include snippets/ssl-certificates.conf;
    include snippets/ssl-params.conf;

    server_name certificate-staging.your-domain.com;

    location / {
	    # se añade un parámetro custom-host en el encabezado
		  # que corresponde al dominio para el que se podrán visualizar los certificados
      proxy_set_header custom-host your-domain.com;
      proxy_pass https://certificate-staging.bcdiploma.com;
    }

    access_log /var/log/nginx/certificate-staging.your-domain.com-access.log upstream_time;
    error_log /var/log/nginx/certificate-staging.your-domain.com-error.log;
}
# END SERVER certificate-staging.your-domain.com:443

• Apache

<VirtualHost *:443>
    ServerName certificate-staging.your-domain.com:443
    SSLEngine on
    SSLProxyEngine On

    # SSL certificate config

    SSLCertificateFile /etc/apache2/ssl/**************************
    SSLCertificateKeyFile /etc/apache2/ssl/***********************
    SSLCertificateChainFile /etc/apache2/ssl/*********************

    ErrorLog /var/log/apache2/ssl_443_certificate_error_log
    TransferLog /var/log/apache2/ssl_443_certificate_access_log
    LogLevel debug
    CustomLog /var/log/apache2/ssl_request_log "%t %h %{SSL_PROTOCOL}x \"%r\" %b"

    SetEnv nokeepalive ssl-unclean-shutdown
    SetEnv proxy-nokeepalive 1
    ProxyRequests     Off

    RequestHeader set custom-host "your-domain.com"
    ProxyPass / https://certificate-staging.bcdiploma.com:443/ connectiontimeout=300 timeout=300
    ProxyPassReverse  / https://certificate-staging.bcdiploma.com:443/
</VirtualHost>

Indique a nuestro equipo el dominio de acceso de pruebas así configurado: actualizaremos la blockchain para que los certificados del entorno de pruebas sean accesibles en esa dirección lo antes posible.

Paso 2: configure las redirecciones para el entorno de producción

Repita la operación anterior para redirigir las solicitudes de su dominio de producción (p. ej., certificate.your-domain.com) hacia el dominio de producción de BCdiploma, por ejemplo:

• nginx

# BEGIN SERVER certificate.your-domain.com:443
server {
    listen WWW.XXX.YYY.ZZZ:443 ssl;

    include snippets/ssl-certificates.conf;
    include snippets/ssl-params.conf;

    server_name certificate.your-domain.com;

    location / {
	    # se añade un parámetro custom-host en el encabezado
		  # que corresponde al dominio para el que se podrán visualizar los certificados
      proxy_set_header custom-host your-domain.com;
      proxy_pass https://certificate.bcdiploma.com;
    }

    access_log /var/log/nginx/certificate.your-domain.com-access.log upstream_time;
    error_log /var/log/nginx/certificate.your-domain.com-error.log;
}
# END SERVER certificate.your-domain.com:443

• apache

<VirtualHost *:443>
    ServerName certificate.your-domain.com:443
    SSLEngine on
    SSLProxyEngine On

    # SSL certificate config

    SSLCertificateFile /etc/apache2/ssl/**************************
    SSLCertificateKeyFile /etc/apache2/ssl/***********************
    SSLCertificateChainFile /etc/apache2/ssl/*********************

    ErrorLog /var/log/apache2/ssl_443_certificate_error_log
    TransferLog /var/log/apache2/ssl_443_certificate_access_log
    LogLevel debug
    CustomLog /var/log/apache2/ssl_request_log "%t %h %{SSL_PROTOCOL}x \"%r\" %b"

    SetEnv nokeepalive ssl-unclean-shutdown
    SetEnv proxy-nokeepalive 1
    ProxyRequests     Off

    RequestHeader set custom-host "your-domain.com"
    ProxyPass / https://certificate.bcdiploma.com:443/ connectiontimeout=300 timeout=300
    ProxyPassReverse  / https://certificate.bcdiploma.com:443/
</VirtualHost>

Paso 3: avise a nuestro equipo

Indique a nuestro equipo la dirección de su dominio de certificados; actualizaremos la blockchain para que los certificados sean accesibles desde su URL lo antes posible.

Método 2 recomendado: con un proxy inverso operado por BCdiploma

Funcionamiento

BCdiploma puede mostrar directamente sus certificados en un subdominio de su institución (p. ej., certificate.your-domain.com), sin que usted tenga que desplegar ninguna infraestructura. La terminación HTTPS, la emisión del certificado SSL a su nombre y su renovación corren íntegramente a cargo de la plataforma BCdiploma. Su equipo de TI solo tiene que crear tres registros DNS, en dos etapas.

El principio es un alias DNS: su subdominio apunta, mediante un registro CNAME, a un punto de entrada dedicado aprovisionado por BCdiploma (un proxy inverso operado por BCdiploma), que presenta un certificado SSL emitido a nombre de su subdominio. Dos registros TXT permiten demostrar previamente que usted controla efectivamente ese nombre de dominio.

La puesta en marcha se realiza entorno por entorno: primero el de pruebas (p. ej., certificate-staging.your-domain.com) y después el de producción (p. ej., certificate.your-domain.com). El proceso que se describe a continuación es idéntico en ambos casos; solo difieren los valores proporcionados por nuestro equipo.

Ventajas:

• Ninguna infraestructura que desplegar ni mantener por su parte (ningún servidor ni proxy inverso que deba operar usted mismo)
• Certificado SSL emitido y renovado automáticamente por nuestro equipo
• Compatibilidad máxima con las redes sociales y con todos los navegadores
• Transparencia para el usuario final

Inconvenientes:

• Requiere un subdominio dedicado (p. ej., certificate.your-domain.com). Las direcciones del tipo your-domain.com/certificates (ruta en un dominio existente) no son posibles con este método.
• Su equipo de TI debe crear tres registros DNS, en dos etapas separadas por unos pocos días como máximo.
• Debe preverse un costo adicional anual sobre la licencia. Cubre el aprovisionamiento de un punto de entrada dedicado a su dominio en nuestra infraestructura de distribución, la emisión y la renovación automática del certificado SSL a su nombre, así como la supervisión de este servicio a lo largo del tiempo. Póngase en contacto con nuestro equipo para conocer las condiciones tarifarias.

Requisitos previos

• 2 subdominios dedicados a la visualización de los certificados (p. ej., certificate.your-domain.com o digitalcredential.your-domain.com), uno para el entorno de pruebas y otro para el de producción. No se puede utilizar un dominio raíz (your-domain.com sin prefijo).
• Capacidad de reacción: uno de los registros proporcionados expira al cabo de 7 días (véase el paso 2).

Paso 1: solicite la activación a nuestro equipo

Comunique a nuestro equipo el subdominio deseado para el entorno en cuestión (p. ej., certificate-staging.your-domain.com para el entorno de pruebas).

En respuesta, le enviaremos el valor del registro _dnsauth que debe crear (el valor del segundo registro, asuid, es fijo y figura más abajo).

Paso 2: cree los dos registros TXT de validación

Cree los dos registros siguientes en su zona DNS:

Ejemplo para digitalcredential-staging.your-domain.com:

Una vez creados los registros, avise a nuestro equipo.

Paso 3: espere nuestra confirmación

Una vez recibidos sus registros, nuestro equipo procede a la validación del dominio, a la emisión del certificado SSL a su nombre y a la configuración de la plataforma. Le confirmamos el final de estas operaciones comunicándole el destino del CNAME que debe crear. Este plazo suele ser inferior a 48 horas.

Paso 4: cree el registro CNAME

Cree el registro final con el destino correspondiente a su entorno, tal como lo haya confirmado nuestro equipo en el paso 3. Cree este CNAME únicamente para el entorno que se esté configurando (cada entorno sigue su propio ciclo de pasos 1 a 5):

Tras la propagación DNS (de unos minutos a unas horas, según su TTL), sus certificados pueden consultarse en su subdominio, en HTTPS, con un certificado SSL a su nombre.

Paso 5: verifique y conserve la configuración

Verifique que un certificado de prueba se muestra en su subdominio y, a continuación, repita el proceso para el entorno de producción.

Método 3 recomendado: delegando su subdominio a BCdiploma

Funcionamiento

Este método produce el mismo resultado que el método 2 —sus certificados servidos en su subdominio, con un certificado SSL a su nombre gestionado íntegramente por nosotros—, pero con una integración DNS diferente: en lugar de crear usted mismo los registros de validación y después el CNAME, usted delega la gestión DNS del subdominio en BCdiploma mediante registros NS. El subdominio se convierte entonces en una zona DNS operada por nuestro equipo: en ella creamos y mantenemos todos los registros necesarios, tanto hoy como en las futuras renovaciones del certificado.

Cuándo preferir este método al método 2:

• su sistema DNS no permite crear los registros que requiere el método 2 (por ejemplo, registros hijos bajo un nombre que ya tiene un CNAME);
• sus modificaciones DNS pasan por un proceso de cambio largo o restrictivo, al que solo desea recurrir una vez;
• desea no tener que realizar nunca más ninguna acción DNS para este servicio.

Ventajas:

• Una sola operación DNS, una sola vez: ninguna intervención posterior de sus equipos, ni siquiera para las renovaciones del certificado
• Ninguno de los valores proporcionados expira: realice la operación en el momento que mejor se adapte a su proceso interno
• Interrupción mínima del servicio si ya existe un servicio en ese subdominio: nuestra zona está preconfigurada para responder exactamente igual que su DNS actual, y la conmutación efectiva solo se produce más tarde, bajo nuestro control, una vez emitido el certificado
• Ninguna infraestructura por su parte, compatibilidad máxima con las redes sociales y con todos los navegadores, transparencia para el usuario final

Inconvenientes:

• El subdominio delegado está gestionado íntegramente por BCdiploma: usted ya no puede crear registros en él. Delegue únicamente un subdominio estrictamente dedicado a la visualización de los certificados.
• Requiere un subdominio dedicado (las direcciones del tipo your-domain.com/certificates no son posibles con este método).
• Debe preverse un costo adicional anual sobre la licencia, en las mismas condiciones que el método 2; póngase en contacto con nuestro equipo.

Requisitos previos

• 2 subdominios dedicados (uno para el entorno de pruebas y otro para el de producción).
• Su proveedor de DNS debe permitir la creación de registros NS para un subdominio (delegación); es el caso de casi todos los registradores y servicios DNS.

Paso 1: solicite la activación a nuestro equipo

Comunique a nuestro equipo:

• el subdominio deseado para el entorno en cuestión (p. ej., digitalcredential-staging.your-domain.com para el entorno de pruebas);
• si ya hay un servicio que responde en ese nombre (caso de una migración): indíquenoslo y preconfiguraremos nuestra zona para garantizar la continuidad, sin ninguna interrupción para sus usuarios.

En respuesta, le enviaremos los 4 registros NS que debe crear.

Paso 2: cree la delegación

En su zona DNS, cree los 4 registros NS proporcionados:

Avise a nuestro equipo una vez realizadas las operaciones.

Paso 3: nosotros nos encargamos del resto

Una vez recibida su confirmación, nuestro equipo realiza todas las operaciones (validación, emisión del certificado SSL a su nombre, puesta en servicio, conmutación del tráfico) y le confirma la puesta en servicio. En el caso de una migración, mantenga activo su antiguo servicio hasta que le confirmemos expresamente que puede retirarse.

Método 4 no recomendado: implementación de un sistema de iframe

Ventajas:

• Requiere una intervención inicial sencilla de los equipos de TI

Inconvenientes:

• En caso de cambio de infraestructura en su sitio web, será imprescindible conservar la misma ruta de acceso a los certificados ya emitidos, lo cual es una operación compleja, sobre todo cuando se cambia de tipo de servidor web o de CMS.
• Compatibilidad limitada con las miniaturas en las redes sociales. Solo se mostrará como miniatura en las redes sociales una imagen fija que usted indicará en el código del iframe. En particular, los logotipos utilizados en sus plantillas de microcertificaciones no se mostrarán como miniaturas en este contexto.
• El código del iframe puede requerir actualizaciones ocasionalmente

Funcionamiento

Los certificados de BCdiploma se mostrarán en un iframe alojado en el sitio de terceros. En concreto, el sitio de terceros alojará:

• una página html estática (proporcionada por nuestro equipo) que permite mostrar en un iframe los certificados procedentes de certificate.bcdiploma.com o certificate-cus.bcdiploma.com;
• una miniatura que se utilizará en las vistas previas de los sitios web (p. ej., redes sociales) donde se comparta el enlace.

Aquí encontrará un ejemplo de integración de un iframe en el sitio myBCdiploma.

El identificador del certificado se pasará como parámetro a esta página para mostrar un certificado específico (p. ej., https://your-domain.com/certificates/index.html?key=684B6E2716D35894A1DEF33DE4F30B415D3C8953F8F2CDF7808582B4F0D0F6D7aVBzTmpBREQ0bXZCVUpybDlqYklvRmZxTnJEVVgza3BGVVFoczk5NE1ZSTNWOAAA)

Paso 1: preparación de su servidor web

En su servidor web, cree un directorio dedicado (p. ej., certificates), https://your-domain.com/certificates, o elija un directorio existente (en este último caso, procure no sobrescribir su contenido en los pasos siguientes)

Paso 2: preparación del archivo de miniatura

Prepare un archivo de imagen que contenga su logotipo y colóquelo en la carpeta creada en el paso 1. Esta es la imagen que se mostrará como vista previa en los sitios en los que se compartan los enlaces de sus certificados. Tenga en cuenta que podemos proporcionarle una miniatura optimizada para LinkedIn. Formato óptimo: 1200*627px Ejemplo: https://www.bcdiploma.com/img/thumbnail-opengraph.png

Paso 3: preparación del archivo HTML

Prepare un archivo index.html con el siguiente contenido y personalícelo:

• Entre las etiquetas indicadas en <head>
• En la variable host al final del archivo

Colóquelo en el directorio creado en el paso 1.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <meta name="robots" content="noindex" />

    <!-- Inicio de la información personalizable -->

    <!-- Personalice los títulos y las descripciones que se mostrarán en las pestañas de los navegadores y al compartir en las redes sociales -->
    <title>BCdiploma blockchain certificate</title>
    <meta property="og:title" content="BCdiploma blockchain certificate" />
    <meta
      name="description"
      content="This certificate was issued through the BCdiploma services and certified on the blockchain."
    />
    <meta
      property="og:description"
      content="This certificate was issued through the BCdiploma services and certified on the blockchain."
    />

    <!-- Personalice la imagen de vista previa que se mostrará en las redes sociales  -->
    <!-- Utilice una ruta completa. Formato óptimo: 1200*627px -->
    <meta
      property="og:image"
      content="https://www.bcdiploma.com/img/thumbnail-opengraph.png"
    />

    <!-- Personalice el icono que se mostrará en la pestaña de los navegadores -->
    <!-- Utilice una ruta completa. Formato óptimo: 32*32px -->
    <link href="https://www.bcdiploma.com/bcdiploma-favicon.png" rel="icon" />

    <!-- Indique su nombre de emisor en "content" -->
    <meta property="article:author" content="BCdiploma" />

    <!-- Fin de la información personalizable -->

    <meta property="og:type" content="article" />
  </head>
  <body>
    <!-- Certificate will be displayed in a frame -->
    <iframe
      id="frameBcd"
      width="100%"
      height="100%"
      style="position:absolute;overflow:hidden;height:100%;margin: 0;padding: 0;top: 0;left:0"
      frameborder="0"
      allowfullscreen
    >
    </iframe>
  </body>
  <script>
    let url = window.location.href;
    let query = url.split("?");
    let queries = query[1].split("&");
    let env, key, baseUrl;
    for (let i = 0; i < queries.length; i++) {
      let temp = queries[i].split("=");
      if (temp[0] === "env") env = temp[1];
      else if (temp[0] === "key") key = temp[1];
    }
    switch (env) {
      case "demo":
        baseUrl = "https://certificate-demo.bcdiploma.com/check/";
        break;
      case "staging":
        baseUrl = "https://certificate-staging.bcdiploma.com/check/";
        break;
      default:
        baseUrl = "https://certificate.bcdiploma.com/check/";
    }
    // Indique el nombre de dominio en el que está alojado el archivo, sin incluir los subdirectorios
    let host = "?host=subdomain.yourdomain.com";
    document.getElementById("frameBcd").src = baseUrl + key + host;
  </script>
</html>

Paso 4: avise a nuestro equipo

Indique a nuestro equipo la ruta de acceso a estos archivos; actualizaremos la blockchain para que los certificados sean accesibles desde su URL lo antes posible.

Preguntas frecuentes

He configurado una redirección de tipo CNAME entre un subdominio de mi dominio institucional y un subdominio de visualización de certificados de BCdiploma (p. ej., certificate.bcdiploma.com) y no funciona: aparece un error al consultar mi certificado. ¿Qué ocurre?

Un registro CNAME no es una redirección web: es únicamente un alias DNS. El navegador sigue accediendo a su URL (p. ej., certificado.su-dominio.com) y, en HTTPS, exige un certificado SSL válido para ese nombre de dominio. Ahora bien, los servidores de BCdiploma presentan un certificado SSL para certificate.bcdiploma.com, no para certificado.su-dominio.com: esto provoca un error de certificado (mismatch/SSL) y la página no puede mostrarse correctamente. Para mostrar los certificados en su dominio, es necesario configurar un proxy inverso (Nginx/Apache/etc.): este termina la conexión HTTPS con su certificado y, a continuación, reenvía las solicitudes a certificate.bcdiploma.com conservando la URL y añadiendo los encabezados esperados (p. ej., custom-host), de acuerdo con la documentación.

Nota: el método “proxy inverso operado por BCdiploma” descrito más arriba sí se basa en un registro CNAME, pero este apunta a un punto de entrada dedicado, aprovisionado por nuestro equipo, que presenta un certificado SSL emitido a nombre de su subdominio. Es ese aprovisionamiento previo lo que hace que el alias DNS funcione, a diferencia de un CNAME que apunte directamente a certificate.bcdiploma.com.

¿Puedo utilizar mi dominio raíz (your-domain.com) en lugar de un subdominio?

No con los métodos 2 y 3: un dominio raíz no puede tener un registro CNAME (limitación del estándar DNS). Utilice un subdominio dedicado (p. ej., certificate.your-domain.com), o el método del proxy inverso si desea servir los certificados bajo una ruta de su dominio principal.