Merge pull request #495 from permitio/asaf/cto-92-add-basic-tutorial-…

…about-self-signed-certificates-in-opal

add basic tutorial about self signed certificates

documentation/docs/tutorials/use_self_signed_certificates.mdx

@@ -0,0 +1,76 @@
+---
+title: Use Self Signed Certificates
+---
+
+# How to use self-signed certificates?
+
+### Why?
+
+- If you want to use https in your local dev setup and you don't want to generate public certificates with Let'sEncrypt or something similar.
+- **NEVER use self-signed certificates in production unless you absolutely know what you are doing!**
+
+### How it works
+
+Entities you should be aware of:
+
+- **private CA** - a private certificate authority that can generate TLS certificates. Since this is not a publicly recognized CA, its certificates will not be respected by (almost) anyone - but you can teach OPAL to respect that CA's certificates.
+- **localserver** - a local program running with https:// signed with a certificate that was generated by the "private" CA.
+- **opal-client** - can be directed to fetch data from localserver, can be told to respect the private CA's certificates
+
+### How to generate self-signed certificates
+
+1. Generate a private key for the "private" CA
+
+```
+openssl genrsa -des3 -out ca-private-key.key 2048
+```
+
+2. Generate a public key / certificate for the "private" CA
+
+```
+openssl req -x509 -new -nodes -key ca-private-key.key -sha256 -days 365 -out ca-public.crt
+```
+
+3. Generate a private key for the "localserver" service
+
+```
+openssl genrsa -out localserver-private.key 2048
+```
+
+4. Generate a certificate request signed by the "localserver" private key.
+   NOTE: you must specify the FQDN to be the host of the (self-signed) https service, e.g: `localhost`
+
+```
+openssl req -new -key localserver-private.key -out localserver-request.csr
+```
+
+5. Your "private" CA self-signs on the certificate request and generates a valid self-signed certificate
+
+```
+openssl x509 -req -in localserver-request.csr -CA ca-public.crt -CAkey ca-private-key.key -CAcreateserial -out localserver-cert.crt -days 365 -sha256
+```
+
+### configuring a uvicorn service to use the private certificate as the HTTPs certificate
+
+```
+uvicorn myservice.main:app --reload --port=8000 --ssl-keyfile=localserver-private.key --ssl-certfile=localserver-cert.crt
+```
+
+### Configuring a data entry (via `OPAL_DATA_CONFIG_SOURCES`) to redirect to the self-signed https service
+
+Run OPAL server with:
+
+```
+OPAL_DATA_CONFIG_SOURCES='{"external_source_url":"https://localhost:8000/opal/data/config"}'
+```
+
+### Teaching the opal-client to respect the self signed certificate
+
+Run OPAL client with:
+
+```
+OPAL_CLIENT_SELF_SIGNED_CERTIFICATES_ALLOWED=true
+OPAL_CLIENT_SSL_CONTEXT_TRUSTED_CA_FILE=/path/to/ca-public.crt
+```
+
+If you run OPAL client with docker - don't forget to mount /path/to/ca-public.crt on a docker volume.