diff --git a/docs/accessanalyzer/2601/install/quickinstall.md b/docs/accessanalyzer/2601/install/quickinstall.md index de2e028b0e..85c7a96f4a 100644 --- a/docs/accessanalyzer/2601/install/quickinstall.md +++ b/docs/accessanalyzer/2601/install/quickinstall.md @@ -90,17 +90,19 @@ sudo mkdir -p /etc/dspm | File | What It Is | | --- | --- | -| `.crt` | Server identity certificate in PEM format. The Subject Alternative Name (SAN) list must include the hostname **in lowercase** and the server's IP address. | -| `.key` | Private key paired with the certificate (PEM). The OS user running the installer must be able to read it — not just `root`. | -| `ca-bundle.crt` | CA certificates that trust the server certificate. Required only if an internal or private CA signs the certificate — omit it for a publicly trusted certificate. | +| `tls.crt` | Server identity certificate in PEM format. The Subject Alternative Name (SAN) list must include the hostname **in lowercase** and the server's IP address. | +| `tls.key` | Private key paired with the certificate (PEM). The OS user running the installer must be able to read it — not just `root`. | +| `ca-bundle.pem` | CA certificates that trust the server certificate. Required only if an internal or private CA signs the certificate — omit it for a publicly trusted certificate. | + +These are the installer's pre-filled default filenames — stage your files under these names and you can accept each TLS prompt by pressing **Enter**. Using different filenames is fine; type the actual path at the prompt instead of accepting the default. **SAN requirement:** The hostname in the SAN list must be lowercase. Browsers normalize hostnames to lowercase during TLS validation — a case mismatch causes HTTP 401 failures at sign-in. The SAN must also include the server IP address. ```bash -sudo chown $(whoami) /etc/dspm/.key -sudo chmod 644 /etc/dspm/.key +sudo chown $(whoami) /etc/dspm/tls.key +sudo chmod 644 /etc/dspm/tls.key -sudo cp /etc/dspm/ca-bundle.crt /usr/local/share/ca-certificates/dspm-ca.crt +sudo cp /etc/dspm/ca-bundle.pem /usr/local/share/ca-certificates/dspm-ca.crt sudo update-ca-certificates ``` @@ -108,14 +110,14 @@ sudo update-ca-certificates ```bash # Check that the SAN includes your hostname (lowercase) and server IP -openssl x509 -noout -text -in /etc/dspm/.crt | grep -A5 "Subject Alternative" +openssl x509 -noout -text -in /etc/dspm/tls.crt | grep -A5 "Subject Alternative" # Verify the cert was signed by your CA bundle -openssl verify -CAfile /etc/dspm/ca-bundle.crt /etc/dspm/.crt +openssl verify -CAfile /etc/dspm/ca-bundle.pem /etc/dspm/tls.crt # Verify the key matches the cert (both md5sums must match) -openssl pkey -pubout -in /etc/dspm/.key 2>/dev/null | md5sum -openssl x509 -noout -pubkey -in /etc/dspm/.crt | md5sum +openssl pkey -pubout -in /etc/dspm/tls.key 2>/dev/null | md5sum +openssl x509 -noout -pubkey -in /etc/dspm/tls.crt | md5sum ``` For the full TLS specification including SAN rules and multi-CA environments, see [TLS Certificate Requirements](system/certificates.md). @@ -130,7 +132,7 @@ To let users sign in with their Active Directory or Entra ID credentials instead ### License key -You need your Netwrix license key to download the installer; it's the first prompt in the installation wizard. Obtain it from your Netwrix account representative before starting. +You need your Netwrix license key to download the installer; it's the installer's first prompt. Obtain it from your Netwrix account representative before starting. ### Connector port requirements @@ -230,7 +232,7 @@ If this returns a version number, the binary is ready. If it returns an error, t sudo dspm-installer ``` -The installer presents an interactive wizard: license key, hostname, first admin name and email, and TLS certificate file paths. Each prompt shows an example value and validates your input before moving on — accept a suggested default by pressing **Enter**, or run `dspm-installer --help` for the full flag reference. Installation takes 15–30 minutes. +The installer prompts you interactively for: license key, hostname, first admin name and email, and TLS certificate file paths. Each prompt shows an example value and validates your input before moving on — accept a suggested default by pressing **Enter**, or run `dspm-installer --help` for the full flag reference. Installation takes 15–30 minutes. :::note An **Advanced Settings** step lets you pin to a specific chart **Target Revision** (for example, `1.5.0`) instead of installing the latest release. Leave it empty for standard installations. @@ -418,7 +420,7 @@ For certificate-specific issues, see [TLS Certificate Requirements — Troublesh | Symptom | Likely cause | Fix | | --- | --- | --- | | Sign-in returns HTTP 401 with correct credentials | SAN hostname is mixed-case; browser normalized it to lowercase | Re-issue the certificate with lowercase hostname in the SAN list | -| Installer exits with "Failed to read TLS private key" | Key file owned by `root`, installer runs as non-root user | `sudo chown /etc/dspm/.key` | +| Installer exits with "Failed to read TLS private key" | Key file owned by `root`, installer runs as non-root user | `sudo chown /etc/dspm/tls.key` | | Sign-in silently fails with `PKIX path building failed` in Keycloak logs | CA bundle is missing the LDAPS DC's CA | Concatenate the DC's LDAPS CA into the bundle and re-run the installer | | Browser rejects the application URL with a SAN mismatch error | Hostname entered as an IP address, or SAN doesn't include the hostname in use | Use a DNS hostname and verify the cert SAN list | | Pods not starting after installation | Outbound HTTPS blocked to one or more required endpoints | Verify connectivity to all domains in [Required Domains](#required-domains) | diff --git a/docs/accessanalyzer/2601/install/system/certificates.md b/docs/accessanalyzer/2601/install/system/certificates.md index 074062a270..ccfe7f23df 100644 --- a/docs/accessanalyzer/2601/install/system/certificates.md +++ b/docs/accessanalyzer/2601/install/system/certificates.md @@ -8,17 +8,19 @@ sidebar_position: 40 Access Analyzer requires three certificate-related files at install time. This page describes the format of each file, the rules the installer enforces, and common pitfalls when preparing them. -All three files must be in PEM format. When you choose **Bring your own certificate** in the installer wizard, the wizard prompts you for the path to each file. +All three files must be in PEM format. The installer prompts you for the path to each file — no interactive certificate provisioning exists beyond this; you supply files you've already prepared. ## Summary | File | Installer Prompt | Purpose | | --- | --- | --- | -| `.crt` | TLS Certificate File | Application TLS certificate (what browsers validate) | -| `.key` | TLS Private Key File | Private key paired with the certificate | -| `ca-bundle.crt` | AD/DC Root CA Bundle Path | Trusted root CAs (application and LDAPS) | +| `tls.crt` | TLS Certificate File | Application TLS certificate (what browsers validate) | +| `tls.key` | TLS Private Key File | Private key paired with the certificate | +| `ca-bundle.pem` | CA Bundle File (optional) | Trusted root CAs (application and LDAPS) | -## 1. Application TLS Certificate (`.crt`) +These filenames are the installer's pre-filled defaults at `/etc/dspm/` — see [File Placement on the VM](#file-placement-on-the-vm). Stage your files there under these names and you can accept each TLS prompt by pressing **Enter**; using different names or a different directory just means typing the actual path at the prompt instead. + +## 1. Application TLS Certificate (`tls.crt`) - **Format**: PEM (Base64 certificate block, starting with `-----BEGIN CERTIFICATE-----`). - **Issued by**: your internal certificate authority. @@ -26,19 +28,19 @@ All three files must be in PEM format. When you choose **Bring your own certific - **Hostname in SANs must be lowercase.** Browsers normalize hostnames to lowercase during TLS validation. If the cert SAN is mixed-case, sign-in fails with HTTP 401. Always generate certificates using a lowercase hostname in the SAN list. - **Where it's used**: Traefik serves it for every browser request to the application URL. -## 2. Application TLS Private Key (`.key`) +## 2. Application TLS Private Key (`tls.key`) - **Format**: PEM (`-----BEGIN PRIVATE KEY-----` or `-----BEGIN RSA PRIVATE KEY-----`). - **Must be readable by the OS user running the installer.** If you extracted the key using `sudo` or another elevated context, the file may be owned by `root` with `0600` permissions — the installer will fail to read it. After extraction, set ownership to the user running the installer: ```bash - sudo chown : /opt/dspm-tls/.key - sudo chmod 644 /opt/dspm-tls/.key + sudo chown : /etc/dspm/tls.key + sudo chmod 644 /etc/dspm/tls.key ``` -- **Never share or commit this file.** Once inside `/opt/dspm-tls/` with correct ownership, restrict access via directory permissions. +- **Never share or commit this file.** Once inside `/etc/dspm/` with correct ownership, restrict access via directory permissions. -## 3. CA Bundle (`ca-bundle.crt`) +## 3. CA Bundle (`ca-bundle.pem`) - **Format**: a single PEM file containing one or more `-----BEGIN CERTIFICATE-----` blocks concatenated together. - **Must include**: @@ -47,7 +49,7 @@ All three files must be in PEM format. When you choose **Bring your own certific - **Concatenating multiple CAs** is a simple `cat` on Linux: ```bash - cat app-ca.crt ldaps-ca.crt > /opt/dspm-tls/ca-bundle.crt + cat app-ca.crt ldaps-ca.crt > /etc/dspm/ca-bundle.pem ``` - **Why two purposes, one file**: Traefik uses the bundle to secure the application's HTTPS endpoint, **and** Keycloak uses it internally to trust the LDAPS connection to your domain controller. @@ -65,23 +67,23 @@ openssl s_client -connect :636 -showcerts /dev/n | openssl x509 -noout -issuer ``` -Compare the issuer to the CA that signed your application certificate. If they differ, you must include both CAs in `ca-bundle.crt`. +Compare the issuer to the CA that signed your application certificate. If they differ, you must include both CAs in `ca-bundle.pem`. ## File Placement on the VM -The convention used throughout the install documentation is: +The installer's default prompt values point here — using this layout means you can accept every TLS prompt by pressing **Enter**: ``` -/opt/dspm-tls/ -├── .crt # TLS_CERT_FILE -├── .key # TLS_KEY_FILE -└── ca-bundle.crt # TLS_CA_BUNDLE_FILE +/etc/dspm/ +├── tls.crt # TLS Certificate File +├── tls.key # TLS Private Key File +└── ca-bundle.pem # CA Bundle File (optional) ``` After staging the files, trust the CA bundle at the OS level so tools like `curl` and `kubectl` also recognize it: ```bash -sudo cp /opt/dspm-tls/ca-bundle.crt /usr/local/share/ca-certificates/dspm-ca.crt +sudo cp /etc/dspm/ca-bundle.pem /usr/local/share/ca-certificates/dspm-ca.crt sudo update-ca-certificates ``` @@ -90,7 +92,7 @@ sudo update-ca-certificates | Symptom | Likely cause | Fix | | --- | --- | --- | | Sign-in fails with HTTP 401 after correct credentials | SAN hostname has mixed case, but browser normalized to lowercase | Re-issue the certificate with lowercase hostname in the SAN list | -| Installer exits with "Failed to read TLS private key" | Key file owned by `root`, installer runs as non-root user | `sudo chown /opt/dspm-tls/.key` | +| Installer exits with "Failed to read TLS private key" | Key file owned by `root`, installer runs as non-root user | `sudo chown /etc/dspm/tls.key` | | Web UI loads, IdP login button appears, sign-in fails silently | CA bundle missing the LDAPS CA | Concatenate the DC's LDAPS CA into the bundle and re-run the installer | | Browser shows "certificate not trusted" | Application CA not distributed to client machines | Distribute the CA to client machines via Group Policy or MDM | | "Certificate is valid for X but not for Y" in browser | Cert SAN doesn't include the hostname or IP being used | Re-issue with full SAN list including both DNS name and IP |