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 at the following URLs, depending on the environment:

• Staging: https://certificate-staging.bcdiploma.com
• Production (data located in the EU zone): https://certificate.bcdiploma.com
• Production (data located in the US zone): https://certificate-cus.bcdiploma.com

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

1. Recommended solution 1: setting up your reverse proxy (required if you want a path on an existing domain, such as your-domain.com/certificates)
2. Recommended solution 2: the BCdiploma-operated reverse proxy (your custom domain through a few DNS records, no infrastructure on your side)
3. Recommended solution 3: delegating your subdomain to BCdiploma (a single DNS operation, done once — we manage everything afterwards, renewals included)
4. Not recommended solution: implementation of an iframe system

Recommended method 1: with your reverse proxy

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, at the network level, a transparent relay (proxy) 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.

Advantages:

• Allows you to use a path on an existing domain (e.g. your-domain.com/certificates)
• 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

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.

Recommended method 2: with a BCdiploma-operated reverse proxy

How it works

BCdiploma can display your certificates directly on a subdomain of your institution (e.g. certificate.your-domain.com), with no infrastructure to deploy on your side. HTTPS termination, the issuance of the SSL certificate in your name and its renewal are fully handled by the BCdiploma platform. Your IT team only has three DNS records to create, in two stages.

The principle is a DNS alias: your subdomain points, via a CNAME record, to a dedicated entry point provisioned by BCdiploma (a reverse proxy operated by BCdiploma), which presents an SSL certificate issued in the name of your subdomain. Two TXT records are used beforehand to prove that you actually control this domain name.

The setup is done environment by environment: first staging (e.g. certificate-staging.your-domain.com), then production (e.g. certificate.your-domain.com). The process below is identical in both cases; only the values provided by our services differ.

Advantages:

• No infrastructure to deploy or maintain on your side (no server, no reverse proxy to operate yourself)
• SSL certificate issued and renewed automatically by our services
• Maximum compatibility with social networks and all browsers
• Totally transparent for the end user

Disadvantages:

• Requires a dedicated subdomain (e.g. certificate.your-domain.com). Addresses such as your-domain.com/certificates (a path on an existing domain) are not possible with this method.
• Three DNS records to be created by your IT team, in two stages a few days apart at most.
• An additional annual cost on the license. It covers the provisioning of an entry point dedicated to your domain on our delivery infrastructure, the issuance and automatic renewal of the SSL certificate in your name, and the ongoing supervision of this service. Please contact our services for pricing details.

Prerequisites

• 2 dedicated subdomains for displaying certificates (e.g. certificate.your-domain.com or digitalcredential.your-domain.com), one for staging and the other for production. A root domain (your-domain.com without a prefix) cannot be used.
• Responsiveness: one of the records provided expires after 7 days (see Step 2).

Step 1: request activation from our services

Send our services the desired subdomain for the environment concerned (e.g. certificate-staging.your-domain.com for staging).

In return, we will send you the value of the _dnsauth record to create (the value of the second record, asuid, is fixed and shown below).

Step 2: create the two TXT validation records

Create the following two records in your DNS zone:

Example for digitalcredential-staging.your-domain.com:

Once the records are created, notify our services.

Step 3: wait for our confirmation

Upon receipt of your records, our services validate the domain, issue the SSL certificate in your name and configure the platform. We will confirm the completion of these operations by sending you the CNAME target to create. This usually takes less than 48 hours.

Step 4: create the CNAME record

Create the final record with the target corresponding to your environment, as confirmed by our services at step 3. Only create this CNAME for the environment currently being set up (each environment follows its own cycle of steps 1 to 5):

After DNS propagation (from a few minutes to a few hours depending on your TTL), your certificates can be viewed on your subdomain, over HTTPS, with an SSL certificate in your name.

Step 5: verify and keep the configuration

Check that a test certificate is displayed correctly on your subdomain, then repeat the process for the production environment.

Recommended method 3: by delegating your subdomain to BCdiploma

How it works

This method produces the same result as method 2 — your certificates served on your subdomain, with an SSL certificate in your name fully managed by us — but with a different DNS integration: instead of creating the validation records and then the CNAME yourself, you delegate the DNS management of the subdomain to BCdiploma through NS records. The subdomain then becomes a DNS zone operated by our services: we create and maintain all the necessary records there, both today and for future certificate renewals.

When to prefer this method over method 2:

• your DNS system does not allow you to create the records required by method 2 (for example child records under a name that already carries a CNAME);
• your DNS changes go through a long or constrained change process, which you only want to go through once;
• you want to never have to perform any DNS action again for this service.

Advantages:

• A single DNS operation, done once: no further intervention from your teams, including for certificate renewals
• None of the provided values expire: carry out the operation whenever it suits your internal process
• Minimal service interruption if a service already exists on this subdomain: our zone is preconfigured to respond exactly like your current DNS, and the actual switchover only happens later, under our control, once the certificate has been issued
• No infrastructure on your side, maximum compatibility with social networks and all browsers, totally transparent for the end user

Disadvantages:

• The delegated subdomain is fully managed by BCdiploma: you can no longer create records on it yourself. Only delegate a subdomain strictly dedicated to certificate display.
• Requires a dedicated subdomain (addresses such as your-domain.com/certificates are not possible with this method).
• An additional annual cost on the license, under the same terms as method 2 — please contact our services.

Prerequisites

• 2 dedicated subdomains (one for staging, one for production).
• Your DNS provider must allow the creation of NS records for a subdomain (delegation) — this is the case with almost all registrars and DNS services.

Step 1: request activation from our services

Send our services:

• the desired subdomain for the environment concerned (e.g. digitalcredential-staging.your-domain.com for staging);
• if a service already responds on this name (migration case): let us know — we will preconfigure our zone to ensure continuity, without any interruption for your users.

In return, we will send you the 4 NS records to create.

Step 2: create the delegation

In your DNS zone, create the 4 NS records provided:

Notify our services once the operations have been carried out.

Step 3: we do the rest

Upon receipt of your confirmation, our services carry out all the operations (validation, issuance of the SSL certificate in your name, commissioning, traffic switchover) and confirm to you that the service is live. In the case of a migration, keep your old service active until our explicit confirmation that it can be decommissioned.

Not recommended method 4: 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 or certificate-cus.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 variable 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>

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.

Note: the "BCdiploma-operated reverse proxy" method described above does rely on a CNAME record—but that CNAME points to a dedicated entry point, provisioned by our services, which presents an SSL certificate issued in the name of your subdomain. It is this prior provisioning that makes the DNS alias work, unlike a CNAME pointing directly to certificate.bcdiploma.com.

Can I use my root domain (your-domain.com) rather than a subdomain?

Not with methods 2 and 3: a root domain cannot carry a CNAME record (a limitation of the DNS standard). Use a dedicated subdomain (e.g. certificate.your-domain.com), or the reverse proxy method if you want to serve the certificates under a path of your main domain.