diff --git a/docs/user-documentation/openbao.md b/docs/user-documentation/openbao.md index e4dc21c..848b34d 100644 --- a/docs/user-documentation/openbao.md +++ b/docs/user-documentation/openbao.md @@ -1,33 +1,138 @@ # OpenBao -[OpenBao](https://openbao.org/) is a fork of [HashiCorp Vault](https://developer.hashicorp.com/vault) which is a centralized solution for managing and securing sensitive data like authentication credentials, usernames, API tokens, and database credentials. -Beyond static secrets, OpenBao supports dynamic secrets, allowing applications to generate ephemeral credentials for enhanced security. +## Outline 📋 +- [🧐 What is it?](#-what-is-it) +- [🤔 Why do I want it?](#-why-do-i-want-it) +- [🤿 Diving deeper](#-diving-deeper) +- [🔨 How to use it](#-how-to-use-it) +- [🔗 References](#-references) -OpenBao's _Encrypt as a Service_ feature makes it simple to implement data encryption across your systems. +## 🧐 What is it? ---- +OpenBao is a **secret management tool** embedded into your application stack. It can handle the creation, storage, and management of secrets, ensuring they remain secure. For seamless integration across multiple Kubernetes applications, OpenBao works with the [Kubernetes External Secrets Operator](https://external-secrets.io/latest/), which converts OpenBao’s secrets into Kubernetes secrets. -## Main features +## 🤔 Why do I want it? -OpenBao's Secret Engines include: +### Secure Secrets Storage +OpenBao organizes your secrets in one encrypted location, reducing the risk of loss or accidental exposure, such as through a public code push. -- **Key-Value Store** +### Controlled Access +OpenBao allows you to define rules about who can access which secrets and under what conditions. -- **PKI** (Public Key Infrastructure) for certificate management +### Leasing and Revocation +Secrets with a lease are automatically revoked at the end of their lifespan. Revocation can also be done manually. -- **SSH** for managing SSH credentials +### Dynamic Secrets +OpenBao generates short-lived secrets on demand and revokes them automatically when they’re no longer needed. -- **Transit Engine** for encrypting data without storing it +### Encryption as a Service +OpenBao encrypts and decrypts data without storing it, offering cryptographic functions as a service. -- **Time-based One-Time Passwords** (TOTP) for two-factor authentication +### Audit Devices and logs +Detailed logs track who accessed which secrets and when, providing complete traceability in case of a breach. -- **Kubernetes Secrets** for seamless integration with containerized applications +### Secret Engines +OpenBao offers diverse ways to manage secrets through various secret engines. +Learn more about available secret engines [here](#secret-engines-1). ---- +## 🤿 Diving deeper -## 🔨 How to get it to run +### Secure Secrets Storage +OpenBao validates and authorizes clients (users, machines, applications) using tokens before granting access to secrets or sensitive data. -*Hint: To be able to use OpenBao it has to be unsealed first. This happens automatically. While unsealing an initial token is being created. To access this token just run the **./getpassword.sh** script.* +How does gaining access to OpenBao secrets work? + +![authentication layout](https://openbao.org/assets/images/openbao-auth-workflow-cfa532248968cdd9f3fd16e8c02c1b49.png) + + + +- **Authentication:** Before a human or machine can gain any access, an administrator must configure OpenBao with an auth method. When a client tries to log in to OpenBao, the system checks client’s data against an internal or external (see *Validation* below) system. Once authenticated, Vault generates an **access token** for the client. This token is then used for every action performed in OpenBao. + + Note: the administrator can provide you with an already generated access token + +- **Validation:** If trusted third-party credential repositories (e.g., GitHub, LDAP, AppRole) are specified, OpenBao forwards authentication to them. +- **Authorization:** Vault applies policies based on the authentication method and rules set by the admin to the token that was generated during authentication. Policies provide a declarative way to grant or forbid access to certain **paths** and **operations** in OpenBao. +- **Access:** The client uses the token for access to secrets, keys, or encryption capabilities, as per the associated policies. + +If you want to read more about authentication, visit https://openbao.org/docs/concepts/auth/ + +### Controlled Access + +OpenBao uses policies to manage access to secrets. Policies are basically a **combination of paths and capabilities** (operations) that they allow on these path. Let’s consider this example: + +``` +path "secret/app1/password" { + capabilities = ["create", " read ", "list", "delete"] +} + +path "secret/app2/* " { + capabilities = ["read", "list"] +} +``` + +This policy permits *creating*, *reading*, *listing*, and *deleting* the password at `secret/app1/`, but only allows *reading* and *listing* **all** resources in `secret/app2/` and its subpaths. + +[Here's a tutorial how to use it.](#controlled-access-2) + +For even deeper understanding, go to https://openbao.org/docs/concepts/policies/ + +### Leasing and Revocation + +To simplify key rolling processes, consumers using OpenBao should regularly verify their subscription status to either renew leases where permitted or request replacements for secrets that need updating. +In addition to that, a lease can be revoked manually. When this happens, it invalidates that secret immediately and prevents any further renewals. OpenBao can revoke not only single secrets, but a tree of secrets, for example all secrets read by a specific user, or all secrets of a particular type. + +For example: +In the Kubernetes secrets engine, revoking a lease deletes associated Kubernetes service accounts, immeditally rendering their access keys invalid. + +[Here's a tutorial how to use it.](#leasing-and-revocation-2) + +### Dynamic Secrets +OpenBao generates temporary secrets for systems like Kubernetes, AWS, or SQL databases, only when needed. These secrets are revoked automatically after their Time-To-Live expires. +For example: +An application requests Kubernetes credentials from OpenBao, which generates a token with specific permissions. The token is automatically revoked after its lease ends. + +[Here's a tutorial how to use it.](#dynamic-secrets-2) + +### Encryption as a Service + +The transit secrets engine handles cryptographic operations on data in transit without storing it. It can encrypt, decrypt, sign, verify, and generate hashes or random bytes. + +For example: +Your application sends data to OpenBao for encryption before saving it to a database. OpenBao can then decrypt the data on demand, ensuring security even if the database is compromised. + +[Here's a tutorial how to use it.](#encryption-as-a-service-2) + +Here you can read more about the transit secrets engine https://openbao.org/docs/secrets/transit/ + +### Audit devices and logs + +**Audit devices** are the tool for collecting detailed **logs** of all requests to OpenBao, and their responses. Because every operation with OpenBao is an API request/response, when using a single audit device, the audit log contains every interaction with the OpenBao API, including errors - except for a few paths which do not go via the audit system. +**Audit log** telemetry on the other hand provides information on the health of your configured audit devices. + +[Here's a tutorial how to use it.](#audit-devices-and-logs-2) + +For more information, plese read https://openbao.org/docs/audit/ and https://openbao.org/docs/internals/telemetry/metrics/audit/ + + +### Secret Engines + +One of the core concepts of OpenBao are secret engines. Think of them as a set of path-based APIs, that can be provided with some set of data, after which they take some action on that data, and they return a result. +Let’s shortly take a look at all the OpenBao’s secret engines to better understand what they are. +1. **Key-Value** secret engines – for storing key value pairs +2. **PKI** (Public Key Infrastructure) secret engine - for certificate management +3. **SSH** secret engine - for managing SSH credentials +4. **Transit** secrets engine - for encrypting data without storing it +5. **Time-based One-Time Passwords** (TOTP) secret engine - for two-factor authentication +6. **Kubernetes** secrets engine - for seamless integration with containerized applications + +Here you can find out more about secret engines https://openbao.org/docs/secrets/ + + +## How to set it up? + + Note: This paragraph will be absolete in the future as the functionality will be automated. +
+ Hint: To be able to use OpenBao it has to be unsealed first. This happens automatically. While unsealing an initial token is being created. To access this token just run the ./getpassword.sh script. The External Secrets Operator needs a kubernetes secret containing the **OpenBao's initial token** (see above) to access its secrets. You can create it with: @@ -76,9 +181,38 @@ spec: After that just run `kubectl get externalsecrets -A` to check that there are no problems with synchronization. And to access the secret on your cluster run: `kubectl get secrets -n openbao` ---- + +## 🔨 How to use it? + +### Uneasling + +(Some theory) + +`In our stack the unsealing happens automatically. Nothing to be done here.` + +### Controlled Access + +`Short tutorial here` + +### Leasing and Revocation + +`Short tutorial here` + +### Dynamic Secrets + +`Short tutorial here` + +### Encryption as a Service + +`Short tutorial here` + +### Audit Devices and logs + +`Short tutorial here` ## 🔗 References -* https://openbao.org/docs/platform/k8s/helm/run/#initialize-and-unseal-openbao -* https://developer.hashicorp.com/vault \ No newline at end of file +- image: https://openbao.org/docs/concepts/policies/ +- https://openbao.org/docs/what-is-openbao/ +- https://www.vaultproject.io/ +- https://developer.hashicorp.com/vault \ No newline at end of file