Managing certificates for Luminesce providers

Luminesce has a CertificateManagement API that you can use to monitor, mint, renew and revoke domain and user certificates providing you have suitable access control permissions.

Luminesce almost always downloads and installs certificates for you. However, there may be times where you need to download or renew certificates, for example when reading/writing to your own SQL database using Sql.Db.Mine.

Monitoring certificates and expiry dates

As a LUSID administrator, you can call the ListCertificates API to view all domain and user certificates ever minted in your domain. You might, for example, send the following command to check for upcoming certificate expiries:

curl -X GET "https://<your-domain>.lusid.com/honeycomb/api/Certificate/certificates"
  -H "Authorization: Bearer <your-API-access-token>"

A response looks like this:

[
  {
    "key": "client-acme",
    "version": 1,
    "commonName": "client-acme",
    "type": "Domain",
    "creationStatus": "Vault, Rabbit, ConfigStore",
    "revocationStatus": "None",
    "validityStart": "2024-03-28T16:12:26.0639697Z",
    "validityEnd": "2025-04-28T00:00:00.0000000Z",
    "createdAt": "2024-03-28T16:12:26.0639697Z",
    "createdBy": "00wjk7twb4hDcHFjN2p4",
    "serialNumber": "36:ad:fa:b0:10:e2:b0:ag:08:0a:05:02:99:8c:77:0c:40:76:1b:7c",
    "links": [
      ...
    ]
  },
  {
    "key": "client-acme_00wjk7twb4hDcHFjN2p4",
    "version": 1,
    "commonName": "client-acme_00wjk7twb4hDcHFjN2p4",
    "type": "User",
    "creationStatus": "Vault, Rabbit, ConfigStore",
    "revocationStatus": "None",
    "validityStart": "2024-06-28T09:06:22.7904420Z",
    "validityEnd": "2025-07-28T00:00:00.0000000Z",
    "createdAt": "2024-06-28T09:06:22.7904420Z",
    "createdBy": "00wjk7twb4hDcHFjN2p4",
    "serialNumber": "37:6d:db:af:7b:d8:13:4d:08:ee:49:78:63:b9:73:d7:cd:bd:cf:8c",
    "links": [
      ...
    ]
  }
]

Note the following:

The type field specifies whether the certificate is user- or domain-level.
- Only LUSID administrators can view domain-level certificates.
- Any user, granted they have permission to call the ListCertificates API, can view their own certificates.
You can monitor the validityStart and validityEnd fields to know when a certificate is valid until and when you may need to renew a certificate. See how to renew a certificate.
The createdBy field provides the user ID of the user who created the certificate. You can pass the user ID into the GetUser API to find out more information about the user, such as their name and assigned roles.

Downloading certificates

You can download a certificate using the DownloadCertificate API. Note it is currently only possible to do this via the Luminesce Swagger page.

Navigate to <your-domain>.lusid.com/honeycomb/swagger/index.html, where <your-domain> is the root of your LUSID domain, for example acmecorp.
Use Swagger’s Try it out button for the DownloadCertificate API to request a User or Domain certificate. Note that you must send two requests to download both the Public and Private keys:
Click the Download file link in the response to download the certificate to your browser’s download location:
Repeat steps 2 and 3 to request and download both the Public and Private key fileType.

Once downloaded, you can copy your certificates to the required location. For example, see where to copy your certificates to for reading/writing to your own SQL database using Sql.Db.Mine.

Renewing certificates

To renew a certificate that may be expiring soon, you can call the ManageCertificate API, passing in a valid API access token and specifying in the request URL:

The action value Renew.
A certificate type out of User or Domain.
Optionally, a validityStart and validityEnd date. If left blank, these default to the current date and 13 months from the current date.

For example, to renew a domain certificate for 13 months:

curl -X PUT "https://<your-domain>.lusid.com/honeycomb/api/Certificate/manage?action=Renew&type=Domain&dryRun=false"
  -H "Authorization: Bearer <your-API-access-token>"

Once renewed, you can download the public and private certificates and copy them to the required location to replace the existing certificates as usual.

Revoking a user certificate

To revoke a user certificate for any reason, you can call the ManageCertificate API, passing in a valid API access token and specifying in the request URL:

The action value Revoke.
A certificate type value User.

For example:

curl -X PUT "https://<your-domain>.lusid.com/honeycomb/api/Certificate/manage?action=Revoke&type=User&dryRun=false"
  -H "Authorization: Bearer <your-API-access-token>"

Revoking and replacing a domain certificate

If you need to revoke a domain certificate, you can call the ManageCertificate API, passing in a valid API access token and specifying in the request URL:

The action value CreateAndAllowMultipleWhichAreValid.
A certificate type value Domain.
A version number incremented by one from the current version number.

For example, to replace a domain certificate before revoking access to the old certificate, you can first create a new version and allow multiple which are valid:

curl -X PUT "https://<your-domain>.lusid.com/honeycomb/api/Certificate/manage?action=CreateAndAllowMultipleWhichAreValid&type=Domain&version=2&dryRun=false"
  -H "Authorization: Bearer <your-API-access-token>"

This both creates a new certificate version and keeps the previous version valid. You can then download the public and private certificates and replace the previous certificate version with the new version without disrupting processes.

Once you have replaced the old certificate with the new version in all the necessary locations, you can call the ManageCertificate API to revoke the previous certificate version. For example:

curl -X PUT "https://<your-domain>.lusid.com/honeycomb/api/Certificate/manage?action=Revoke&type=Domain&version=1&dryRun=false"
  -H "Authorization: Bearer <your-API-access-token>"