Connector Appliance APIs

Managing root certificate authorities

August 16, 2023

Contributed by:

A C

The Connector Appliance comes packaged with a trusted certificates bundle that validates outgoing connections (for example, when making connections to Citrix Cloud services). However, in some cases, the Connector Appliance makes connections to other resources such as on-premises hypervisors or intercepting proxies. These resources are often provisioned with custom root certificates. The Connector Appliance rejects the connection if it cannot validate the SSL certificates provided. In these cases, administrators can provide custom root certificates to the Connector Appliance. These certificates are added to the Connector Appliance’s trusted bundle.

For more information, see Connector Appliance availability and load management.

Usage

To add a certificate to the Connector Appliance, you need the following information:

The IP address of your Connector Appliance
A valid authorization token
A JSON file containing the certificate to be added in textual PEM format

Request

To add a single certificate, make a POST request to the Connector Appliance /rootCA endpoint. Include the appropriate headers, a token to authenticate, and a JSON file containing the certificate in the format displayed below (newlines replaced for \n). Include only one certificate per request. If you include multiple certificates in a single request, the request fails.

Note:

Add only certificates. Avoid adding private keys by mistake.

After you add the required certificates, reboot the Connector Appliance to allow the certificate to take effect. For instructions, see reboot-your-connector-appliance.

