Push and Bind Certificate to ADC Devices
Before you begin
- ADC devices must be configured in AppViewX.
- The device should be in the Managed state.
- A valid certificate should be used to push the certificate.
- Profiles or virtual servers should be available. This can be fetched using Fetch Available Profiles API (refer section below).
Fetch available profiles API
| Endpoint: | /certificate/profiles |
| Type: | GET |
| Sample URL: |
To understand the elements of the sample URL, click here. |
| Headers | |
| Content-Type: | application/json |
| Name | Description |
|---|---|
| sessionId
|
(Mandatory) Session Id received after login. Type: String Constraint: Required if username and password are not provided. |
| username
|
(Mandatory) AppViewX login username. Type: String Constraint: Required if sessionId is not provided. |
| password
|
(Mandatory) AppViewX login password. Type: String Constraint: Required if sessionId is not provided. |
| Content-Type
|
(Mandatory) Specifies the nature of the data in the
payload. Type: String Constraint: Value of the parameter should be ‘application/json’ |
| gwsource
|
(Mandatory) Source from which the request is triggered. (E.g.
external) Type: String |
| category
|
(Mandatory) Specifies the device category. Type: String Possible values: ADC, Server, and Firewall. |
| vendor
|
(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
|
(Mandatory) Resource id of the certificate. Type: String Constraints: This can be obtained from search API. |
| deviceName
|
(Mandatory) Name of the device as per AppViewX Device
Inventory. Type: String |
| inventory
|
(Mandatory) Name of AppViewX inventory where the certificate is
present. Type: String Possible values: Server, Client, Code Signing, and Device. |
| Name | Description |
|---|---|
| response | Contains the following response attributes for the fetch profiles
request: objects, totalRecords, obtainedRecords, and
obtainedRecordRange. Type: List of Objects |
| objects
|
List of available device profile Ids. Type: List of String |
| totalRecords
|
Total number of profiles fetched. Type: Integer |
| obtainedRecords
|
Total number of profiles fetched. Type: Integer |
| obtainedRecordRange
|
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 |
|
Request Structure for Push and Bind SYNC API
| Endpoint: | /certificate/profiles/push |
| Type: | POST |
| Sample URL: | https://<appviewx node id>:<gateway port>/avxapi/certificate/profiles/push?gwkey=f000ca01&gwsource=external&ttl=120 |
| Headers | |
| Content-Type: | application/json |
| Name | Description |
|---|---|
| sessionId
|
(Mandatory) Session Id received after login. Type: String Constraint: Required if username and password are not provided. |
| username
|
(Mandatory) AppViewX login username. Type: String Constraint: Required if sessionId is not provided. |
| password
|
(Mandatory) AppViewX login password. Type: String Constraint: Required if sessionId is not provided. |
| Content-Type
|
(Mandatory) Specifies the nature of the data in the
payload. Type: String Constraint: Value of the parameter should be ‘application/json’ |
| gwkey
|
(Mandatory) Tenant Key. This is needed only in case of
multi-tenant installations and can disregarded for other types of
installations. Type: String |
| gwsource
|
(Mandatory) Source from which the request is triggered. (E.g.
external) Type: String |
| ttl
|
(Mandatry) The time to live (ttl) is a query parameter. If
the total time taken surpasses this value, the response will
indicate that the request is still in progress. On the other hand,
if the operation completes successfully within the TTL, the response
will indicate success. Type: Integer |
| Payload | Contains all the parameters to be sent in the request body for
the post request. Type: Payload |
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: List of String Constraint: These can be obtained from Fetch Available Profiles
API.
|
| certificateDetails | (Mandatory) Certificate details for the server devices to be pushed. |
| 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 CA file name and intermediate certificate file name. |
| 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 |
|
| 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 |
| 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. |
| sniCert | (Optional) Enables the SNI push for certificate. Type: Boolean |
| sniStatus | (Optional) Enables SNI in the virtual server. Type: Boolean |
Request
Payload |
|
| 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 |
|
| 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 |
|
Request payload for pfx and p12 cert
types |
|
| 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 |
|
Request payload if
certificateLocation is
IAM |
|
| 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 |
|
| 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 |
|
Response for Push and Bind SYNC API
| Name | Description |
|---|---|
| response | Contains the parameters certificate, deviceProfiles,
applicationConnectors, success and messages. Type: Object |
| certificate
|
Details about the selected certificate which was used to push
into the ADC devices Type: List <Object> |
| deviceProfiles
|
Details about the device profiles to which the certificate is
bound. Type: List <Object> |
| applicationConnectors
|
Details about the application connectors where the push operation
occurred. Type: List <Object> |
| success
|
Determines whether the push operation succeeded. Type: Boolean |
| messages
|
Details of the push operation. Type: List <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 Request/Response
{
"applicationConnectorIds": [ "xx.xxx:@clientssl-insecure-compatible:@Common:@c46ec8a04da701721159ce0c3cf772367ade58cb" ]
} Response Details
{
"response": {
"certificate": <Selected Certificate>,
"deviceProfiles": <Selected Profiles>,
"applicationConnectors": <Application connectors with its work order status>,
"success": <Status of the operation>,
"messages": <Response message for the push action performed>
},
"message": null,
"appStatusCode": <Error Code>,
"tags": {},
"headers": null
}
Sample Response (common for all vendors)
{
"response": {
"certificate": {
"commonName": "appviewx_test",
"serialNumber": "C4:DA:38:94:6B:A7:08:92:FB:A5:31:89:60:C6:D3:E7",
"issuerCommonName": "AppViewX Intermediate CA",
"status": "Managed",
"avxStatus": null,
"associatedObjects": [
"device_name::serverssl-insecure-compatible:Common:server-ssl"
],
"discoverySources": [
"device_name"
],
"subjectOrganization": "",
"subjectOrganizationUnit": "",
"subjectLocality": "",
"subjectState": "",
"subjectCountry": "",
"issuerOrganization": "AppViewX Inc",
"issuerOrganizationUnit": "",
"issuerLocality": "Seattle",
"issuerState": "Washington",
"issuerCountry": "US",
"version": "3",
"validFrom": 1617025560000,
"validTo": 1648561560000,
"validFor": "364 day(s) 23 hr(s) 57 min(s)",
"keyAlgorithmAndSize": "RSA 1024",
"signatureAlgorithm": "SHA160withRSA",
"signatureHashAlgorithm": "SHA160",
"keyUsage": "DigitalSignature, KeyEncipherment",
"extendedKeyUsage": "Server Authentication(1.3.6.1.5.5.7.3.1) Client Authentication(1.3.6.1.5.5.7.3.2) ",
"basicConstraints": "Subject Type=End entity, Path Length=none",
"group": "Default",
"subjectAlternativeNames": [
"DNS : appviewx_test"
],
"complianceStatus": "Compliant",
"applications": [],
"expiryStatus": "Valid",
"permission": null,
"category": "Server",
"uuid": "9eb94a53963d1ae326dbf4cda6077f55baa8476e",
"id": "6061da0e92d28c50bd40336b",
"certificateAuthority": "AppViewX",
"authorityKeyIdentifier": "D0:D7:4B:D0:82:85:A4:98:70:6E:75:97:26:C6:A3:14:A5:C0:31:4D",
"subjectKeyIdentifier": "9D:1D:77:A0:CA:35:C5:5B:D4:3A:70:1A:AB:B0:2A:DD:CD:61:D9:80",
"issuerSerialNumber": "2C:F4:8E:5F:5F:D2:C2:F2:8A:DB:5A:D4:A1:06:A5:B2",
"authorityInfoAccess": [
"AuthorityInfoAccess : [ accessMethod : 1.3.6.1.5.5.7.48.1, alterativeName : , url : https://172.18.0.157:31443/avxapi/controller/avxocsp?issuerserialnumber=59755839906513824709803510723863029170 ]"
],
"certificatePolicies": [],
"crlDistributionPoints": [
"CrlDistributionPoint : [ name : , url : https://172.18.0.157:31443/avxapi/controller/avxcrl?crlFileName=59755839906513824709803510723863029170.crl ]"
],
"thumbprintAlgorithm": "SHA-1",
"thumbPrint": "64:E8:0C:89:5F:6A:F1:2D:09:47:8C:5B:D5:DC:1B:CE:42:78:06:E7",
"type": "Others",
"genericFields": {
"vs_ip_AppViewX": "",
"device_name_AppViewX": ""
},
"certAttributes": {
"test": "test"
},
"validFromDate": null,
"validToDate": null,
"discoveredFileNames": [],
"issuingTemplate": null,
"csrGenerationSource": "appviewx",
"certificateHSMDetails": null,
"deviceDetails": null,
"newConnectors": [],
"csrAvailable": true,
"enhancedSANTypes": null,
"autoRenewDate": "",
"missingParamsForAutoRenew": "CSR parameters are available for certificate renewal",
"base64ImageContent": null,
"caConnectorName": null,
"caSettingName": null,
"suspendedCertificate": false,
"comments": null,
"mailAddress": "",
"streetAddress": "",
"postalCode": "",
"publicKeyModulus": null,
"requestIds": [
"R145",
"R146"
],
"orderId": null,
"publicKey": "30:81:89:02:81:81:00:8E:EA:40:EF:61:06:00:89:9F:99:70:61:03:C3:D2:28:C1:EF:12:B2:FB:1A:6E:65:1C:85:3D:E1:8D:BD:DF:68:C9:76:A4:23:0D:79:A2:E6:52:F0:68:FC:AD:87:D2:D7:70:7C:76:C5:3F:A5:96:7B:D3:74:8A:5A:98:70:48:95:37:51:E3:33:1B:A7:32:19:E5:39:54:38:8A:1A:5B:A0:9C:5D:B5:D6:A6:EC:D9:DB:8A:FB:B8:BD:66:A6:E2:F9:D8:BF:AB:4D:F1:D3:31:E1:CB:6E:84:CF:C3:6F:E8:1F:E3:AF:12:F4:22:11:13:5E:F3:56:B1:8B:4E:18:BC:4D:02:03:01:00:01",
"ellipticCurve": null,
"issuedByRootCertificate": false,
"cumulativeSanCount": 1,
"privatekeyAvaliable": true
},
"deviceProfiles": [
{
"profileId": "device_name:@serverssl-insecure-compatible:@Common",
"vendor": "F5",
"deviceName": "device_name",
"vendorCategory": "ADC",
"profileIdentifierForView": "device_name::serverssl-insecure-compatible:Common:server-ssl",
"profileDisplayOrder": "Partition:@Profile Name:@SSL Type",
"connectorType": "PROFILE_CONNECTOR",
"applications": [],
"hollisticViewData": {
"Partition": "Common",
"Profile Name": "serverssl-insecure-compatible",
"SSL Type": "server-ssl"
},
"overviewData": {},
"inventoryData": {
"associatedObjects": "device_name::serverssl-insecure-compatible:Common:server-ssl"
},
"vendorProperties": {
"partition": "Common",
"sslType": "server-ssl",
"name": "serverssl-insecure-compatible",
"partitionNameWithoutPath": "Common",
"iAppProfile": false
}
}
],
"applicationConnectors": [
{
"appconnectorId": "device_name:@serverssl-insecure-compatible:@Common:@9eb94a53963d1ae326dbf4cda6077f55baa8476e",
"certificateUuid": "9eb94a53963d1ae326dbf4cda6077f55baa8476e",
"profileInfo": {
"profileId": "device_name:@serverssl-insecure-compatible:@Common",
"vendor": "F5",
"deviceName": "device_name",
"vendorCategory": "ADC",
"profileIdentifierForView": "device_name::serverssl-insecure-compatible:Common:server-ssl",
"profileDisplayOrder": "Partition:@Profile Name:@SSL Type",
"connectorType": "PROFILE_CONNECTOR",
"applications": [],
"hollisticViewData": {
"Partition": "Common",
"Profile Name": "serverssl-insecure-compatible",
"SSL Type": "server-ssl"
},
"overviewData": {},
"inventoryData": {
"associatedObjects": "device_name::serverssl-insecure-compatible:Common:server-ssl"
},
"vendorProperties": {
"partition": "Common",
"sslType": "server-ssl",
"certificateFileName": "certificate_push_202103291347.crt",
"rootCertificateFileName": "test_cert_ca.crt",
"certificatePartition": "Common",
"name": "serverssl-insecure-compatible",
"partitionNameWithoutPath": "Common",
"privateKeyPartition": "Common",
"keyType": "RSA",
"privateKeyFileName": "certificate_push_202103291347.key",
"iAppProfile": false
}
},
"backupInfo": {
"rollbackEligibility": false,
"backupDisplayMessage": null,
"backupCertUuid": null,
"backupCertCommonName": null,
"backupCertSerialNumber": null,
"unbindCertificate": false,
"backupProperties": null
},
"syncInfo": {
"syncMessage": {
"title": "Certificate Push",
"message": "Certificate pushed to the device successfully",
"utcTime": "2021-03-29T13:48:30.605",
"status": "SUCCESS",
"batchId": null
},
"syncStatus": "SYNCRONIZED"
},
"userPreference": {
"autoPush": false,
"overwrite": true,
"securePush": false,
"userName": "admin",
"scheduledPushDate": null,
"modifiedData": true,
"modifiedTime": "2021-03-29T13:46:34.691",
"fileProperties": {
"pushRootAndIntermediateCertificates": false,
"certificateFileName": "certificate_push.crt",
"rootCertificateFileName": "test_cert_ca.crt",
"privateKeyFileName": "certificate_push.key"
},
"validationType": "DEFAULT",
"customApplications": null
},
"vendorScriptDetails": [],
"workflowDetails": {
"requestId": "146",
"workOrderId": "0",
"workflowStatus": "In Progress",
"workflowType": "VW",
"userName": "admin",
"actionType": "PUSHBIND",
"actionTypeDisplayName": "Push",
"taskId": "avxapi_5",
"taskName": "Post Push Script Execution",
"taskType": "others",
"taskStatus": "In Progress",
"currentAction": null,
"proceedProcess": null,
"breakdownProcess": null,
"reviewComponent": false,
"implemetationTime": 0,
"workOrderLogs": [
"Pre Push Script not available",
"Certificate push successful in device : device_name. Certificate/Key/CA file name already exists in device with different content. Certificate push has been completed successfully with names: [ Certificate File Name: certificate_push_202103291347.crt, Private Key File Name: certificate_push_202103291347.key, CA File Name: test_cert_ca.crt ]."
]
},
"loggerStatus": null,
"previousApplicationConnectorId": null
}
],
"success": true,
"messages": [
"Certificate push to the profiles completed successfully"
]
},
"message": null,
"appStatusCode": null,
"tags": {},
"headers": null
}
References
- 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.
- IP: A unique identifier assigned to each device connected to
a computer network that uses the Internet Protocol for communication
- 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.
