POST SSHCertificates/Request
Creates an SSH certificate to enhance security for client or host SSH keys. This endpoint allows a CA to issue an SSH Certificate with an expiration date. Then, your local CA signs the client's public key. SSH Protect manages the certificate and keys. You can also get an SSH Certificate via the vCert sshenroll command. For more information, see https://github.com/Venafi/vcert/releases.
Once you request a certificate, you can monitor the status by calling POST SSHCertificates/Retrieve. SSH certificates, which match machine requirements, grant access to that machine. So you no longer need to add and remove users to each system.
TIP If you want a TLS X.509 certificate, call POST Certificates/Request instead.
Prerequisites
-
Setup is required. For more information, see our Support article.
-
A master administrator or security team creates a SSH Certificate Issuance Template.
-
Get the trusted CA key from POST SSHCertificates/Template/Retrieve.
-
Distribute the CA key to OpenSSH hosts and clients. For more information, see
Requirements
-
Permissions:
-
The caller must have View permission and Create permission to the CA issuance template.
-
If the caller passes CADN and PolicyDN, the caller must have View permission and Create permission to the Policy folder for the SSH certificate.
-
- Token scope: SSH:Manage
Headers
-
Content type: Content-Type:application/json.
- Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.
Parameters
Many values originate from the SSH Certificate Issuance Template. To see defaults and options, call POST SSHCertificates/Template/Retrieve.
|
Name |
Description |
|---|---|
|
ProcessingTimeout |
(Optional) The maximum time the server will hold the connection that is waiting for certificate issuance before returning a Status of PendingIssue. Specify a value between 0 and 120 seconds (2 minutes). |
|
IncludeCertificateDetails |
(Optional) To include details about the issued certificate, such as Principals, specify true. Otherwise the default is false, and certificate details are excluded. |
|
IncludePrivateKeyData |
(Optional) Applies only to a service-generated keypair. To include the generated private key data, specify true. The default is true. |
|
PrivateKeyPassphrase |
(Optional) Applies only to a service-generated keypair. The passphrase that wraps the generated private key before it is returned in the response. |
|
CADN |
The Distinguished Name (DN) of the template to use for signing. Specify the correct template. For example: \\VED \\Certificate Authority\\SSH\\Templates\\myhost_template.
|
|
DestinationAddress |
(Optional) The destination host where the certificate will authenticate. Specify a Fully Qualified Domain name (FQDN) or IP address. |
| Extensions |
(Optional) Case sensitive. Valid only for client certificates. A set of key-value pairs that contain certificate extensions from the CA template. The template AllowedToRequestExtensions value must be true. Either specify common sshd extensions, custom extensions. or both. Possible values:
|
|
ForceCommand |
(Optional) Add a command to the certificate. The command runs after a successful login. Specify force or source keys and a value or regex expression. The template AllowedToRequestForceCommand must be true and the value must match AllowedForceCommandPatterns. For example: /usr/scripts/db_backup.sh. |
|
KeyId |
The identifier that matches the issuance template naming pattern in Allowed Certificate Identifier. For auditing and tracking purposes. |
|
ObjectName |
(Optional) The friendly name of the SSH Certificate object. Omit this parameter, if KeyId is the friendly name. If the Certificate object is already present in the Policy folder, the old certificate archives and the CA issues a new certificate. |
|
Origin |
(Optional) Additional information, such as the name and version of the calling application, that describes the source of this request. The default is Web SDK. |
|
PolicyDN |
(Optional) The DN of a Policy folder where the SSH Certificate object will be created. Omit this parameter, if you want the template CertificateDestinationDn value. |
|
Principals |
(Optional) An array of names for which the requested certificate will be valid. The value must match AllowedPrincipalsPatterns from the template. |
|
PublicKeyData |
Optional) A public key that has the OpenSSH format. Omit this parameter, if you want SSH Protect to generate a new key pair. The embedded key algorithm must match Key Algorithm from the template. Otherwise, Error Code 29 shows a non-compliant key algorithm. The Comment section at the end is optional. |
|
SourceAddresses |
(Optional) An array of one or more valid IP or Classless Inter-Domain Routing (CIDR) addresses that can use the certificate. Valid only when the template AllowedToRequestSourceAddresses is true. For example: ["192.168.1.1/24", "10.0.0.1"\]. |
|
ValidityPeriod |
(Optional) The certificate expiration time. Omit this value if you want the template ValidityPeriod value. When setting an expiration, follow your company's best practices. One of the following formats:
|
Returns
For a set of working examples, see Request an SSH certificate for host authentication.
IMPORTANT After this API call runs, make sure the client or hosts can use the certificate. Use the prerequisites to confirm the OpenSSH service is operating properly on every remote server.
|
Name |
Description |
|---|---|
| HTTP 200 |
For valid requests, this call returns HTTP 200 and the following data in the message body:
|
| HTTP 202 |
If the VED service is unavailable, this call returns HTTP 202 Accepted and the following data in the message body:
|
|
HTTP 400 |
For invalid parameters or rejected requests, this call returns HTTP 400 Bad Request and Response: The SSH SshWebResponse object. |
|
HTTP 404 |
For requests that contain invalid data, this call returns HTTP 404 Not Found and Response: The SSH SshWebResponse object. |
Example: Request an SSH Certificate; generate and sign the public key
IMPORTANT The correct endpoint name is SSHCertificates, not SSH/Certificates.
Request
POST https://tpp.venafi.example/vedsdk/SSHCertificates/Request
{
"PolicyDN":"\\VED\\Policy\\My Issued Certificates Folder",
"CADN":"\\VED\\Certificate Authority\\SSH\\Templates\\template_host",
"KeyId":"host_key_id",
"ObjectName":"host_key_id",
"Principals":[
"jhost129"
],
"DestinationAddress":"db.example.com",
"ValidityPeriod":"1w 2d 3h 4m 50s",
"SourceAddresses":[
"192.168.1.1/24",
"10.0.0.1"
],
"ForceCommand":"force",
"Extensions":{
"permit-pty":"",
"permit-port-forwarding":"",
"login@github.com":"alice@github.com"
},
"ProcessingTimeout":120,
"IncludeCertificateDetails":true,
"IncludePrivateKeyData":true,
"PrivateKeyPassphrase":"MyPassphrasethatmeetsCoRequirements"
}
Response
HTTP/1.1 200 OK
{
"DN":"\\VED\\Policy\\My Issued Certificates Folder\\host_key_id",
"Guid":"{5508941d-5922-406f-be73-2207af1853a0}",
"ProcessingDetails":{
"Status":"Pending Issue",
"StatusDescription":null
},
"Response":{
"ErrorMessage":"",
"Success":true
}
}