POST https://<connector-appliance-ip-address>/rootCA HTTP/1.1
Content-Type: application/json
Accept: */*
Authorization: Bearer <token>

{
    "rootCA": "-----BEGIN CERTIFICATE-----\nMIIEWTCCA0GgAwIBAgIUSmas7Or+0Mc1DbbheaP31obAvHUwDQYJKoZIhvcNAQEL\nBQAwgbsxCzAJBgNVBAYTAlVLMRcwFQYDVQQIDA5DYW1icmlkZ2VzaGlyZTESMBAG\nA1UEBwwJQ2FtYnJpZGdlMRQwEgYDVQQKDAtIZWN0b3IgTHRkLjEUMBIGA1UECwwL\nRW5naW5lZXJpbmcxHzAdBgNVBAMMFnd3dy5oZWN0b3IuZXhhbXBsZS5jb20xMjAw\nBgkqhkiG9w0BCQEWI2hlY3Rvci5jb25uZWN0b3JAaGVjdG9yLmV4YW1wbGUuY29t\nMB4XDTIzMDIxNTE2MjAzNFoXDTMzMDIxMjE2MjAzNFowgbsxCzAJBgNVBAYTAlVL\nMRcwFQYDVQQIDA5DYW1icmlkZ2VzaGlyZTESMBAGA1UEBwwJQ2FtYnJpZGdlMRQw\nEgYDVQQKDAtIZWN0b3IgTHRkLjEUMBIGA1UECwwLRW5naW5lZXJpbmcxHzAdBgNV\nBAMMFnd3dy5oZWN0b3IuZXhhbXBsZS5jb20xMjAwBgkqhkiG9w0BCQEWI2hlY3Rv\nci5jb25uZWN0b3JAaGVjdG9yLmV4YW1wbGUuY29tMIIBIjANBgkqhkiG9w0BAQEF\nAAOCAQ8AMIIBCgKCAQEAm2Rdo5TrcjJnlnLTWb4tORCUF4grmn/sEpNIuU2XhXd5\nnQcCe5DyfxSGYkjd0n2tBM/2ulg8/ZNSfIZ4ipKL41SRo3e9b51h1Q/F6DbZxBwJ\nKdJayfqy7tKCMyL2zSIQSTJ0r1mTnuhrJflzuuXPZtsU2irYPmj0FzrIyPi9xG9j\n4DhRFyrMYrCtzYwEcl3H8qEhQn0+/zKhOWSB6mCET5IkVuV9L8ynTNXbDlzXSJ6Z\nEa94GDakJwu5PZcTYP/XxTJxHzKDlwKSJ1J8xoMHhpGglL6SU7AIjxn2cTWHyqRb\nvwyCqI4xF4ZGSbP8yxGTzybRk/6ZblnCA4ZCRPT4cQIDAQABo1MwUTAdBgNVHQ4E\nFgQUhbO/t2sySufP1178lkeNDRJH+1IwHwYDVR0jBBgwFoAUhbO/t2sySufP1178\nlkeNDRJH+1IwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAXCNh\nRugFaqEwdG24FCYTq0WCmR2n2KarorgiJRDx8mJvXYcVxLA/Gh3/cQaNS1eD8vN1\nQYHVyms5/9+zgx2L2S9xuFvqpFEHc58ee0tmg+2kJ68Ai2CTLp0h/PHyCq0qj4pB\nr7OWRLv15VvOuiJD2af5bz5rngnh3wKjGdZbPf0O9Rfugt37lXRXW6d/BAqoADAA\nQyNPCNC64bUgc2n6kbTs0WKhKFLvccxvp6jnPfRmnqVQgPDc/NcLSWNZ2MZRIhxP\n9U9eOjN4WnP0Kb2GU/1GchzcDpW8JSEEXZckd/n5QeR6M4peYVNuGPdYJOxhuwcc\nBJAHXICvVsMHq6msEw==\n-----END CERTIFICATE-----\n"
}
<!--NeedCopy-->

Responses

Success

A success response will return HTTP 201. The body of the response contains information about the certificate. Reboot the Connector Appliance to allow the certificate to take full effect.

HTTP/1.1 201 Created
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
Location: /rootCA/25981580-2425-4be0-ad1a-e16af35423b3

{
    "id": "25981580-2425-4be0-ad1a-e16af35423b3",
    "subject": "Hector Ltd.",
    "issuer": "Hector Ltd.",
    "expiry": "2033-02-12",
    "fingerprint": "B77AC68C036301E4FFCFBC2469A4B084F72B6418",
    "rootCADetails": "# Common Name or Certificate Name: Hector Ltd.\n# Owner: Hector Ltd.\n# Certificate Serial Number: 4A66ACECEAFED0C7350DB6E179A3F7D686C0BC75\n# Valid From [GMT]: 2023.02.15\n# Valid To [GMT]: 2033.02.12\n",
    "enabled": true
}
<!--NeedCopy-->

Missing authentication details

HTTP/1.1 401 Unauthorized
...
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
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-->

To resolve this error, check that you have a valid authorization token in your request.

Invalid authentication details

HTTP/1.1 401 Unauthorized
...
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
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-->

To resolve this error, check that you have a valid authorization token in your request.

Missing or empty certificate

HTTP/1.1 400 Bad Request
...
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
Content-Type: application/json; charset=utf-8
...

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

To resolve this error, check that you have a valid rootCA field in your request.

Invalid certificate

HTTP/1.1 400 Bad Request
...
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
Content-Type: application/json; charset=utf-8
...

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

To resolve this error, check that you have a valid rootCA field in your request.

Certificate already exists

HTTP/1.1 409 Conflict
...
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
Content-Type: application/json; charset=utf-8

{
    "type": "https://errors-api.cloud.com/connapp/conflict",
    "detail": "Configuration for this rootCA already exists"
}
<!--NeedCopy-->

To resolve this error, check that the rootCA field in your request is different to ones previously sent.

Internal error

HTTP/1.1 500 Internal Server Error
...
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
Content-Type: application/json; charset=utf-8

{
    "type": "https://errors-api.cloud.com/connapp/error",
    "detail": "An error has occurred."
}
<!--NeedCopy-->

To resolve this error, contact Citrix Support. Quote the Citrix-TransactionId returned by the request.

Confirm certificate settings

In the event you need to confirm the existing settings, make a request as described in this section. This information is also shown on the web front end.

Request

GET https://<connector-appliance-ip-address>/rootCA HTTP/1.1
Accept: */*
Authorization: Bearer <token>
<!--NeedCopy-->

Responses

Success

A success response returns HTTP 200. The body of the response contains information about each certificate.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0

