feat: document the way to set up bitwarden with HTTPS (#10)

Signed-off-by: Gergely Brautigam <182850+Skarlso@users.noreply.github.com>
external-secrets · Jul 25, 2024 · 27d11e0 · 27d11e0
1 parent 58f32c8
commit 27d11e0
Showing 1 changed file with 140 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -159,12 +159,152 @@ chart values file.
 
 The certificate will then be required when using external-secrets' Bitwarden provider.
 
+## Certificates
+
+There are many ways to generate secrets for an HTTP server. One of which could be through cert-manager.
+
+That process can be found under the `hack` folder. But using an existing certificate is also possible through helm
+values. These are mounted inside the container and used further by the client with keys defined by the following
+command line arguments:
+
+```go
+	flag.StringVar(&rootArgs.server.KeyFile, "key-file", "/certs/key.pem", "--key-file /certs/key.pem")
+	flag.StringVar(&rootArgs.server.CertFile, "cert-file", "/certs/cert.pem", "--cert-file /certs/cert.pem")
+```
+
+The certificate mount target and values are defined under `image` section in the values file as such:
+
+```yaml
+image:
+  repository: ghcr.io/external-secrets/bitwarden-sdk-server
+  pullPolicy: IfNotPresent
+  # Overrides the image tag whose default is the chart appVersion.
+  tag: ""
+  tls:
+    enabled: true
+    volumeMounts:
+      - mountPath: "/certs"
+        name: "bitwarden-tls-certs"
+    volumes:
+      - name: "bitwarden-tls-certs"
+        secret:
+          secretName: "bitwarden-tls-certs"
+          items:
+            - key: "tls.crt"
+              path: "cert.pem"
+            - key: "tls.key"
+              path: "key.pem"
+            - key: "ca.crt"
+              path: "ca.pem"
+```
+
+To use cert-manager the `hack` folder sets up the following certificate issuer:
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: bitwarden-bootstrap-issuer
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: bitwarden-bootstrap-certificate
+  namespace: cert-manager
+spec:
+  # this is discouraged but required by ios
+  commonName: cert-manager-bitwarden-tls
+  isCA: true
+  secretName: bitwarden-tls-certs
+  subject:
+    organizations:
+      - external-secrets.io
+  dnsNames:
+    - external-secrets-bitwarden-sdk-server.default.svc.cluster.local
+    - bitwarden-sdk-server.default.svc.cluster.local
+    - localhost
+  ipAddresses:
+    - 127.0.0.1
+    - ::1
+  privateKey:
+    algorithm: RSA
+    encoding: PKCS8
+    size: 2048
+  issuerRef:
+    name: bitwarden-bootstrap-issuer
+    kind: ClusterIssuer
+    group: cert-manager.io
+---
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: bitwarden-certificate-issuer
+spec:
+  ca:
+    secretName: bitwarden-tls-certs
+```
+
+The important bits are the `dnsNames`. The first one is with the external-secrets helm release name, and the second one
+is a plain install. But also, external-secrets pins the release name of bitwarden, so that should work too. This will
+create a self-signed certificate for us to use internally. This certificate will later be provided to external-secrets
+so it can talk to the service.
+
+Next, we create a Certificate for bitwarden with the following request:
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: bitwarden-tls-certs
+  namespace: default
+spec:
+  secretName: bitwarden-tls-certs
+  dnsNames:
+    - bitwarden-sdk-server.default.svc.cluster.local
+    - external-secrets-bitwarden-sdk-server.default.svc.cluster.local
+    - localhost
+  ipAddresses:
+    - 127.0.0.1
+    - ::1
+  privateKey:
+    algorithm: RSA
+    encoding: PKCS8
+    size: 2048
+  issuerRef:
+    name: bitwarden-certificate-issuer
+    kind: ClusterIssuer
+    group: cert-manager.io
+```
+
+This is provided to bitwarden to initialize an HTTPS server.
+
+### External-secrets
+
+On external-secrets side, there are two options to provide the certificate.
+
+One is through `caBundle` which accepts the plain root certificate as a base64 encoded value.
+
+Second is through `caProvider` that uses either a secret or a configmap and looks for the right key.
+
+**_WARNING_**: DO NOT provide the same secret as the server. For more detail read [cert-manager Trust Post](https://cert-manager.io/docs/trust/).
+
+### Insecure
+
+For testing purposes, or if you trust your network that much, an `--insecure` flag has been provided that runs this
+server as plain HTTP.
+
 ## Testing
 
 Run `make prime-test-cluster` to launch a cluster and generate a certificate for the service. One done, simply run tilt
 to create the service. Note OSX users must install https://github.com/FiloSottile/homebrew-musl-cross in order to
 build the CGO library.
 
+## External-secrets documentation
+
+Usage on the external-secrets side is documented under [Bitwarden Secrets Manager Provider](https://external-secrets.io/latest/provider/bitwarden-secrets-manager/).
+
 ## License
 
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fexternal-secrets%2Fbitwarden-sdk-server.svg?type=large&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fexternal-secrets%2Fbitwarden-sdk-server?ref=badge_large&issueType=license)