Request an SSH certificate for client authentication

Problem

To request an SSH clients certificate, your call to POST SSHCertificates/Request. can use an issuance template that is configured for issuance of clent certificates.

Solution

In this case, you can use short-lived client SSH certificates instead of traditional SSH keypairs. This example shows you how to get an SSH certificate for client authentication with a server-generated private key.

In this example, we request an SSH client certificate from issuance template named “Production - DMZ - Web Admins”. We want a principal, "alice", in the certificate and validity of 2 hours.

We don’t want to create our own private key, so the server can generate one for us, and return it along with our certificate.

Before you start

You need:

• The location and name of the SSH CA Template. In Venafi, an object location and name is also known as the Distinguished Name (DN). To get the value from the Policy tree, switch to the Certificate Authority Templates folder. For example, \\VED\Certificate Authority\\Templates\\template_client.

  

• A template for client certificates. Your request follows template requirements or restrictions. The certificate issuance template is configured to issue client certificates. For more information, see Working with issuance templates

Time Estimate

About 30 mins

To get an SSH certificate for client authentication

1. Reuse or create a bearer token that includes the scope ssh:manage. The bearer token grants your client access to Trust Protection Platform.

   To get a bearer token, see Getting a token. For each subsequent API call, be sure to include the token in the request header.

2. Call POST SSHCertificates/Request. For example:

   POST https://tpp.venafi.example/vedsdk/SSHCertificates/Request
   Authorization:Bearer 4MyGeneratedBearerTknz==
   {
     "CADN":"\\VED\\Certificate Authority\\SSH\\Templates\\template_client",
     "KeyId":"MySSHCertificateforClient",
     "Principals":[
        "web.prod.venafi.com"
     ],
      "ValidityPeriod":"2h"
   }

3. (Optional) Use the DN from the response to check the SSH certificate status. Call POST SSHCertificates/Retrieve. For example:

   POST https://tpp.venafi.example/vedsdk/SSHCertificates/retrieve
   Authorization:Bearer 4MyGeneratedBearerTknz==
   
      "DN": "\\VED\\Policy\\My Issued Certificates Folder\\MySSHCertificateforClient",
      "IncludeCertificateDetails": false,
      "PrivateKeyPassphrase":"123456",
      "IncludePrivateKeyData": true
   }

4. In the response, you can get the certificate CertificateData and the private key PrivateKeyData. For example:

   {
      "CADN":"\\VED\\Certificate Authority\\SSH\\Templates\\template_client",
      "CAGuid":"{1f041052-e27f-4e62-b32d-5f25556f3ccf}",
      "CertificateData":"ssh-rsa-cert-v01@openssh.com ...MySSHCertificateforClient",
      "DN":"\\VED\\Policy\\My Issued Certificates Folder\\MySSHCertificateforClient",
      "Guid":"{cce31bb5-3dbc-481b-982b-0fac7c7bd2b8}",
      "PrivateKeyData":"-----BEGIN OPENSSH PRIVATE KEY----- ...\n-----END OPENSSH PRIVATE KEY-----\n",
      "ProcessingDetails":{
         "Status":"Issued",
         "StatusDescription":""
      },
      "PublicKeyData":"ssh-rsa...= MySSHCertificateforClient",
      "Response":{
         "ErrorMessage":"",
         "Success":true
      }
   }

5. Save the certificate and private key as files. For example, id_rsa and id_rsa-cert.pub. You can use the certificate without modification. But the private key contains “\n" which must be replaced by newlines. This can be done by using the following command: root@web:~# sed -i 's/\\r\\n/\n/g' id_rsa

6. Now we can use the requested certificate for authentication to remote servers. For example: root@web:~# ssh -i id_rsa -i id_rsa-cert.pub alice@web.prod.venafi.com.