Certificate’s integration in the issuer Website

Introduction

The purpose of this page is to describe how you can display BCdiploma certificates on a domain other than bcdiploma.com, such as your own.

By default, BCdiploma certificates are accessible and displayed on https://certificate.bcdiploma.com.

2 different methods are documented here to make them accessible on the issuer's domain, for example: https://your-domain.com/certificates or https://certificate.your-domain.com

1. Preferred solution: Setting up your reverse proxy
2. Alternative solution (not recommanded): Implementation of an iframe system

The redirection must be permanent, work over HTTPS, and preserve both the path and the parameters (for example: /index.html?key=...). The TLS certificate of the old domain must remain valid as long as the redirection is active. We recommend regularly monitoring the availability of your URLs, as well as the expiration of the domain and certificates, and adding this requirement to your checklist when performing a domain change or rebranding. This redirection must be implemented by your institution’s IT team, as they are the only ones who know your internal network architecture (servers, DNS, network, security, etc.). Common options include server-side HTTP redirection (301/308), a rule at the content delivery network (CDN) or access gateway level, a reverse proxy on the old domain, a redirection via a dedicated subdomain (DNS + HTTP), or a generic “wildcard” redirection covering multiple subdomains.

Preferred method: by setting up your reverse proxy

Advantages:

• Maximum compatibility with social networks
• Little maintenance to do once set it up
• Maximum compatibility with any browser
• Totally transparent for the end user

Disadvantages:

• Requires an initial intervention from your IT/infrastructure team

How it works

This article describes how to set up a reverse proxy so that BCdiploma certificates are displayed on your domain rather than on the bcdiploma.com domain. In concrete terms, it is about setting up an automatic redirection between your domain (e.g. certificates.your-domain.com) and the bcdiploma.com domain.

Note that there is a multitude of reverse proxies on the market (nginx, apache, etc.) and as many types of implementation in information systems. The documentation below only describes the principles to implement on your infrastructure, with the help of your IT team who is aware of your specificities.

Prerequisite: header size settings

To support the CSP headers, you need to change some settings in your reverse proxy:

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

Step 1: set up a redirection for the staging environment

You need to redirect incoming requests to a specific domain on your network that will be used for the staging (e.g. certificate-staging.your-domain.com) to the BCdiploma staging domain, i.e. certificate-staging.bcdiploma.com. This redirection must be combined with a custom-host header with your your-domain.com domain name as value.

Examples of configuration files for different reverse-proxy servers:

• 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 / {
	    # we add a custom-host parameter in the header
		  # which corresponds to the domain for which the certificates can be viewed
      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>

Tell our services your staging domain thus set up: we will update the blockchain so that the staging certificates will be accessible on this address as soon as possible.

Step 2: set up redirections for the production environment

Repeat the above operations to redirect requests from your production domain (e.g. certificate.your-domain.com) to BCdiploma's production domain, namely certificate.bcdiploma.com, 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 / {
	    # we add a custom-host parameter in the header
		  # which corresponds to the domain for which the certificates can be viewed
      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>

Step 3: please advise our services

Tell our services the path to your certificates domain, we will update the blockchain so that the certificates are accessible from your URL as soon as possible.

Alternative method (not recommanded): setting up an iframe system

Advantages:

• Requires a simple initial intervention by your IT/infrastructure team

Disadvantages:

• If you change the infrastructure of your website, you'll need to keep the same access path to the certificates you've already issued. This can be a complex operation, especially if you change the type of web server or CMS.
• Limited handling of thumbnails in social networks. Only a static image that you specify in the iframe code will be displayed as a thumbnail on social networks. In particular, logos used in your microcertification templates will not be displayed as thumbnails in this context
• The iframe code may need to be updated from time to time

How it works

BCdiploma certificates will be displayed in an iframe hosted on the third-party site. In concrete terms, the third-party website will host:

• a simple static html page (provided by our services) allowing to display in an iframe the certificates coming from certificate.bcdiploma.com.
• a thumbnail used in overviews on websites where the link is shared

Please find here an example of an iframe integration on the myBCdiploma website.

The identifier of the certificate will be passed as a parameter to this page (ex: https://your-domain.com/certificates/index.html?key=684B6E2716D35894A1DEF33DE4F30B415D3C8953F8F2CDF7808582B4F0D0F6D7aVBzTmpBREQ0bXZCVUpybDlqYklvRmZxTnJEVVgza3BGVVFoczk5NE1ZSTNWOAAA) to display a specific certificate.

Step 1: preparing your web server

On your web server, create a dedicated directory (ex: certificates), https://your-domain.com/certificates, or choose an existing directory (in the second case, be careful not to overwrite its contents in the following steps)

Step 2: preparing the thumbnail file

Prepare an image file containing your logo and place it in the folder created in 1. It is this image that will be previewed on the sites on which the links of your certificates will be shared. Note that we can provide you with a thumbnail optimized for LinkedIn. Optimal dimensions: 1200*627px Example: https://www.bcdiploma.com/img/thumbnail-opengraph.png

Step 3: preparation of the HTML file

Prepare an index.html file with the following content and customize it:

• Enter the tags indicated in <head>
• In the host tag at the end of the file

and place it in the directory created in step 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" />

    <!-- Start of customizable information -->

    <!-- Customize the titles and descriptions that will be displayed in browser tabs and social media shares -->
    <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."
    />

    <!-- Customize the preview image that will be displayed on social media -->
    <!-- Use a full path. Optimal format: 1200*627px -->
    <meta
      property="og:image"
      content="https://www.bcdiploma.com/img/thumbnail-opengraph.png"
    />

    <!-- Customize the favicon that will be displayed in the browser tab -->
    <!-- Use a full path. Optimal format: 32*32px. -->
    <link href="https://www.bcdiploma.com/bcdiploma-favicon.png" rel="icon" />

    <!-- Put your issuer name in "content" -->
    <meta property="article:author" content="BCdiploma" />

    <!-- End of customizable information -->

    <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/";
    }
    // Specify the domain name on which the file is hosted, excluding subdirectories
    let host = "?host=subdomain.yourdomain.com";
    document.getElementById("frameBcd").src = baseUrl + key + host;
  </script>
</html>

4. Step 4: please advise our services

Tell our services the path to these files, we will update the blockchain so that the certificates are accessible from your URL as soon as possible.

FAQ

I set up a CNAME “redirect” from a subdomain on my institutional domain to a BCdiploma certificate display subdomain (e.g., certificate.bcdiploma.com), but it doesn’t work. I get an error when opening a certificate—what’s happening?

A CNAME record is not a web redirect—it’s only a DNS alias. The browser still connects to your hostname (e.g., certificates.your-domain.com) and, over HTTPS, it requires a TLS/SSL certificate that matches that exact hostname. BCdiploma’s servers present a certificate for certificate.bcdiploma.com, not for certificates.your-domain.com, which results in an SSL certificate mismatch / TLS error. To serve certificates on your domain, you need a reverse proxy (Nginx/Apache/etc.): it terminates HTTPS using your certificate, then proxies requests to certificate.bcdiploma.com while keeping the URL transparent and adding the required headers (e.g., custom-host) as described in the documentation.