Intégration du certificat dans le site Internet de l'émetteur

Introduction

L'objectif de cette page est de décrire comment vous permettre d'afficher les certificats BCdiploma sur un autre domaine que bcdiploma.com, par exemple le vôtre.

Par défaut, les certificats BCdiploma sont accessibles et affichés aux URL suivantes en fonction de l'environnement :

• Staging : https://certificate-staging.bcdiploma.com
• Production (données situées dans la zone UE) : https://certificate.bcdiploma.com
• Production (données situées dans la zone US) : https://certificate-cus.bcdiploma.com

2 méthodes différentes sont documentées ici pour permettre de les rendre consultables sur le domaine de l'émetteur, par exemple : https://your-domain.com/certificates ou https://certificate.your-domain.com

1. Solution préférentielle : le paramétrage de votre reverse proxy
2. Solution alternative, non recommandée : la mise en place d'un système d'iframe

La redirection doit être permanente, fonctionner en HTTPS et préserver le chemin et les paramètres (par exemple /index.html?key=...). Le certificat TLS de l’ancien domaine doit rester valide tant que la redirection est active. Nous recommandons de surveiller régulièrement la disponibilité de vos adresses (URL), ainsi que l’échéance du domaine et des certificats, et d’inscrire ce point dans votre liste de contrôle lors d’un changement de domaine ou d’identité visuelle. Cette redirection doit impérativement être mise en œuvre par l’équipe informatique de votre institution, seule à connaître votre architecture réseau interne (serveurs, DNS, réseau, sécurité...). Les options usuelles comprennent la redirection HTTP côté serveur (301/308), une règle au niveau du réseau de diffusion de contenu (CDN) ou de la passerelle d’accès, un reverse-proxy sur l’ancien domaine, une redirection via sous-domaine dédié (DNS + HTTP) ou une redirection générique « wildcard » pour plusieurs sous-domaines.

Méthode recommandée : en paramétrant votre reverse proxy

Avantages :

• Compatibilité maximale avec les réseaux sociaux
• Peu de maintenance à effectuer une fois mis en place
• Compatibilité maximale avec tous navigateurs
• Transparence pour l'utilisateur final

Inconvénients :

• Nécessite une intervention initiale de votre équipe IT/infrastructure

Fonctionnement

Cet article décrit comment paramétrer un reverse-proxy pour que les certificats BCdiploma soient affichés sur votre domaine plutôt que sur le domaine bcdiploma.com. Concrètement, il s'agit de mettre en place au niveau réseau une redirection automatique entre votre domaine (ex: certificates.your-domain.com) et le domaine bcdiploma.com.

Notons qu'il existe une multitude de reverse proxy sur le marché (nginx, apache, etc.) et autant de type de mise en œuvre dans les systèmes d'information. La documentation ci-dessous décrit donc uniquement les principes à mettre en œuvre sur votre infrastructure, à l'aide de votre équipe IT qui en connait les spécificités.

Prérequis : Paramètres relatifs à la taille des headers

Pour prendre en compte les headers CSP, vous devez modifier certains paramètres de votre reverse proxy:

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

Étape 1 : mettez en place une redirection pour l'environnement de recette

Vous devez rediriger les requêtes arrivant sur un domaine spécifique de votre réseau qui sera utilisé pour la recette (ex : certificate-staging.your-domain.com) vers le domaine de recette de BCdiploma, à savoir certificate-staging.bcdiploma.com. Cette redirection doit être accompagnée d'un header custom-host ayant comme valeur votre nom de domaine your-domain.com.

Exemples de fichier de configuration pour différents serveurs reverse-proxy :

