Go back to the procedure overview

II. Create the Client Certificate (CC)

Generate the Client Certificate (CC) file using your new Certificate Authority (CA) key.

Use the following command to create the Client Certificate file [myClientCertificate]-CC.pem using your new Certificate Authority key. Here, replace [myClientCertificate] with whatever name you want for the Client Certificate. We suggest keeping the -CC suffix to identify this file as the Client Certificate. An example might be Opto22-CC.pem. This file will be distributed to and installed in any client operating systems or browsers that need to securely connect with your groov EPIC. This is the only file that should be distributed.

Note that your Certificate Authority key file should be -CA.key – which should be kept secure and never distributed, whereas the Client Certificate you’re about to create is -CC.pem, and will be distributed.

You will be prompted to enter the passphrase associated with your CA key created in step I. Next, you’ll be prompted to set the details for your Client Certificate. These details will be viewable by anyone that installs the Client Certificate, so be mindful of the information entered. Most of these fields can be left blank, but three have default values so we recommended filling them out completely. Here are some examples:

        Country Name (2 letter code) [AU]: US
        State or Province Name (full name) [Some-State]: California
        Locality Name (eg, city) []: Temecula
        Organization Name (eg, company) [Internet Widgits Pty Ltd]: Opto 22
        Organizational Unit Name (eg, section) []: IT Services
        Common Name (e.g. server FQDN or YOUR name) []: Opto 22 CA
        Email Address []: developer@opto22.com

If you’re outside the United States, you can find your 2-letter Country Name code on wordlatlas.com. Note that if you do not enter a value for this field it will default to the Australian country code “AU”.

The State or Province Name should be written out in full, not abbreviated (for example “Washington” rather than “WA”). If you do not enter a value for this field it will default to “Some-State”.

The Organization Name should be your company or reflect where the Client Certificate will be used. If you do not enter a value for this field it will default to “Internet Widgits Pty Ltd”.

The Organizational Unit can be whatever you like - for example your department name or just left blank.

The Common Name is the name of the Certificate Authority as it will appear in your operating system or browser’s trusted list. We recommend using the name you chose for your Certificate Authority key file. It will be easier to recognize it in the list of trusted Certificate Authorities in later steps.

Finally, the Email Address should be the contact for any issues with the Client Certificate (for example, the IT department’s email address), or just left blank.

At the command line, type the following, replacing [myCertificateAuthority] with your CA, and [myClientCertificate] with the chosen name of your Client Certificate:

openssl req -x509 -new -nodes -key [myCertificateAuthority]-CA.key -sha256 -days 397 -out [myClientCertificate]-CC.pem

Top

III. Add the client certificate to your operating system or browser’s list of trusted authorities

Skip to Windows, Chrome, Firefox, or Mac OS.

Windows

  • To add the certificate to the Windows Trusted Root CA list so all browsers can use it:
    1. Open the Start menu, type in run and launch the “Run” desktop application. In the popup type in MMC, and launch the Microsoft Management Console (MMC).
    2. Click file, then Add/Remove Snap-in, a new popup will appear.
    3. Select the Certificates snap-in, then click Add > to add it, which will bring open another popup.
    4. Choose to add this for either the computer account or the individual user account, depending on who has access to the machine. If you are adding the snap-in for the computer account you will get another screen where you will need to confirm you are adding it for this local computer, not another computer on the network.
      Click finish.
    5. Click OK to add the snap-in.
    6. Double click the Certificates snap-in under Console Root to see the certificates list.
    7. Right-click on the folder titled Trusted Root Certification Authorities and in the resulting pop-up, choose the All Tasks option, then click import, which brings open the certificate import wizard.
    8. In this wizard select next to continue and then click browse to open a file browser. Now navigate to the folder where you created your certificate files and select your [myClientCertificate]-CC.pem file.
      Do NOT select the [myCertificateAuthority]-CA.key; instead, change the file filter above the Open button to show All Files (*.*). Now select your [myClientCertificate]-CC.pem file, and then click Open.
    9. Click Open to load the file and then Next to continue in the wizard.
    10. For the option to “Place all certificates in the following store” you *must place the certificate in the Trusted Root Certification Authorities or it will not work. Click Next and then Finish to add the Certificate.
    11. Now is a good time to confirm your client certificate was imported. Select Trusted Root Certificate Authorities again, then Certificates, and look for an entry with your chosen Common Name. Double-click this file, and choose the Details tab. You should see all the entries you made during the client certificate creation.
    12. After this you can close MMC, note that there is no need to save the console configuration when you exit.
      • At this point, if you use Firefox, you will need to tell it that the authorities in this system list can be trusted. Open Firefox now if you haven’t already.
        In the Firefox search bar, navigate to about:config and then search for security.enterprise_roots.enabled. Right click this property and toggle it to true.
    13. Close your browser(s) completely. They must not have any background extensions or processes, note that you may need to use Task Manager to end the browser task entirely before it will acknowledge the new client certificate.

Chrome

  • To add the certificate to Chrome’s trusted CA list if you exclusively use Chrome:
    1. Select ... in the top right corner to get to your Settings. Under advanced open the menu item to manage certificates.
    2. On the trusted root certification authorities tab select import.
    3. Set the explorer to show all file types, navigate to the client certificate ([myClientCertificate]-CC.pem file, not the [myCertificateAuthority]-CA.key file) and open the file.
    4. Make sure that it’s going into the Trusted Root Certification Authorities store.
    5. Restart your browser completely. They must not have any background extensions or processes, you may need to end the task entirely to get it to update.

Firefox

  • To add the certificate to Firefox’s trusted CA list if you exclusively use Firefox:
    1. Select the hamburger icon with three horizontal lines in the top right-hand corner of the browser and open the options menu.
    2. Switch to the privacy and security tab.
    3. Scroll to the bottom and select view certificates.
    4. Under the authorities tab choose import, navigate to the client certificate ([myClientCertificate]-CC.pem file, not the [myCertificateAuthority]-CA.key file) and open the file, make sure you allow this certificate to identify websites.
    5. Restart your browser completely. They must not have any background extensions or processes, you may need to end the task entirely to get it to update.

Mac OS

  • To add the certificate to the Mac OS trusted CA list so that you can have secure access from a Mac:
    1. Select the magnifying glass icon in the top right-hand corner to open Spotlight Search.
    2. Search for and launch “Keychain Access”.
    3. Click file, then import items to bring open a file browser.
    4. Click the Options button first and set the Destination Keychain: to be System, then open your client certificate ([myClientCertificate]-CC.pem file).
    5. Enter your MacOS system password to complete the import.
    6. Next, find your certificate in the system keychain tab.
    7. Right-click your client certificate and select get info.
    8. In the popup window select Trust > and set the option for ‘when using this certificate’ to Always Trust, close this popup and enter your iOS user password once again.
    9. Restart your browser completely. They must not have any background extensions or processes, you may need to force quit and restart the application to get it to update.
      • At this point, if you use Firefox, you will need to tell it that the authorities in this system list can be trusted. Open Firefox now if you haven’t already.
        In the Firefox search bar, navigate to about:config and then search for security.enterprise_roots.enabled. Right click this property and toggle it to true. You may need to restart your system for these changes to take effect.

Top

Next steps

Continue to Sign a Certificate Signing Request (CSR) for an individual EPIC (steps IV-VII) or go back to the procedure overview

Or go to EPIC Developer Overview Home