Managing certificates

The Connector Appliance provides a self-signed certificate that is served to a browser that connects to the Connector Appliance administration page. You can replace this self-signed certificate with one of your own that is signed by your organization or generated by using your organization’s chain of trust.

Replacing the certificate

To replace the Connector Appliance self-signed certificate, you need the following information:

  • The IP address of your Connector Appliance
  • A valid authorization token
  • A certificate and private key pair in PEM format

Request

POST https://<connector-appliance-ip-address>/$replaceSslCert HTTP/1.1
Accept: appication/json
Authorization: Bearer <token>

{
  "certBytes": "-----BEGIN CERTIFICATE-----\n<certificate-base64-bytes>\n-----END CERTIFICATE-----\n",
  "key": "-----BEGIN PRIVATE KEY-----\n<private-key-base64-bytes>\n-----END PRIVATE KEY-----\n",
  "passphrase": "<optional-private-key-passphrase>"
}
<!--NeedCopy-->

Responses

Success

HTTP/1.1 202 Accepted
Cache-Control: no-cache
Content-Length: 316
Content-Type: application/json; charset=utf-8
Date: Fri, 23 Dec 2016 22:24:00 GMT
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0

{"status": "accepted"}
<!--NeedCopy-->

Missing authentication details

HTTP/1.1 401 Unauthorized
...
Content-Type: application/json; charset=utf-8
...

{
    "type": "https://errors-api.cloud.com/common/authentication",
    "detail": "Missing authentication details",
    "parameters": [
        {
            "name": "reason",
            "value": "missing"
        }
    ]
}
<!--NeedCopy-->

Check that you have a valid authorization token in your request.

Invalid authentication details

HTTP/1.1 401 Unauthorized
...
Content-Type: application/json; charset=utf-8
...

{
    "type": "https://errors-api.cloud.com/common/authentication",
    "detail": "Invalid authentication details",
    "parameters": [
        {
            "name": "reason",
            "value": "invalid"
        }
    ]
}
<!--NeedCopy-->

Check that you have a valid authorization token in your request and that it has not expired.

Missing private key

HTTP/1.1 400 Bad Request
...
Content-Type: application/json; charset=utf-8
...

{
    "type": "https://errors-api.cloud.com/common/missing",
    "detail": "Field \"key\" is missing.",
    "parameters": [
        {
            "name": "property",
            "value": "key"
        }
    ]
}
<!--NeedCopy-->

Check that your request includes a private key in PEM format. You might also receive a similar response if the certificate is missing.

Invalid certificate

HTTP/1.1 400 Bad Request
...
Content-Type: application/json; charset=utf-8
...

{
    "type": "https://errors-api.cloud.com/common/invalidString",
    "detail": "Field \"certBytes\" has an invalid value.",
    "parameters": [
        {
            "name": "property",
            "value": "certBytes"
        }
    ]
}
<!--NeedCopy-->

Check that your request includes a certificate in PEM format. You might also receive a similar response if the private key is invalid.

Next steps

Confirm that the new certificate has taken effect in one of the following ways:

  • In the Connector Appliance console, check that the SHA-1 fingerprint matches that of the certificate you uploaded. Allow at least 30 seconds for the console to update.
  • Go to the Connector Appliance administration page in your browser and check that the certificate shown under the browser lock icon is the new certificate. You might have to refresh the page.
Resources
Connector Appliance APIs OpenAPI Specification
Copy Download
Managing certificates

In this article