SSH Create Certificate with MTLS

Before you begin

Before attempting to creating certificates, the user has to ensure the following:

CERT+ license
Signing CA of the MTLS certificate should be present in AppViewX CERT+ module.
MTLS should be enabled in SSH > Advanced Settings > MTLS Auth Settings and issuer certificates should be configured for authentication.

Request Structure

Note: To call this API, you must provide a client certificate and private key configured for mTLS.


Endpoint:	`/ssh/cert/enroll`
Type:	`POST`
Sample URL:	`https://<CC_IP/CC_HostName>:<MTLS_GATEWAY_PORT>/ssh/cert/enroll?gwsource=external` To understand the elements of the sample URL, click here.
Headers:
Content-Type:	application/json

Table 1. Request Parameters
Name	Description
Content-Type `Header`	(Mandatory) Specifies the nature of the data in the payload. Type: String Constraints: The value of the param should be ‘application/json’.
gwsource `Query`	(Mandatory) Source from which the request is triggered. (E.g. external) Type: String
Payload `Body`	(Mandatory) Contains all the parameters to be sent in the request body for the post request. Type: Payload

Payload


Name	Description
publicKey	(Mandatory) Public key to create certificate. Type: String
validityValue	(Mandatory) Validity of the certificate. Type: Number
validityUnit	(Mandatory) Validity unit of the certificate. Type: String
certificateIdentity	(Mandatory) Identity of the certificate. Type: String
caName	(Mandatory) CA name used to sign the SSH certificate. Type: String
principals	(Mandatory) Principals of the certificate. Type: List
certType	(Mandatory) Type of the certificate. Type: String (User or Host)

Response Structure

200 OK returns string of type application/json with the following body params.

Table 2. Response Parameters
Name	Description
response	Contains the response message of the API. Type: Response
message	Success Type: String
appStatusCode	SSH-NB-200 Type: String
tags	More info in case of failure response.

Table 3. Response
Name	Description
fingerPrint	Finger print of the certificate. Type: String
certType	Type of the certificate. Type: String
rawFPString	Finger print of the certificate. Type: String
signingCA	Signing CA of the certificate. Type: String
keyId	Key ID of the certificate. Type: String
serialNumber	Serial number of the certificate. Type: String
rawCertType	Raw cert type of the certificate. Type: String
validFrom	Valid from value of the certificate. Type: String
validTo	Valid to value of the certificate. Type: String
validity	Validity of the certificate. Type: String
validityUnit	Validity unit of the certificate. Type: String
principals	Principals of the certificate. Type: String
extensions	Extensions of the certificate. Type: String
certContent	Content of the certificate. Type: String
caName	CA name of the certificate. Type: String
certStatus	Status of the certificate. Type: String

Status Codes

Table 4. Status Codes and Description
HTTP Status code	appStatusCode	Message and Possible remediation
200 OK	NA	Success
403 Forbidden	ERR-SSH-NB-459	Client certificate authentication failed. Issuer Certificate is not trusted.
	ERR-SSH-NB-460	Client certificate authentication failed. Issuer Certificate is expired.
	ERR-SSH-NB-462	No Issuer Certificates are configured for client certificate authentication.
	ERR-SSH-NB-463	Client certificate provided for authentication is expired.
	ERR-SSH-NB-464	MTLS authentication is not enabled.
401 Unauthorized	ERR-SSH-NB-458	Client certificate not found for authentication. Possible remediation: Ensure that valid certificate is provided for authentication
400 Bad Request	ERR-SSH_NB-268	Valid certificate already exists for the given Key Possible remediation: Valid certificate is available for the given public key. Please make sure to use different public key
	ERR-SSH_NB-267	Selected CA is not in Active status Possible remediation: Please make sure to provide active CA name
	ERR-SSH_NB-263	Selected CA cannot sign requested Cert Type Possible remediation: Please provide proper CA name
	ERR-SSH_NB-266	Validity start cannot exceed validity end Possible remediation: Make sure to provide start value less than end value
	ERR-SSH_NB-269	validityValue must be greater than zero Possible remediation: validityValue field should not be 0 or less than 0
	ERR-SSH_NB-264	Certificate validity can not exceed CA validity Possible remediation: Make sure to give the certificate validity less than CA validity
	ERR-SSH_NB-273	Certificate validity end can not be past date Possible remediation: Make sure to give the certificate validity in future
404 Not Found	ERR-SSH-NB-350	No CA found with given name or Id Possible remediation: Please make sure to provide the available CA name

Sample Request/Response

Use Case

To create a new certificate with MTLS using /ssh/cert/enroll API.

Note: To call this API, you must provide a client certificate and private key configured for mTLS.

Request URL

https://<CC_IP/CC_HostName>:<MTLS_GATEWAY_PORT>/ssh/cert/enroll?gwsource=external

Sample Request

{
      "publicKey": "dummy key",
      "validityValue" : 1,
      "validityUnit" : "months",
      "certificateIdentity":"admin",
      "caName": "testVendor.user.ca",
      "principals": ["admin"],
      "certType" : "User"
}

curl Sample Request

curl --cert <CERT-FILE-NAME>.crt --key <KEY-FILE-NAME>.key --location 'https://<CC_HostName>:<MTLS_GATEWAY_PORT>/ssh/cert/enroll?gwsource=External' --header 'Content-Type: application/json' --data-raw '{
      "publicKey": "public-key-content",
      "validityValue" : 1,
      "validityUnit" : "days",
      "certificateIdentity":"username/id",
      "caName": "signing-ca-name",
      "principals": ["username/id"],
      "certType" : "User"
}'

Sample Response


{
  "response": {
    "fingerPrint": "dWmpOIqQ4lj+JkNfF84d3xf+OFfToJ77Foaa4tmqXX4",
    "certType": "User",
    "rawFPString": "RSA-CERT SHA256:dWmpOIqQ4lj+JkNfF84d3xf+OFfToJ77Foaa4tmqXX4",
    "signingCA": "RSA SHA256:PUggWDhnfHBKZGdndqaMH9a0uBxWZtTycRWLGJvDWxk (using rsa-sha2-512)",
    "keyId": "appviewx",
    "serialNumber": "3615444997796232",
    "rawCertType": "[email protected] user certificate",
    "validFrom": 1765353748000,
    "validTo": 1765440148000,
    "validity": 23,
    "validityUnit": "hours",
    "principals": [
      "appviewx"
    ],
    "extensions": {
      "permitX11Forwarding": true,
      "permitAgentForwarding": true,
      "permitPortForwarding": true,
      "permitPty": true,
      "permitUserRc": true
    },
    "certContent": "[email protected] AAAAHHNzaC1yc2EtY2..........",
    "caName": "test-ssh-avx-ca",
    "certStatus": "Active",
},
  "message": "Success",
  "appStatusCode": "SSH-NB-200",
}

Reference

Understanding the sample URL:

CC_IP/CC_HostName: Replace with the actual Cloud Connector (CC) IP address, or CC hostname based on the specific configuration in AppViewX.
- CC IP: A unique identifier assigned to each device connected to a computer network that uses the Internet Protocol for communication
  The IP address will be included in the endpoint URL for an on-prem deployment.
- CC HostName: A human-readable label assigned to a device (host) on a network
  The hostname will be included in the endpoint URL for an on-prem deployment.
CC_MTLS_GATEWAY_PORT: AppViewX Cloud connector's mTLS gateway port
A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an SaaS Cloud Connector (CC) deployment.
Example: 30021
Endpoint: Endpoint of the API, for example: /ssh/host/create
gwsource: Source or origin of a gateway, for example: external.

What's Next

SSH Download CA