• 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 / {
	    # on ajoute un paramètre custom-host dans le header
		  # qui correspond au domaine pour lequel les certificats pourront être visualisés
      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>

Indiquez à nos services votre domaine d'accès de recette ainsi mis en place : nous ferons une mise à jour de la blockchain pour que les certificats de recette soient accessibles sur cette adresse au plus vite.

Étape 2 : Mettez en place les redirections pour l'environnement de production

Répétez l'opération ci-dessus pour rediriger les requêtes de votre domaine de production (ex : certificate.your-domain.com) vers le domaine de production de BCdiploma, ex :

• 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 / {
	    # on ajoute un paramètre custom-host dans le header
		  # qui correspond au domaine pour lequel les certificats pourront être visualisés
      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>

Étape 3 : alertez nos services

Indiquez à nos services le chemin d'accès à ces fichiers, nous ferons une mise à jour de la blockchain pour que les certificats soient accessibles depuis votre URL au plus vite.

Méthode alternative (non recommandée) : mise en place d'un système d'iframe

Avantages :

• Nécessite une intervention initiale simple pour les équipes IT

Inconvénients :

• En cas de changement d'infrastructure sur votre site web, il sera impératif de conserver le même chemin d'accès aux certficats déjà émis, ce qui être une opération complexe notamment lors d'un changement de type de serveur Web ou de CMS.
• Support limité des vignettes dans les réseaux sociaux. Seule une image fixe que vous indiquerez dans le code de l'iframe sera affichée comme miniature sur les réseaux sociaux. Notamment, les logos utilisés dans vos modèles de microcertifications ne seront pas affichés comme miniatures dans ce contexte.
• Le code de l'iframe peut ponctuellement nécessiter des mises à jour

Fonctionnement

Les certificats BCdiploma seront affichés dans une iframe hébergée sur le site tiers. Concrètement, le site tiers hébergera :

• une page html statique (fournie par nos services) permettant d'afficher dans une iframe les certificats provenant de certificate.bcdiploma.com ou certificate-cus.bcdiploma.com;
• une vignette qui sera utilisée dans les aperçus sur les sites web (ex : réseaux sociaux) où le lien est partagé.

Vous trouverez ici un exemple d'intégration d'une iframe sur le site myBCdiploma.

L'identifiant du certificat sera passé en paramètre à cette page pour afficher un certificat spécifique (ex : https://your-domain.com/certificates/index.html?key=684B6E2716D35894A1DEF33DE4F30B415D3C8953F8F2CDF7808582B4F0D0F6D7aVBzTmpBREQ0bXZCVUpybDlqYklvRmZxTnJEVVgza3BGVVFoczk5NE1ZSTNWOAA)

Étape 1 : préparation de votre serveur Web

Sur votre serveur Web, créer un répertoire dédié (ex : certificates), https://your-domain.com/certificates ou choisissez un répertoire existant (dans ce dernier cas, veillez à ne pas écraser son contenu dans les étapes suivantes)

Étape 2 : préparation du fichier vignette

Préparez un fichier image contenant votre logo et placez la dans le dossier créé en 1. C'est cette image qui sera affichée en aperçu sur les sites sur lesquels les liens de vos certificats seront partagés. Notez que nous pouvons vous fournir une vignette optimisée pour LinkedIn. Format optimal : 1200*627px Exemple : https://www.bcdiploma.com/img/thumbnail-opengraph.png

Étape 3 : préparation du fichier HTML

Préparez un fichier index.html avec le contenu suivant et personnaliser-le :

• Entre les balises indiquée dans <head>
• Dans la balise host en fin de fichier

Placez-le dans le répertoire créé en 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" />

    <!-- Début des informations personnalisables -->

    <!-- Personnalisez les titres et descriptions qui seront affichés dans les onglets des navigateurs et dans les partages sur les réseaux sociaux -->
    <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."
    />

    <!-- Personnalisez l'image de "preview" qui sera affichée sur les réseaux sociaux  -->
    <!-- Utilisez un chemin complet. Format optimal : 1200*627px -->
    <meta
      property="og:image"
      content="https://www.bcdiploma.com/img/thumbnail-opengraph.png"
    />

    <!-- Personnalisez l'icône qui sera affiché dans l'onglet des navigateurs -->
    <!-- Utilisez un chemin complet. Format optimal : 32*32px -->
    <link href="https://www.bcdiploma.com/bcdiploma-favicon.png" rel="icon" />

    <!-- Mettez votre nom d'émetteur dans "content" -->
    <meta property="article:author" content="BCdiploma" />

    <!-- Fin des informations personnalisables -->

    <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/";
    }
    // Indiquez le nom de domaine sur lequel le fichier est hébergé en excluant les sous-répertoires
    let host = "?host=subdomain.yourdomain.com";
    document.getElementById("frameBcd").src = baseUrl + key + host;
  </script>
</html>

Étape 4 : alertez nos services

Indiquez à nos services le chemin d'accès à ces fichiers, nous ferons une mise à jour de la blockchain pour que les certificats soient accessibles depuis votre URL au plus vite.

FAQ

J’ai mis en place une redirection de type CNAME entre un sous-domaine de mon domaine institutionnel et un sous-domaine d’affichage des certificats de BCdiploma (ex. certificate.bcdiploma.com) et cela ne fonctionne pas : j’ai une erreur à la consultation de mon certificat. Que se passe-t-il ?

Un enregistrement CNAME n’est pas une redirection web : c’est uniquement un alias DNS. Le navigateur accède toujours à votre URL (ex. certificat.votre-domaine.com) et, en HTTPS, il exige un certificat SSL valide pour ce nom de domaine. Or, les serveurs BCdiploma présentent un certificat SSL pour certificate.bcdiploma.com, pas pour certificat.votre-domaine.com : cela provoque une erreur de certificat (mismatch/SSL) et la page ne peut pas s’afficher correctement. Pour afficher les certificats sur votre domaine, il faut mettre en place un reverse proxy (Nginx/Apache/etc.) : il termine le HTTPS avec votre certificat, puis proxy les requêtes vers certificate.bcdiploma.com en conservant l’URL et en ajoutant les en-têtes attendus (ex. custom-host) conformément à la documentation.