diff --git a/Makefile b/Makefile index f439b5f4517..84d55eddee7 100644 --- a/Makefile +++ b/Makefile @@ -190,10 +190,12 @@ install_antlr_cli: ## Install antlr CLI locally .PHONY: docker-docs docker-docs: ## Runs the OM docs in docker passing openmetadata-docs as volume for content and images + docker pull openmetadata/docs:latest docker run --name openmetadata-docs -p 3000:3000 -v ${PWD}/openmetadata-docs/content:/docs/content/ -v ${PWD}/openmetadata-docs/images:/docs/public/images openmetadata/docs:latest .PHONY: docker-docs-validate docker-docs-validate: ## Runs the OM docs in docker passing openmetadata-docs as volume for content and images + docker pull openmetadata/docs:latest docker run --entrypoint '/bin/sh' -v ${PWD}/openmetadata-docs/content:/docs/content/ -v ${PWD}/openmetadata-docs/images:/docs/public/images openmetadata/docs:latest -c 'npm run export' .PHONY: docker-docs-local diff --git a/openmetadata-docs/content/deployment/security/enable-ssl/openmetadata-server.md b/openmetadata-docs/content/deployment/security/enable-ssl/openmetadata-server.md index d8a583ce6ea..ccdb0202d49 100644 --- a/openmetadata-docs/content/deployment/security/enable-ssl/openmetadata-server.md +++ b/openmetadata-docs/content/deployment/security/enable-ssl/openmetadata-server.md @@ -91,18 +91,3 @@ Click on `Trust` to open and set `Always Trust`: Once the above steps are finished, all the browsers will allow you to visit the OpenMetadata server using HTTPS. However, you'll still a warning in the address bar. All of these steps are not necessary with an X509 certificate issued by a trusted authority and one should always use that in production. - -### Import public cert into Java Keystore - -This step is required in case you have configured a `bot` with a JWT Token as authentication mechanism and your server -has SSL enabled. - -From your terminal: - -1. Go to your $JAVA_HOME/lib/security where the **cacerts** keystore is located. - -2. Run the following command once in the directory: - -```bash -keytool -import -trustcacerts -keystore cacerts -storepass changeit -noprompt -alias localhost -file /path/to/public.cert -``` diff --git a/openmetadata-docs/content/deployment/security/enable-ssl/ssl-troubleshooting.md b/openmetadata-docs/content/deployment/security/enable-ssl/ssl-troubleshooting.md new file mode 100644 index 00000000000..6ecc438f6a8 --- /dev/null +++ b/openmetadata-docs/content/deployment/security/enable-ssl/ssl-troubleshooting.md @@ -0,0 +1,144 @@ +--- +title: SSL Troubleshooting +slug: /deployment/security/enable-ssl/ssl-troubleshooting +--- + +# SSL Troubleshooting + +In this section we comment common issues that the user can face when enabling SSL in OpenMetadata. + +## Bot using JWT as authentication mechanism + +After enabling SSL on the OM server, we have to update also the public keys URL for the validation of the JWT tokens by +updating to the secured URL: `https://{server_domain}:{port}/api/v1/config/jwks`. + +In case we are using a self-signed certificate, it will fail with the error below: + + + +To avoid this error, you must import your public certificate into the Java Keystore of the OM server. If your OM +deployment is done with Docker or Kubernetes, you must copy the cert into the `openmetadata_server` container or pod. +After that, you can proceed with the following steps from your terminal: + +1. Go to your $JAVA_HOME/lib/security where the **cacerts** keystore is located. + +2. Run the following command once in the directory: + +```bash +keytool -import -trustcacerts -keystore cacerts -storepass changeit -noprompt -alias localhost -file /path/to/public.cert +``` + +After that, you can restart the server, and the error 500 will disappear. + +## Deploying workflows in Airflow + +One common issue after enabling SSL with a self-signed certificate is that our workflows in Airflow will fail or will +not be deployed. We can notice it because the following error will be shown in the UI when deploying or re-deploying: + + + +This can be solved in two different ways: + +#### 1. Validate the certificate using the public certificate (recommended): + +We specify which public certificate must be used to validate the OM server connection. + +1. Copy the public certificate into our Airflow instance. +2. Update the configuration of our OM server so that each time a workflow is deployed, we send the new configuration. + +- In **docker**: + +```yaml +AIRFLOW_VERIFY_SSL=validate +AIRFLOW_SSL_CERT_PATH=/path/to/certificate/in/airflow +``` + +- In **bare metal**: + +Edit the `conf/openmetadata.yaml` file: + +```yaml +airflowConfiguration: + verifySSL: "validate" + sslConfig: + validate: + certificatePath: "/path/to/certificate/in/airflow" +``` + +- In **K8s**: + +We have to update in the `values.yaml` file with: + +```yaml +global: + airflow: + verifySsl: "validate" + sslCertificatePath: "/path/to/certificate/in/airflow" +``` + +#### 2. Ignore the certification validation (not recommended for production): + +When doing any call to the secured OM server, the certificate validation will be ignored. + +- In **docker**: + +```yaml +AIRFLOW_VERIFY_SSL=ignore +``` + +- In **bare metal**: + +Edit the `conf/openmetadata.yaml` file: + +```yaml +airflowConfiguration: + verifySSL: "ignore" +``` + +- In **K8s**: + +We have to update in the `values.yaml` file with: + +```yaml +global: + airflow: + verifySsl: "ignore" +``` + +Once one of the configurations is set, we can restart our OM server and deploy or redeploy without any issues. + +## Ingesting from CLI + +Similar to what happens when deploying workflows in Airflow, we have to update our workflow config file with one of +these options: + +- To validate our certificate: + +```yaml +workflowConfig: + openMetadataServerConfig: + verifySSL: validate + sslConfig: + certificatePath: /local/path/to/certificate +``` + +- To ignore certificate validation: + +```yaml +workflowConfig: + openMetadataServerConfig: + verifySSL: ignore +``` + +## Demo of SSL enabled with an SSO and JWT token configured + +In case you are looking for a full dockerized demo of how JWT tokens, SSO configuration, and SSL enabled work together, +please visit our demo repository [here](https://github.com/open-metadata/openmetadata-demo/tree/main/sso-with-ssl). \ No newline at end of file diff --git a/openmetadata-docs/content/menu.md b/openmetadata-docs/content/menu.md index 847a377a19a..2808ceb5c75 100644 --- a/openmetadata-docs/content/menu.md +++ b/openmetadata-docs/content/menu.md @@ -133,6 +133,8 @@ site_menu: url: /deployment/security/enable-ssl/nginx - category: Deployment / Enable Security / Enable SSL / Use the OpenMetadata Server url: /deployment/security/enable-ssl/openmetadata-server + - category: Deployment / Enable Security / Enable SSL / SSL Troubleshooting + url: /deployment/security/enable-ssl/ssl-troubleshooting - category: Deployment / Enable Security / Enable JWT Tokens url: /deployment/security/enable-jwt-tokens - category: Deployment / Enable Security / JWT Troubleshooting diff --git a/openmetadata-docs/images/deployment/enable-ssl/500-error-ssl.png b/openmetadata-docs/images/deployment/enable-ssl/500-error-ssl.png new file mode 100644 index 00000000000..f7da56a4904 Binary files /dev/null and b/openmetadata-docs/images/deployment/enable-ssl/500-error-ssl.png differ diff --git a/openmetadata-docs/images/deployment/enable-ssl/handshake-error-ssl.png b/openmetadata-docs/images/deployment/enable-ssl/handshake-error-ssl.png new file mode 100644 index 00000000000..1a24154de46 Binary files /dev/null and b/openmetadata-docs/images/deployment/enable-ssl/handshake-error-ssl.png differ