Work with the Agent’s Certificates

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Alation uses signed certificates to encrypt the communication between your Alation Cloud instance and the Agent. Alation uses two signed certificates—one for the Agent and one root certificate. These certificates will automatically expire after one year.

You’re in full control of these certificates. You can always view the certificates in Alation. You can revoke them at any time to stop communication between your Alation Cloud instance and the Agent. You can also renew certificates at any time, whether they are current, expired, or revoked.

  1. In Alation, click on the Settings gear icon in the top right corner. This opens the Admin Settings page.

    ../../_images/TopNavigationBar_Gear.png
  2. Under the Server Admin section, click Manage Connectors.

    ../../_images/AdminSettings_ManageConnectors.png
  3. Click the Agents tab. The Agents Dashboard appears.

View the Certificates’ Expiration Date

To view the expiration date of the Agent’s certificates:

  1. Navigate to the Agents Dashboard.

  2. In the Certificate Expiration column, you can see the date on which the certificates will expire. If there is no date, then there are no valid certificates associated with that Agent.

View the Certificates

To view an Agent’s certificates:

  1. Navigate to the Agents Dashboard.

  2. Click on the name of the Agent. The Agent’s dedicated page opens.

  3. Click the Agent Options button, then select View Certificates.

    ../../_images/Agent_Options_ViewCertificates.png
  4. A dialog will appear that shows the certificates.

    Note

    If the certificate has been revoked, you’ll see an error message.

    ../../_images/Agent_Options_ViewCertificatesError.png

    See Renew the Certificates to reestablish the connection.

  5. Click the Close button to exit the dialog.

Revoke the Certificates

You can revoke the Agent’s certificates at any time. This stops all communication between the Agent and your Alation Cloud instance.

To revoke an Agent’s certificates:

  1. Navigate to the Agents Dashboard.

  2. Click on the name of the Agent. The Agent’s dedicated page opens.

  3. Click the Agent Options button, then select Revoke Certificate.

    ../../_images/Agent_Options_RevokeCertificate.png
  4. A confirmation dialog appears. Click the Confirm button to revoke the certificate.

    Important

    It may take up to an hour before the certificate is fully revoked, per the Online Certificate Status Protocol (RFC 5019) Section 6. Your Agent may appear to have a Connected status until that time.

Renew the Certificates

Agent certificates automatically expire after one year. You’ll need to renew them on a yearly basis in order to keep using the Agent. You may also need to renew certificates that you have previously revoked.

To renew an Agent’s certificates:

  1. Navigate to the Agents Dashboard.

  2. Click on the name of the Agent. The Agent’s dedicated page opens.

  3. Click the Agent Options button, then select Renew Certificate.

    ../../_images/Agent_Options_RenewCertificate.png
  4. On the Generate Certificate Signing Request (CSR) screen, copy the provided command and run it on the Agent’s host machine.

    sudo kratos certs gen
    

    Since this Agent has already been connected to your Alation Cloud instance in the past, you will get a warning that a key has already been created.

    Warning! A key for this agent appears to have already been generated
    at "/etc/hydra/agent/security/proxy_key.pem". Generating a new key pair
    will destroy the existing one.
    Continue? [Y|n]
    

    Enter Y to continue.

    The command will generate a certificate signing request. Example output:

    -----BEGIN CERTIFICATE REQUEST-----
    <your certificate signing request>
    -----END CERTIFICATE REQUEST-----
    
  5. Copy the certificate signing request from the Agent machine, including the dashes.

  6. In Alation, paste the certificate signing request into the provided box under Certificate Signing Request Output. Then click the Next button.

    ../../_images/Agent_AddNewAgent_Certificate_Paste.png
  7. Alation will generate two signed certificates—one for the Agent and one root certificate. Copy the provided certificate installation command.

    ../../_images/Agent_AddNewAgent_Certificate_CopyText.png
  8. On the Agent’s host machine, paste the copied certificate command and run it. This installs the certificate.

  9. Restart the Agent by copying the provided command and running it on the Agent’s host machine.

    sudo systemctl restart hydra
    
  10. When the Agent has finished restarting, click the Finish button in Alation. Check that your Agent has a status of Connected in the Agent Dashboard. If it doesn’t, check the Troubleshooting page.

Note

The certificates will automatically expire after one year.