Push and Bind Certificate to ADC Profile

The API initiates a push of the certificate along with the private keys to the ADC devices and associates them to the device profiles.

Before You Begin

Ensure the following before attempting to push a certificate to a particular ADC device through AppViewX:
  • ADC devices must be configured in AppViewX.
  • The device should be in the Managed state.

Fetch Available Profiles API

Endpoint: /certificate/profiles
Type: GET
Sample URL: 
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/profiles?category=ADC&vendor=F5&deviceName=F5_device&gwsource=external

To understand the elements of the sample URL, click here.
Headers
Content-Type: application/json
Table 1. Request Details - Parameters
Name Description
sessionId

Header

 (Mandatory) Session Id received after login.

Type: String

Constraint: Required if username and password are not provided.
username

Header

 (Mandatory) AppViewX login username.

Type: String

Constraint: Required if sessionId is not provided.
password

Header

 (Mandatory) AppViewX login password.

Type: String

Constraint: Required if sessionId is not provided.
Content-Type

Header

 (Mandatory) Specifies the nature of the data in the payload.

Type: String

Constraint: Value of the parameter should be ‘application/json’
gwsource

Query

 (Mandatory) Source from which the request is triggered. (E.g. external)

Type: String
category

Query

 (Mandatory) Specifies the device category.

Type: String

Possible values: ADC, Server, and Firewall.
vendor

Query

 (Mandatory) Vendor for the chosen device. For example, F5 is a vendor for the ADC category.

Type: String

Possible values: F5, Citrix, AVI, A10, AmazonELB, NginxPlus, and HAProxy.
certificateUuid

Query

 (Mandatory) Resource id of the certificate.

Type: String

Constraints: This can be obtained from search API.
deviceName

Query

 (Mandatory) Name of the device as per AppViewX Device Inventory.

Type: String
inventory

Query

 (Mandatory) Name of AppViewX inventory where the certificate is present.

Type: String

Possible values: Server, Client, Code Signing, and Device.
Table 2. Response Parameters
Name Description
response Contains the following response attributes for the fetch profiles request: objects, totalRecords, obtainedRecords, and obtainedRecordRange.
objects

response

 List of available device profile Ids.

Type: List of String
totalRecords

response

 Total number of profiles fetched.

Type: Integer
obtainedRecords

response

 Total number of profiles fetched.

Type: Integer
obtainedRecordRange

response

 Range of record found.

Type: Object
message Success message of the action or failure description in case of error.

Type: String
appStatusCode Application specific status code for the response. It is a non-null value for a failure response.

Type: String
tags Additional information in case of failure response.
Response
{
 "response": {
 "objects": [
 "device_name",
 "device_name:@apm-default-serverssl:@Common",
 "device_name:@clientssl-insecure-compatible:@Common",
 "device_name:@clientssl-secure:@Common",
 "device_name:@clientssl:@Common",
 "device_name:@crypto-client-default-serverssl:@Common",
 "device_name:@crypto-server-default-clientssl:@Common",
 "device_name:@pcoip-default-serverssl:@Common",
 "device_name:@serverssl-insecure-compatible:@Common",
 "device_name:@serverssl:@Common",
 "device_name:@splitsession-default-clientssl:@Common",
 "device_name:@splitsession-default-serverssl:@Common",
 "device_name:@wom-default-clientssl:@Common",
 "device_name:@wom-default-serverssl:@Common"
 ],
 "totalRecords": 14,
 "obtainedRecords": 14,
 "obtainedRecordRange": {
 "start": 0,
 "end": 0
 }
 },
 "message": "14 record(s) found",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }

Request Structure for Push and Bind ASYNC API

Endpoint: /certificate/pushToDevice
Type: POST
Sample URL: https://<appviewx node ip>:<gateway port>/avxapi/certificate/pushToDevice?gwsource=external&gwkey=f000ca01
Headers
Content-Type: application/json
Table 3. Input Parameters
Name Description
sessionId

Header

 (Mandatory) Session Id received after login.

Type: String

Constraint: Required if username and password are not provided.
username

Header

 (Mandatory) AppViewX login username.

Type: String

Constraint: Required if sessionId is not provided.
password

Header

 (Mandatory) AppViewX login password.

Type: String

