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

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

1. Solution recommandée 1 : le paramétrage de votre reverse proxy (nécessaire si vous souhaitez un chemin de type your-domain.com/certificates)
2. Solution recommandée 2 : le reverse proxy opéré par BCdiploma (votre domaine personnalisé via quelques enregistrements DNS, aucune infrastructure de votre côté)
3. Solution recommandée 3 : la délégation de votre sous-domaine à BCdiploma (une seule opération DNS, une seule fois — nous gérons tout ensuite, renouvellements compris)
4. Solution non recommandée : la mise en place d'un système d'iframe

Méthode 1 recommandée : avec votre reverse proxy

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 un relais (proxy) transparent 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.

Avantages :

• Permet d'utiliser un chemin sur un domaine existant (ex : your-domain.com/certificates)
• 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

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 l'adresse de votre domaine de certificats, nous ferons une mise à jour de la blockchain pour que les certificats soient accessibles depuis votre URL au plus vite.

Méthode 2 recommandée : avec un reverse proxy opéré par BCdiploma

Fonctionnement

BCdiploma peut afficher directement vos certificats sur un sous-domaine de votre institution (ex : certificate.your-domain.com), sans aucune infrastructure à déployer de votre côté. La terminaison HTTPS, l'émission du certificat SSL à votre nom et son renouvellement sont entièrement pris en charge par la plateforme BCdiploma. Votre équipe IT n'a que trois enregistrements DNS à créer, en deux temps.

Le principe est un alias DNS : votre sous-domaine pointe, via un enregistrement CNAME, vers un point d'entrée dédié provisionné par BCdiploma (un reverse proxy opéré par BCdiploma), qui présente un certificat SSL émis au nom de votre sous-domaine. Deux enregistrements TXT permettent au préalable de prouver que vous contrôlez bien ce nom de domaine.

La mise en place se fait environnement par environnement : d'abord la recette (ex : certificate-staging.your-domain.com), puis la production (ex : certificate.your-domain.com). Le processus ci-dessous est identique dans les deux cas ; seules les valeurs fournies par nos services diffèrent.

Avantages :

• Aucune infrastructure à déployer ni à maintenir chez vous (pas de serveur, pas de reverse proxy à opérer vous-même)
• Certificat SSL émis et renouvelé automatiquement par nos services
• Compatibilité maximale avec les réseaux sociaux et tous navigateurs
• Transparence pour l'utilisateur final

Inconvénients :

• Nécessite un sous-domaine dédié (ex : certificate.your-domain.com). Les adresses de type your-domain.com/certificates (chemin sur un domaine existant) ne sont pas possibles avec cette méthode.
• Trois enregistrements DNS à créer par votre équipe IT, en deux étapes espacées de quelques jours au maximum.
• Coût additionnel annuel à prévoir sur la licence. Il couvre le provisionnement d'un point d'entrée dédié à votre domaine sur notre infrastructure de diffusion, l'émission et le renouvellement automatique du certificat SSL à votre nom, ainsi que la supervision de ce service dans la durée. Contactez nos services pour en connaître les modalités tarifaires.

Prérequis

• 2 sous-domaines dédiés à l'affichage des certificats (ex : certificate.your-domain.com ou digitalcredential.your-domain.com), un pour la recette et l'autre pour la production. Un domaine racine (your-domain.com sans préfixe) ne peut pas être utilisé.
• De la réactivité : l'un des enregistrements fournis expire au bout de 7 jours (voir Étape 2).

Étape 1 : demandez l'activation à nos services

Communiquez à nos services le sous-domaine souhaité pour l'environnement concerné (ex : certificate-staging.your-domain.com pour la recette).

En retour, nous vous transmettrons la valeur de l'enregistrement _dnsauth à créer (la valeur du second enregistrement, asuid, est fixe et figure ci-dessous).

Étape 2 : créez les deux enregistrements TXT de validation

Créez les deux enregistrements suivants dans votre zone DNS :

Exemple pour digitalcredential-staging.your-domain.com :

Une fois les enregistrements créés, prévenez nos services.

Étape 3 : attendez notre confirmation

À réception de vos enregistrements, nos services procèdent à la validation du domaine, à l'émission du certificat SSL à votre nom et au paramétrage de la plateforme. Nous vous confirmons la fin de ces opérations en vous communiquant la cible du CNAME à créer. Ce délai est généralement inférieur à 48h.

Étape 4 : créez l'enregistrement CNAME

Créez l'enregistrement final avec la cible correspondant à votre environnement, telle que confirmée par nos services à l'étape 3. Ne créez ce CNAME que pour l'environnement en cours de mise en place (chaque environnement suit son propre cycle d'étapes 1 à 5) :

Après propagation DNS (de quelques minutes à quelques heures selon votre TTL), vos certificats sont consultables sur votre sous-domaine, en HTTPS, avec un certificat SSL à votre nom.

Étape 5 : vérifiez et conservez la configuration

