Trusting the Manager Certificate

The Manager creates its own certificate authority (CA) when it first starts, and uses it to issue the certificate for the console. Browsers do not know this CA, so they warn about the connection until you add the CA to the trusted root certificates on each workstation that operators use. Agents need no action: they are installed with the CA fingerprint and trust it from the start.

Trusting the CA is a one-time task for each workstation. The CA is valid for 20 years. The Manager reissues its own server certificate automatically, and the new certificate is trusted because it comes from the same CA. You trust the CA again only if the Manager is re-keyed. See Re-Keying the Manager CA.

For background, see Certificates and Trust.

Before you begin

Download the CA certificate

Get the CA certificate in either of these ways.

From the Manager's trust endpoint

The Manager publishes its CA certificate at https://<manager>:5210/api/trust. The endpoint needs no sign-in and returns the fingerprint (fingerprint) and the CA certificate in PEM format (caCertificatePem). For example, in PowerShell 7:

$trust = Invoke-RestMethod -Uri https://<manager>:5210/api/trust -SkipCertificateCheck
Set-Content -Path .\manager-ca.pem -Value $trust.caCertificatePem
certutil -decode .\manager-ca.pem .\manager-ca.cer

The certificate check is skipped here because the CA is not trusted yet. That is why you must verify the fingerprint before you import the certificate.

From the browser

Open the console, view the site's certificate from the address bar, select the top certificate in the certification path (the Manager's CA), and export it to a file.

Verify the fingerprint

Before you import the certificate, confirm that it is your Manager's CA. Compare its SHA-256 hash with the fingerprint you took from the Manager's event log on the Manager machine itself. A certificate fetched over the network could come from an impostor, so do not compare it with a value fetched over the same connection.

To verify the fingerprint:

  1. Calculate the SHA-256 hash of the certificate file. The file must be in DER format, like the .cer file that certutil -decode writes:

    certutil -hashfile .\manager-ca.cer SHA256

  2. Compare the result with the fingerprint from the event log, ignoring letter case and the hyphens between the groups of four digits.

    If the two values differ, do not import the certificate. You are not connected to your Manager.

Import the certificate

Import the CA into the Trusted Root Certification Authorities store. Choose the store that fits how many workstations need it.

For your own account

Run this in a command prompt as yourself. No administrator rights are needed; Windows asks you to confirm the installation.

certutil -user -addstore Root .\manager-ca.cer

For every user of a workstation

Run this in an elevated command prompt:

certutil -addstore Root .\manager-ca.cer

For many workstations

Distribute the certificate with Group Policy or your device management tool. In a Group Policy Object, import the certificate under Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies > Trusted Root Certification Authorities.

Note: Keep a way to reach the console that does not depend on Group Policy. In a directory outage, workstations that rely on a policy for the CA still have it, but a newly built workstation does not. The per-user certutil command works on any machine.

Microsoft Edge and Google Chrome use the Windows certificate store. Firefox uses its own store by default; import the certificate in Firefox's certificate settings under Authorities, or configure Firefox to trust the Windows root store.

After the import, restart the browser and open the console again. The warning no longer appears. The Manager's certificate covers its host name, its fully qualified name, localhost, and all its IP addresses, so you can connect by any of them.

Trust the Manager in the cdr command-line tool

The cdr command-line tool keeps its own list of trusted Managers for each Windows user, separate from the Windows certificate store. The first time it connects to a Manager, it shows the CA fingerprint and asks you to confirm it:

cdr has not connected to the manager at https://localhost:5210/ before.
Its CA fingerprint is:
  3F2A-91C0-...
Compare it with the fingerprint on the manager's console, or in its event log. Trust it only if they match: a different value means you are not talking to your manager.
Trust this manager and remember it for this address? [y/n] (n):

Compare the value with the fingerprint from the event log, and answer y only if they match. cdr remembers the fingerprint for that address and checks it on every later connection.

  • To trust a Manager without running another command, run cdr trust pin --manager https://<manager>:5210.
  • In a script, where nobody can answer the prompt, give the fingerprint with --manager-ca <fingerprint> or the CYGNADR_MANAGER_CA environment variable.
  • To see the Managers you trust, run cdr trust list. To forget one, for example after it is re-keyed, run cdr trust remove --manager https://<manager>:5210.

For details, see Agent and Trust Commands.