> For the complete documentation index, see [llms.txt](https://documentation.ocsinventory-ng.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ocsinventory-ng.org/administrator-docs/server-setup/security/encryption-key.md). # Encryption Key OCS Inventory Server encrypts sensitive configuration values, such as the LDAP bind password and the OIDC client secret, before storing them in the database. This page explains how that encryption key works and how to change it if needed. ### How It Works The server uses a single encryption key, stored in the server's environment configuration (`FIELD_ENCRYPTION_KEY`), to encrypt and decrypt these values on the fly: * The **LDAP bind password**, used to connect to your directory for authentication. * The **OIDC client secret**, used for single sign-on integration. Without this key configured, the server can't decrypt these values, LDAP and OIDC logins will fail, and any new sensitive value would be saved unencrypted. {% hint style="info" %} The key is generated automatically during a fresh installation. You don't need to do anything for a new install, this page is mainly useful if you need to check, back up, or change the key on an existing installation. {% endhint %} ### Checking the Current Key To confirm a key is configured and see how many sensitive values are currently encrypted with it, run this on the server: ```bash python manage.py encryption_key fingerprint 57c3e6b69c228832 1 secret(s) readable, 0 unreadable ``` This prints a short fingerprint for the current key, along with how many stored secrets can be successfully read with it. If any secrets can't be decrypted, this command will tell you, that usually means the key was changed without following the rotation steps below. ### Backing Up the Key {% hint style="danger" %} If you lose this key, every encrypted value (LDAP bind password, OIDC client secret) becomes permanently unreadable. You'll need to re-enter them manually through the interface. Store a copy of your key somewhere safe, a password manager or your organization's secrets vault, separately from the server itself. {% endhint %} The key is stored as the `FIELD_ENCRYPTION_KEY` value in the server's environment file. Back it up the same way you would any other credential. ### Changing (Rotating) the Key You generally shouldn't need to change this key. Only do so if you suspect it has been exposed, or as part of your organization's routine credential rotation policy. {% hint style="warning" %} Changing the key requires downtime. Any sensitive value saved while the key is being changed will be encrypted with the old key and become unreadable once the new key is in place. Stop the server before rotating the key, and don't restart it until the steps below are complete. {% endhint %} {% stepper %} {% step %} **Stop the server.** This avoids anyone saving a new LDAP or OIDC configuration while the rotation is in progress. {% endstep %} {% step %} **Generate a new key**: ```bash python manage.py encryption_key --generate ``` {% endstep %} {% step %} **Rotate existing secrets** to the new key. This re-encrypts every currently stored secret so it can be read with the new key: ```bash python manage.py encryption_key --rotate ``` {% endstep %} {% step %} **Update your environment file** with the new key value, replacing the previous `FIELD_ENCRYPTION_KEY`. {% endstep %} {% step %} **Restart the server.** {% endstep %} {% step %} **Verify** that everything decrypts correctly: ```bash python manage.py encryption_key ``` This should report all stored secrets as readable. If any aren't, don't discard your old key yet, it may still be needed to recover the affected values. {% endstep %} {% endstepper %} ### Troubleshooting | Symptom | Likely cause | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | LDAP or OIDC logins suddenly fail after a server change | The encryption key in the environment file doesn't match the one the stored secrets were encrypted with. Restore the correct key from your backup. | | Server logs a warning that sensitive values are unencrypted | No `FIELD_ENCRYPTION_KEY` is configured. Generate one and set it in the environment file, then restart the server. | | `encryption_key` reports secrets as unreadable | The key was changed without rotating existing secrets first. Restore the previous key if you still have it, then follow the rotation steps above properly. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.ocsinventory-ng.org/administrator-docs/server-setup/security/encryption-key.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.