This topic describes the best practices for automating certificate renewal for
LDAPS.

## Overview

If you are issuing shorter-lived certificates, we recommend that you automate
the renewal of these certificates.

## Dealing with API errors

Automation should check for errors both on the initial blocking API call as
well as when polling the returned long-running operation. The update can only be
considered as successful if the long-running operation is marked as done without
error.

If `UpdateLdapsSettings` returns an error with code `INVALID_ARGUMENT`, the
error message can explain what is wrong with the uploaded certificate. This
error is typically returned during the initial blocking call to the API. In such
cases, retries are ineffective and the automation should send an alert.

If the API returns any other error code which is retriable (such as
`UNAVAILABLE`), the automation should retry the call with the appropriate
backoff. These errors are typically returned when polling the long-running
operation that is returned by the initial blocking call to
`UpdateLdapsSettings`.

Learn more about
[`UpdateLdapsSettings`](https://docs.cloud.google.com/managed-microsoft-ad/reference/rest/v1/projects.locations.global.domains/updateLdapssettings.md.txt).

## Checking the `LDAPSSettings` state

After calling `UpdateLdapsSettings`, it is good practice to check that
`LDAPSSettings` meets expectations and is in a good state (`ACTIVE`). You can
call `GetLdapsSettings` to compare the fingerprints of certificates in the
intended state against the deployed certificate fingerprints. You can use tools
like OpenSSL to calculate the fingerprints of your new certificates.

Do take note of any display differences between the method the automation uses
to compute fingerprints versus how Managed Microsoft AD stores them.
For example, Managed Microsoft AD stores a thumbprint as a single undelimited
hexadecimal string: `771B8FD90806E074A7AD49B1624D2761137557D2`. OpenSSL returns
the following for the same certificate:
`SHA1 Fingerprint=77:1B:8F:D9:08:06:E0:74:A7:AD:49:B1:62:4D:27:61:13:75:57:D2`.

Learn more about [`LDAPSSettings`](https://docs.cloud.google.com/managed-microsoft-ad/reference/rest/v1/LDAPSSettings.md.txt) and
[`GetLdapsSettings`](https://docs.cloud.google.com/managed-microsoft-ad/reference/rest/v1/projects.locations.global.domains/getLdapssettings.md.txt).

## Building a PFX certificate chain

If your automation procures certificates in the PEM or CRT formats, you must
convert them to PFX and include the entire certificate chain.

To convert to PFX and include the entire chain, complete the following steps
using shell and OpenSSL.

1. Create a single PEM file that includes all intermediate certificates as well
   as the root certificate.

   ```
   cat root-ca-cert.pem >> temp.pem
   echo -e "\n" >> temp.pem
   cat intermediate-ca-cert.pem >> temp.pem
   ```
2. Build the output PFX file. `leaf.key` is the private key.

   ```
   openssl pkcs12 -export -out out.pfx -inkey leaf.key -in leaf-cert.pem \
       -certfile temp.pem -passout "EXPORT_PASSWORD"
   ```
3. Show info of the PFX file. This should show the entire root to leaf chain
   and the private key.

   ```
   openssl pkcs12 -in out.pfx -nodes -passin "EXPORT_PASSWORD"
   ```