Vérifiez l'affichage d'un certificat de test sur votre sous-domaine, puis répétez le processus pour l'environnement de production.

Méthode 3 recommandée : en déléguant votre sous-domaine à BCdiploma

Fonctionnement

Cette méthode produit le même résultat que la méthode 2 — vos certificats servis sur votre sous-domaine, avec un certificat SSL à votre nom entièrement géré par nos soins — mais avec une intégration DNS différente : au lieu de créer vous-même les enregistrements de validation puis le CNAME, vous déléguez la gestion DNS du sous-domaine à BCdiploma via des enregistrements NS. Le sous-domaine devient alors une zone DNS opérée par nos services : nous y créons et maintenons tous les enregistrements nécessaires, aujourd'hui comme lors des renouvellements futurs du certificat.

Quand préférer cette méthode à la méthode 2 :

• votre système DNS ne permet pas de créer les enregistrements demandés par la méthode 2 (par exemple des enregistrements enfants sous un nom portant déjà un CNAME) ;
• vos modifications DNS passent par un processus de changement long ou contraint, que vous ne souhaitez solliciter qu'une seule fois ;
• vous souhaitez n'avoir plus jamais aucune action DNS à effectuer pour ce service.

Avantages :

• Une seule opération DNS, une seule fois : aucune intervention ultérieure de vos équipes, y compris pour les renouvellements de certificat
• Aucune des valeurs fournies n'expire : réalisez l'opération au moment qui convient à votre processus interne
• Interruption de service minimale si un service existe déjà sur ce sous-domaine : notre zone est préconfigurée pour répondre exactement comme votre DNS actuel, et la bascule effective n'a lieu que plus tard, sous notre contrôle, une fois le certificat émis
• Aucune infrastructure de votre côté, compatibilité maximale avec les réseaux sociaux et tous navigateurs, transparence pour l'utilisateur final

Inconvénients :

• Le sous-domaine délégué est entièrement géré par BCdiploma : vous ne pouvez plus y créer d'enregistrements vous-même. Ne déléguez qu'un sous-domaine strictement dédié à l'affichage des certificats.
• Nécessite un sous-domaine dédié (les adresses de type your-domain.com/certificates ne sont pas possibles avec cette méthode).
• Coût additionnel annuel à prévoir sur la licence, aux mêmes modalités que la méthode 2 — contactez nos services.

Prérequis

• 2 sous-domaines dédiés (un pour la recette, un pour la production).
• Votre hébergeur DNS doit permettre la création d'enregistrements NS pour un sous-domaine (délégation) — c'est le cas de la quasi-totalité des registrars et services DNS.

Étape 1 : demandez l'activation à nos services

Communiquez à nos services :

• le sous-domaine souhaité pour l'environnement concerné (ex : digitalcredential-staging.your-domain.com pour la recette) ;
• si un service répond déjà sur ce nom (cas d'une migration) : indiquez-le-nous — nous préconfigurerons notre zone pour assurer la continuité, sans aucune interruption pour vos utilisateurs.

En retour, nous vous transmettrons les 4 enregistrements NS à créer.

Étape 2 : créez la délégation

Dans votre zone DNS, créez les 4 enregistrements NS fournis :

Prévenez nos services une fois les opérations effectuées.

Étape 3 : nous faisons le reste

À réception de votre confirmation, nos services réalisent l'ensemble des opérations (validation, émission du certificat SSL à votre nom, mise en service, bascule du trafic) et vous confirment la mise en service. Dans le cas d'une migration, conservez votre ancien service actif jusqu'à notre confirmation explicite qu'il peut être décommissionné.

Méthode 4 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 certificats déjà émis, ce qui est 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=684B6E2716D35894A1DEF33DE4F30B415D3C8953F8F2CDF7808582B4F0D0F6D7aVBzTmpBREQ0bXZCVUpybDlqYklvRmZxTnJEVVgza3BGVVFoczk5NE1ZSTNWOAAA)

É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 le 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 personnalisez-le :

• Entre les balises indiquées dans <head>
• Dans la variable 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.

À noter : la méthode « reverse proxy opéré par BCdiploma » décrite plus haut repose bien, elle, sur un enregistrement CNAME — mais celui-ci pointe vers un point d'entrée dédié, provisionné par nos services, qui présente un certificat SSL émis au nom de votre sous-domaine. C'est ce provisionnement préalable qui rend l'alias DNS fonctionnel, contrairement à un CNAME pointant directement vers certificate.bcdiploma.com.

Puis-je utiliser mon domaine racine (your-domain.com) plutôt qu'un sous-domaine ?

Non pour les méthodes 2 et 3 : un domaine racine ne peut pas porter d'enregistrement CNAME (limitation du standard DNS). Utilisez un sous-domaine dédié (ex : certificate.your-domain.com), ou la méthode reverse proxy si vous souhaitez servir les certificats sous un chemin de votre domaine principal.