{
    "unappliedChanges": false,
    "items": [
        {
            "id": "25981580-2425-4be0-ad1a-e16af35423b3",
            "subject": "Hector Ltd.",
            "issuer": "Hector Ltd.",
            "expiry": "2033-02-12",
            "fingerprint": "B77AC68C036301E4FFCFBC2469A4B084F72B6418",
            "rootCADetails": "# Common Name or Certificate Name: Hector Ltd.\n# Owner: Hector Ltd.\n# Certificate Serial Number: 4A66ACECEAFED0C7350DB6E179A3F7D686C0BC75\n# Valid From [GMT]: 2023.02.15\n# Valid To [GMT]: 2033.02.12\n",
            "enabled": true
        }
    ]
}
<!--NeedCopy-->

If the unappliedChanges field value is true see reboot-your-connector-appliance to apply the latest settings.

Disable certificate

Request

PATCH https://<connector-appliance-ip-address>/rootCA/25981580-2425-4be0-ad1a-e16af35423b3 HTTP/1.1
Accept: */*
Authorization: Bearer <token>

{"enabled": false}
<!--NeedCopy-->

Where 25981580-2425-4be0-ad1a-e16af35423b3 is the id of the certificate to remove.

Responses

Success

HTTP/1.1 204 No Content
Content-Type: application/json; charset=utf-8
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
<!--NeedCopy-->

Certificate ID not found

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0

{
    "type": "https://errors-api.cloud.com/common/notFound",
    "detail": "Not found",
    "parameters": [
        {
            "name": "entityType",
            "value": "https://identifiers-api.cloud.com/connapp/rootCA"
        },
        {
            "name": "id",
            "value": "25981580-2425-4be0-ad1a-e16af35423b3"
        }
    ]
}
<!--NeedCopy-->

Enable certificate

Request

PATCH https://<connector-appliance-ip-address>/rootCA/25981580-2425-4be0-ad1a-e16af35423b3 HTTP/1.1
Accept: */*
Authorization: Bearer <token>

{"enabled": true}
<!--NeedCopy-->

Where 25981580-2425-4be0-ad1a-e16af35423b3 is the id of the certificate to remove.

Responses

Success

HTTP/1.1 204 No Content
Content-Type: application/json; charset=utf-8
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
<!--NeedCopy-->

Certificate ID not found

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0

{
    "type": "https://errors-api.cloud.com/common/notFound",
    "detail": "Not found",
    "parameters": [
        {
            "name": "entityType",
            "value": "https://identifiers-api.cloud.com/connapp/rootCA"
        },
        {
            "name": "id",
            "value": "25981580-2425-4be0-ad1a-e16af35423b3"
        }
    ]
}
<!--NeedCopy-->

Remove certificate

Request

DELETE https://<connector-appliance-ip-address>/rootCA/25981580-2425-4be0-ad1a-e16af35423b3 HTTP/1.1
Accept: */*
Authorization: Bearer <token>
<!--NeedCopy-->

Where 25981580-2425-4be0-ad1a-e16af35423b3 is the id of the certificate to remove.

Responses

Success

HTTP/1.1 204 No Content
Content-Type: application/json; charset=utf-8
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0
<!--NeedCopy-->

Certificate ID not found

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Citrix-TransactionId: bfc9b56c-bcd0-4cf1-9ea1-3da4d48a81c0

{
    "type": "https://errors-api.cloud.com/common/notFound",
    "detail": "Not found",
    "parameters": [
        {
            "name": "entityType",
            "value": "https://identifiers-api.cloud.com/connapp/rootCA"
        },
        {
            "name": "id",
            "value": "25981580-2425-4be0-ad1a-e16af35423b3"
        }
    ]
}
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

Connector Appliance APIs OpenAPI Specification

Copy Download

Managing root certificate authorities

August 16, 2023

Contributed by:

A C

August 16, 2023

Contributed by:

A C

Managing root certificate authorities

Usage

Request

Responses

Success

Missing authentication details

Invalid authentication details

Missing or empty certificate

Invalid certificate

Certificate already exists

Internal error

Confirm certificate settings

Request

Responses

Success

Disable certificate

Request

Responses

Success

Certificate ID not found

Enable certificate

Request

Responses

Success

Certificate ID not found

Remove certificate

Request

Responses

Success

Certificate ID not found

Resources

Connector Appliance APIs OpenAPI Specification

In this article

Resources

Connector Appliance APIs OpenAPI Specification