Constraint: Required if sessionId is not provided.
Content-Type

Header

 (Mandatory) Specifies the nature of the data in the payload.

Type: String

Constraint: Value of the parameter should be ‘application/json’
gwkey

Query

 (Mandatory) Tenant Key. This is needed only in case of multi-tenant installations and can disregarded for other types of installations.

Type: String
gwsource

Query

 (Mandatory) Source from which the request is triggered. (E.g. external)

Type: String
Payload Contains all the parameters to be sent in the request body for the post request.

Type: Payload

Payload

Table 4. Payload
Name Description
certificateId (Mandatory) Resource id of the certificate.

Type: String

Constraint: Optional if the Uuid of the certificate is present.
certificateUuid (Optional) Certificate UUid

Type: String

Constraint: Mandatory only if certificateId is not present.
selectedProfiles (Mandatory) ADC device profile id.

Type: String

Constraint: These can be obtained from Fetch Available Profiles API
  • If a Profile connector is specified, then the certificate will be pushed and bound to the profile.
  • If a Default connector specified, then the certificate will be only pushed.
certificateDetails (Mandatory) Certificate details for the server devices to be pushed.
Type: Any of the following server devices:
Table 5. Certificate details for F5
Name Description
certificateType (Mandatory) Type of the certificate

Type: String

Possible Certificate types: PEM-.crt
certificateFileName (Mandatory) A user defined file name for pushing the certificate into an F5 device.

Type: String

Constraints: The certificate file name should not begin or end with special characters except -, ., _. The certificate file name should also be different from both the root and intermediate certificate file names.
privateKeyFileName (Mandatory) A user defined file name for pushing the keys into an F5 device.

Type: String

Constraints: The key file name should not begin or end with special characters except -, ., _. The key file name should be same as the certificateFileName.
pushRootAndIntermediateCertificates (Optional) Determines whether both Root and Intermediate certificate needs to be pushed.

Type: Boolean
rootCertificateFileName (Optional) A user defined file name for pushing the intermediate and root certificates into in a F5 device. It is mandatory if pushRootAndIntermediateCertificates = true.

Type: String

