Push and Bind Certificate to a Firewall Profile

The push and bind certificate to a firewall profile API uploads the certificate and its private keys to the firewall profile and links them to the server profiles. Refer to After you are done section to Approve and Implement the request.

Before you Begin

Ensure the following before attempting to push and bind certificate to a firewall profile through AppViewX:
  • Firewall devices must be configured in AppViewX.
  • The devices should be in the Managed state.
  • Approval is not required: Enable this mode by setting the ‘Certificate Requests Need Approval?’ flag to false in the Certificate Policy.
  • Approval is required: If the approval setting in the policy cannot be changed, users can approve specific requests by following the After you are done section.

Request Structure

Endpoint: /certificate/pushToDevice
Type: POST
Sample URL: 
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/pushToDevice?gwsource=external

To understand the elements of the sample URL, click here.
Headers
Content-Type: application/json
Table 1. 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’
gwsource

Query

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

Type: String
Payload

Body

 Contains all the parameters to be included in the request body for the POST request.

Type: Payload

Payload

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

Type: String
selectedProfiles (Mandatory) Firewall profile id.

Type: String

Constraint: If the profile connector is specified then certificate is pushed and bound to the profile, but if a default connector is specified then the certificate is only pushed.

certificateDetails (Mandatory) Certificate details for the Firewall devices.

Type: Any of the following type (as per the firewall device) - Refer theFortinet certificate details OR PaloAlto certificate details tables respectively.
pushDetails (Optional) Other push details

Type: pushDetails
Table 3. Fortinet certificate details
Name Description
certificateType (Mandatory) Certificate type i.e. the format in which the certificate is to be pushed to the firewall device.

Type: String

Constraint: Value should be PEM-.pem.
certificateName (Mandatory) Certificate name i.e. the name in which the certificate is to be pushed to the firewall device.

Type: String

Constraint: The certificate file name should not start and end with special characters except @, #, $, %, ^, &, _, {, }, [, ], |, :, <, >, (, ), ;, . It should not be the same as intermediate file name and CA file name.
privateKeyPassword (Optional) Password for the private key pushed to the firewall device.

Type: String
pushRootAndIntermediateCertificates (Mandatory) Indicates whether the Root and Intermediate certificate are to be pushed to the firewall device.

Type: Boolean

Constraint: The value is either true or false.
rootCertificateFileName (Mandatory) Root certificate name i.e. the name in which the root certificate is to be pushed to the firewall device.

Type: String

Constraint: The root certificate name should not start and end with special characters. No special characters except !, @, #, $, %, ^, &, _, {, }, [, ], |, :, <, >, (, ), ;, . and should not be the same as certificate file name and CA file name.
intermediateCertificateFileName (Mandatory) Intermediate certificate name i.e. the name in which the intermediate certificate is to be pushed to the firewall device.

Type: String (multiple values)

Constraint: The intermediate certificate name should not start and end with special characters. No special characters except !, @, #, $, %, ^, &, _, {, }, [, ], |, :, <, >, (, ), ;, . and should not be the same as certificate file name and CA file name.
Table 4. PaloAlto certificate details
Name Description
certificateType (Mandatory) Certificate type i.e. the format in which the certificate is to be pushed to the firewall device.

Type: String

Constraint: Value should be PEM-.pem or PKCS12-.p12.
certificateName (Mandatory) Certificate name i.e. the name in which the certificate is to be pushed to the firewall device.

Type: String

Constraint: The certificate file name should not start and end with special characters except @, #, $, %, ^, &, _, {, }, [, ], |, :, <, >, (, ), ;, . It should not be the same as intermediate file name and CA file name.
pushRootAndIntermediateCertificates (Mandatory) Indicates whether the Root and Intermediate certificate are to be pushed to the firewall device.

Type: Boolean

Constraint: The value is either true or false.
rootCertificateFileName (Mandatory) Root certificate name i.e. the name in which the root certificate is to be pushed to the firewall device.

Type: String

Constraint: The root certificate name should not start and end with special characters. No special characters except !, @, #, $, %, ^, &, _, {, }, [, ], |, :, <, >, (, ), ;, . and should not be the same as certificate file name and CA file name.
intermediateCertificateFileName (Mandatory) Intermediate certificate name i.e. the name in which the intermediate certificate is to be pushed to the firewall device.

Type: String (multiple values)

Constraint: The intermediate certificate name should not start and end with special characters. No special characters except !, @, #, $, %, ^, &, _, {, }, [, ], |, :, <, >, (, ), ;, . and should not be the same as certificate file name and CA file name.
Table 5. pushDetails
Name Description
preValidationScriptPath (Optional) Location of the pre push script.

Type: String
postValidationScriptPath (Optional) Location of the post push script.

Type: String
overwrite (Optional) Indicates whether the certificate needs to be overwritten if already available.

Type: Boolean
pushAutomatically (Optional) Indicates whether the certificate needs to be pushed automatically when renewed.

Type: Boolean

Response Structure

Response returns string of type application/json with the following body parameters:
Table 6. Parameters
Name Description
response Contains the response attributes

Type: response
message Success message 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.
Table 7. response
Name Description
requestId Request ID for push action for the application connector.

Type: String
connectorId Application connector ID.

Type: String

Status Codes

HTTP Code appStatusCode Response Message
202 Accepted NA 1 connector(s) saved and push operation has been triggered.
401 Unauthorized AVX_GW_003 Authentication failed, reason - Invalid Credentials.

Remediation: Ensure that valid username and password or valid sessionId is provided as header parameters.
400 Bad Request MANDATORY_FIELD_MISSING Mandatory field is missing or invalid - <<field name>>

Remediation: Ensure that a valid value is provided for the <<field name>> field in the request.
400 Bad Request INVALID_REQUEST The selectedProfiles parameter is already available in the specified certificate.

Remediation: Provide a different value for the selectedProfiles field.
404 Not Found NO_RECORDS_FOUND No matching records found - certificate not found.

Remediation: Provide a correct value for the field certificateId.
417 Expectation failed FIELD_VALUE_INVALID Invalid value - <<field name>>

Remediation: Ensure that a valid value is provided for the <<field name>> field in the request.
417 Expectation failed CERT-APP-0016 Connector with profiles {} already exists.

Remediation: A profile connector is already available for the selected certificate. Change the certificateId or delete the existing connector.
500 Internal Server Error avx-common-011 Error while processing.

Sample Request/Response

Request Payload
{
 "certificateDetails": {
 "certificateType": "PEM-.pem",
 "certificateName": "testfile",
 "pushRootAndIntermediateCertificates": true,
 "rootCertificateFileName": "testrootfile.pem",
 "intermediateCertificateFileName": [
 "testinterfilelevel1.pem"
 ]
 },
 "pushDetails": {
 "preValidationScriptPath": "",
 "postValidationScriptPath": "",
 "overwrite": false,
 "pushAutomatically": false
 },
 "certificateId": "5f5b1fac77534426423bab57",
 "selectedProfiles": [
 "xxx.xxx.xx.xxx:@Template_001:@shared:@IKE Gateway Profile:@TEST"
 ]
 }
Response
{
 "response": [
 {
 "requestId": "3",
 "connectorId": "xxx.xxx.xx.xxx:@Template_001:@shared:@IKE Gateway Profile:@TEST:@389ed6f96387e3002cc6ac0678c07ffe70459abf"
 }
 ],
 "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.