Constraints: Intermediate file or bundle name should not begin and end with special characters except -, _, .. It should not be the same as the certificate file name.
Request Payload
{
"certificateId": "665efb67585b6b7259766f1b",
"selectedProfiles": ["F5:@shape-api-ssl:@Common"],
"certificateDetails": {
"certificateFileName": "F5testCert1.crt",
"certificateType": "PEM-.crt",
"privateKeyFileName": "F5testCert1.key",
"pushRootAndIntermediateCertificates": true,
"rootCertificateFileName": "test123_root.crt"
}
}
Response
 {
 "response": [
 {
 "requestId": "156",
 "connectorId": "device_name:@default:@clentssl:@9eb94a53963d1ae326dbf4cda6077f55baa8476e"
 }
 ],
 "message": "1 connector(s) saved and push opertaion has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }
Table 6. Certificate details for Citrix
Name Description
certificateType (Mandatory) Type of the certificate

Type: String

Possible Certificate types: PEM-.crt, PEM-.cer, PEM-.pem, DER-.der, and DER-.cer
certificateFileName (Mandatory) A user defined file name for pushing the certificate into the Citrix device.

Type: String

Constraints: The certificate file name should not begin or end with special characters except -, ., _. The certificate file name should also be different from both the root and intermediate certificate file names.
privateKeyFileName (Mandatory) A user defined file name for pushing the keys into the Citrix device.

Type: String

Constraints: The key file name should not begin or end with special characters except -, ., _. The key file name should be same as the certificateFileName.
pushRootAndIntermediateCertificates (Optional) Determines whether both Root and Intermediate certificate needs to be pushed.

Type: Boolean
intermediateCertificateFileName (Optional) A user-defined file name for pushing the intermediate certificate into the Citrix device. It is mandatory if pushRootAndIntermediateCertificates = true.

Type: String

Constraints: Intermediate file or bundle name should not begin and end with special characters except -, _, .. It should not be the same as the certificate file name.
rootCertificateFileName (Optional) A user-defined file name for pushing the root certificate into the Citrix device. It is mandatory if pushRootAndIntermediateCertificates = true.

Type: String

Constraints: Root file name should not begin and end with special characters except -, _, .. It should not be the same as the certificate file name.
Request Payload
{
"certificateUuid": "9eb94a53963d1ae326dbf4cda6077f55baa8476e",
 "selectedProfiles": [
 "device_name:@default:@sslvs"
 ],
 "certificateDetails": {
 "certificateFileName": "test123.crt",
 "certificateKeyPairName": "test123",
 "certificateType": "PEM-.crt",
 "intermediateCertificateFileName": [
 "test123_inter.crt"
 ],
 "privateKeyFileName": "test123.key",
 "pushRootAndIntermediateCertificates": true,
 "rootCertificateFileName": "test123_root.crt",
 "sniCert": "false",
 "sniStatus": "false"
 }
 }
Response
{
"response": [
 {
 "requestId": "156",
 "connectorId": "device_name:@default:@clentssl:@9eb94a53963d1ae326dbf4cda6077f55baa8476e"
 }
 ],
 "message": "1 connector(s) saved and push opertaion has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }
Table 7. Certificate details for AVI
Name Mandatory
certificateType (Mandatory) Type of the certificate

Type: String

Possible Certificate types: PEM-.pem
certificateFileName (Mandatory) A user defined file name for pushing the certificate into the AVI device.

Type: String

Constraints: The certificate file name should not begin or end with special characters except -, ., _. The certificate file name should also be different from both the root and intermediate certificate file names.
privateKeyFileName (Mandatory) A user defined file name for pushing the keys into the AVI device.

Type: String

Constraints: The key file name should not begin or end with special characters except -, ., _. The key file name should be same as the certificateFileName.
pushRootAndIntermediateCertificates (Optional) Determines whether both Root and Intermediate certificate needs to be pushed.

Type: Boolean
intermediateCertificateFileNames (Optional) A user-defined file name for pushing the intermediate certificate into the AVI device. It is mandatory if pushRootAndIntermediateCertificates = true.

Type: String

Constraints: Intermediate file or bundle name should not begin and end with special characters except -, _, .. It should not be the same as the certificate file name.
rootCertificateFileName (Optional) A user-defined file name for pushing the root certificate into the AVI device. It is mandatory if pushRootAndIntermediateCertificates = true.

Type: String

Constraints: Root file name should not begin and end with special characters except -, _, .. It should not be the same as the certificate file name.
Request Payload
{
 "certificateUuid":"9eb94a53963d1ae326dbf4cda6077f55baa8476e",
 "selectedProfiles":[
 "device_name:@serverssl-insecure-compatible:@Common"
 ],
 "certificateDetails":{
 “certificateType”:”PEM-.pem”,
 "certificateFileName":"certificate_push.pem",
 "privateKeyFileName":"certificate_push.key",
 "pushRootAndIntermediateCertificates": true,
 “intermediateCertificateFileNames”:[”test_cert_inter.crt”],
 "rootCertificateFileName": "test_cert_ca.crt"
 }
 }
Response
{
"response": [
 {
 "requestId": "156",
 "connectorId": "device_name:@default:@clentssl:@9eb94a53963d1ae326dbf4cda6077f55baa8476e"
 }
 ],
 "message": "1 connector(s) saved and push opertaion has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }
Table 8. Certificate details for A10
Name Mandatory
certificateType (Mandatory) Type of the certificate

Type: String

Possible Certificate types: PEM-.pem, PEM-.crt, PEM-.cer, DER-.der, DER-.cer, PKCS#7-.p7b, PKCS#7-.p7c, PKCS#7-.p12, and PKCS#7-.pfx
certificateFileName (Mandatory) A user defined file name for pushing the certificate into the A10 device.

Type: String

Constraints: The certificate file name should not begin or end with special characters except -, ., _. The certificate file name should also be different from both the root and intermediate certificate file names.
privateKeyFileName (Mandatory) A user defined file name for pushing the keys into the A10 device.

Type: String

Constraints: The key file name should not begin or end with special characters except -, ., _. The key file name should be same as the certificateFileName.
pfxPassword (Optional) Password for the pfx and pkcs12 file type. It is mandatory only if the certificate file type is .pfx or .pkcs12.

Type: Boolean

Constraints: The password should be Base64 encoded.
pushRootAndIntermediateCertificates (Optional) Determines whether both Root and Intermediate certificate needs to be pushed.

Type: Boolean
intermediateCertificateFileNames (Optional) A user-defined file name for pushing the intermediate certificate into the A10 device. It is mandatory if pushRootAndIntermediateCertificates = true.

Type: String

Constraints: Intermediate file or bundle name should not begin and end with special characters except -, _, .. It should not be the same as the certificate file name.
Request payload for non pfx and p12 cert types
{
 "certificateUuid":"9eb94a53963d1ae326dbf4cda6077f55baa8476e",
 "selectedProfiles":[
 "device_name:@serverssl-insecure-compatible:@Common"
 ],
 "certificateDetails":{
 “certificateType”:”PEM-.crt”,
 "certificateFileName":"certificate_push.crt",
 "privateKeyFileName":"certificate_push.key",
 "pushRootAndIntermediateCertificates": true,
 "intermediateCertificateFileNames":[ "test_cert_ca.crt"]
 }
 }
Request payload for pfx and p12 cert types
 {
"certificateUuid":"9eb94a53963d1ae326dbf4cda6077f55baa8476e",
 "selectedProfiles":[
 "device_name:@serverssl-insecure-compatible:@Common"
 ],
 "certificateDetails":{
 “certificateType”:”PKCS-.pfx”,
 "certificateFileName":"certificate_push.pfx",
 "pushRootAndIntermediateCertificates": true,
 "intermediateCertificateFileNames":[ "test_cert_ca.crt"],
 “pfxPassword”:”cGFzc3dvcmQ=”
 }
 }
Response
 {
 "response": [
 {
 "requestId": "156",
 "connectorId": "device_name:@default:@clentssl:@9eb94a53963d1ae326dbf4cda6077f55baa8476e"
 }
 ],
 "message": "1 connector(s) saved and push opertaion has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }
Table 9. Certificate details for AmazonELB
Name Mandatory
certificateType (Mandatory) Type of the certificate

Type: String

Possible Certificate types: PEM-.pem
certificateLocation (Mandatory) Location of the certificate. Values are ACM or IAM.

Type: String
certCAReferenceId (Optional) Reference ID to input the certificate location. It is mandatory if certificateLocation is ACM.

Type: String

Constraints: The special characters allowed are ('=', '/', ',', '.', '@', '-').
certificateFileName (Optional) A user defined file name for pushing the certificate into the AmazonELB device. It is mandatory if certificateLocation is IAM.

Type: String

Constraints: The certificate file name should not begin or end with special characters except -, ., _. The certificate file name should also be different from both the CA file name and intermediate certificate file name.
pushRootAndIntermediateCertificates (Optional) Determines whether both Root and Intermediate certificate needs to be pushed.

Type: Boolean
Request payload if certificateLocation is ACM
{
"certificateUuid":"9eb94a53963d1ae326dbf4cda6077f55baa8476e",
 "selectedProfiles":[
 "device_name:@serverssl-insecure-compatible:@Common"
 ],
 "certificateDetails":{
 “certCAReferenceId”: "arn:aws:iam::2313:amazonELB"
 “certificateLocation”: "ACM"
 “certificateType”: "PEM-.pem"
 “pushRootAndIntermediateCertificates”: true
 }
Request payload if certificateLocation is IAM
{
 "certificateUuid":"9eb94a53963d1ae326dbf4cda6077f55baa8476e",
 "selectedProfiles":[
 "device_name:@serverssl-insecure-compatible:@Common"
 ],
 "certificateDetails":{
 “certificateFileName: "sample.pem",
 “certificateLocation”: "IAM",
 “certificateType”: "PEM-.pem",
 “pushRootAndIntermediateCertificates”: true
 }
Response
{
"response": [
 {
 "requestId": "156",
 "connectorId": "device_name:@default:@clentssl:@9eb94a53963d1ae326dbf4cda6077f55baa8476e"
 }
 ],
 "message": "1 connector(s) saved and push opertaion has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }
Table 10. Certificate details for NginxPlus
Name Mandatory
certificateType (Mandatory) Type of the certificate

Type: String

Possible Certificate types: PEM-.pem, PEM-.crt, and PEM-.cer
certificateLocation (Mandatory) A user defined file name for pushing the certificate into the NginxPlus device.

Type: String

Constraints: The certificate file name should not begin and end with special characters except -, ., _. It should not be the same as CA file name and intermediate file name.
keyLocation (Mandatory) A user defined file for pushing the key into the NginxPlus device.

Type: String

Constraints: The key file name should not begin and end with special characters except -, ., _. Key file name should be same as certificateFileName.
privateKeyInDevice (Optional) Determines whether private key needs to be pushed into the device.

Type: Boolean
Request Payload
 {
 "certificateUuid":"9eb94a53963d1ae326dbf4cda6077f55baa8476e",
 "selectedProfiles":[
 "device_name:@serverssl-insecure-compatible:@Common"
 ],
 "certificateDetails":{
 “certificateType”:”PEM-.pem”,
 "certificateLocation":"/home/appviewx",
 "keyLocation":"/home/appviewx",
 "privateKeyInDevice": true 
 }
 }
Response
 {
 "response": [
 {
 "requestId": "156",
 "connectorId": "device_name:@default:@clentssl:@9eb94a53963d1ae326dbf4cda6077f55baa8476e"
 }
 ],
 "message": "1 connector(s) saved and push opertaion has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }
Table 11. Certificate details for HAProxy
Name Mandatory
certificateType (Mandatory) Type of the certificate

Type: String

Possible Certificate types: PEM-.pem
certificateFileName (Mandatory) A user defined file name for pushing the certificate into the HAProxy device.

Type: String

Constraints: The certificate file name should not begin or end with special characters except -, ., _. The certificate file name should also be different from both the root and intermediate certificate file names.
privateKeyInDevice (Optional) Determines whether private key needs to be pushed into the device.

Type: Boolean
privateKeyLocation (Mandatory) A user defined file name for pushing the keys into the HAProxy device. It is mandatory if privateKeyInDevice is true.

Type: String

Constraints: The certificate file name should not begin or end with special characters except -, ., _. The certificate file name should also be different from both the root and intermediate certificate file names.
Request Payload
{
 "certificateUuid":"9eb94a53963d1ae326dbf4cda6077f55baa8476e",
 "selectedProfiles":[
 "device_name:@serverssl-insecure-compatible:@Common"
 ],
 "certificateDetails":{
 “certificateType”:”PEM-.pem”,
 "certificateFileName":"/opt/haproxy/certificate_push.pem",
 "privateKeyLocation": true,
 "privateKeyLocation": "/opt/haproxy/test_cert.key"
 }
 }
Response
{
 "response": [
 {
 "requestId": "156",
 "connectorId": "device_name:@default:@clentssl:@9eb94a53963d1ae326dbf4cda6077f55baa8476e"
 }
 ],
 "message": "1 connector(s) saved and push opertaion has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }

Response Structure for Push and Bind ASYNC API

Note: The response details/parameters are common for all vendor devices.
Table 12. Parameters
Name Description
response Contains Request id and connector id.

Type: Object
requestId

response

 Request Id for push action for the application connector.

Type: String
connectorId

response

 Application connector Id.

Type: String
message Success or failure messages

Type: String
appStatusCode Application specific status code for the response.

Type: String
tags More info in case of failure response

Type: Object
headers Details of the response headers if any

Type: Object

Sample Response (common for all vendors)

{
 "response": [
 {
 "requestId": "156",
 "connectorId": "device_name:@default:@clentssl:@9eb94a53963d1ae326dbf4cda6077f55baa8476e"
 }
 ],
 "message": "1 connector(s) saved and push opertaion has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }

References

Understanding the sample URL
  • IP/HostName/TenantName: Replace with the actual IP address, hostname, or tenant name based on the specific configuration in AppViewX.
    • 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.

    • 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.

    • TenantName: An identifier label for a tenant given to indicate which tenant's data the API request will access/modify

      The tenant name will be included in the endpoint URL for a SaaS deployment.

  • GWPORT: AppViewX gateway port

    A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.

    Example: 31443

  • avxapi: Path parameter value (static) that is part of the endpoint's URL
  • Endpoint: Endpoint of the API, for example: execute-hook
  • gwsource: Source or origin of a gateway, for example: external.