diff --git a/content/docs/img/quickstart/hosted-authenticate-login.png b/content/docs/img/quickstart/hosted-authenticate-login.png new file mode 100644 index 000000000..1061063e2 Binary files /dev/null and b/content/docs/img/quickstart/hosted-authenticate-login.png differ diff --git a/content/docs/img/quickstart/identity-verified.png b/content/docs/img/quickstart/identity-verified.png new file mode 100644 index 000000000..f6a1411da Binary files /dev/null and b/content/docs/img/quickstart/identity-verified.png differ diff --git a/content/docs/img/quickstart/jwt-claims.png b/content/docs/img/quickstart/jwt-claims.png deleted file mode 100644 index 3afe4dd4e..000000000 Binary files a/content/docs/img/quickstart/jwt-claims.png and /dev/null differ diff --git a/content/docs/img/quickstart/self-signed-warning.png b/content/docs/img/quickstart/self-signed-warning.png deleted file mode 100644 index 51371a8e6..000000000 Binary files a/content/docs/img/quickstart/self-signed-warning.png and /dev/null differ diff --git a/content/docs/img/quickstart/user-details-page.png b/content/docs/img/quickstart/user-details-page.png deleted file mode 100644 index d0a86a7c3..000000000 Binary files a/content/docs/img/quickstart/user-details-page.png and /dev/null differ diff --git a/content/docs/img/quickstart/valid-certificate.png b/content/docs/img/quickstart/valid-certificate.png new file mode 100644 index 000000000..5437ab846 Binary files /dev/null and b/content/docs/img/quickstart/valid-certificate.png differ diff --git a/content/docs/img/quickstart/verify-service.png b/content/docs/img/quickstart/verify-service.png deleted file mode 100644 index 91153015c..000000000 Binary files a/content/docs/img/quickstart/verify-service.png and /dev/null differ diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx index 30ea1f654..27bf06578 100644 --- a/content/docs/quickstart.mdx +++ b/content/docs/quickstart.mdx @@ -1,41 +1,64 @@ --- # cSpell:ignore thisisunsafe, genkey, noout -title: Run Pomerium Core With Docker +title: Secure a Web App With Pomerium Core lang: en-US sidebar_label: Quickstart pagination_prev: null pagination_next: null -description: Get Pomerium up and running quickly with Docker. +description: In this quickstart guide, you'll learn how to run Pomerium Core in a Docker container and secure access to a web application. keywords: [ pomerium, identity access proxy, - oidc, - docker, reverse proxy, containers, identity aware proxy, - quickstart pomerium, + quickstart, docker, - docker-compose, + docker compose, + core, + pomerium core, ] --- import ConfigDocker from '@site/content/examples/config/config.docker.yaml.md'; import DockerCompose from '@site/content/examples/docker/basic.docker-compose.yml.md'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Secure a Web Application With Pomerium + +Welcome to Pomerium! This quickstart shows you how to set up Pomerium Core to proxy requests to an internal web application in a containerized Docker environment. + +**Steps to complete**: + +1. Configure [Pomerium Core](/docs/deploy/core) and the [Verify](https://verify.pomerium.com/) web app to run in Docker containers +1. Generate certificates and secrets +1. Access the Verify web app behind Pomerium + +**Time to complete:** 5 minutes + +:::note + +Check out [**Pomerium Fundamentals**](/docs/courses/fundamentals/get-started) for step-by-step instructions on how to configure and run Pomerium Core to protect your apps and services. + +::: -# Run Pomerium Core With Docker +## Before you start -Run Pomerium Core with Docker containers in **under 5 minutes**. +To complete this guide, you need: -The Core quickstart uses Pomerium's [**Hosted Authenticate Service**](/docs/capabilities/hosted-authenticate-service), but you can also configure a [**self-hosted authenticate service**](/docs/capabilities/self-hosted-authenticate-service) to integrate with Pomerium. +- [Docker] and [Docker Compose] +- [mkcert](https://mkcert.dev/) -## Prerequisites +:::info -[Docker] and [Docker Compose] +While this guide uses Docker, Pomerium supports other [**architectures and deployment styles**](/docs/deploy), too. -## Configure Pomerium +::: + +## Set up Pomerium Create a `config.yaml` file in the root of your project. @@ -43,7 +66,46 @@ Add the configuration below to `config.yaml`: -## Configure Docker +### Add a signing key + +Pomerium requires a [signing key](/docs/reference/signing-key) to cryptographically sign a user's JWT for identity verification: + +```bash +openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem +cat ec_private.pem | base64 +``` + +Replace `signing_key` in `config.yaml` with the output of these commands. + +For example: + +```yaml title="config.yaml" +signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUFsSEdxZnFYYzVFTDUwSE1hbUFyOGdJckVYZ0cxaXI5NkQyb1o3aXVxTDlvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFN0lSWWtFR1k0YjRjRHRvbXlWaVVlL3RrVVlseGZ4SFZLMUx0R0FHWWN0NEcvbTA1TkpBRwpxZWFBRDdmN3pwMEloeGFNRThEdGVoZHNrQXNKNFIxSG1RPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo= +``` + +### Create a wildcard TLS certificate + +Generate locally trusted certificates with [mkcert](https://github.com/FiloSottile/mkcert): + +1. Install [mkcert](https://github.com/FiloSottile/mkcert?tab=readme-ov-file#installation) +2. Create a trusted root certificate authority: + +```bash +mkcert -install +``` + +3. Create a wildcard server certificate for `*.localhost.pomerium.io`: + +```bash +mkcert "*.localhost.pomerium.io" +``` + +This creates two files in the current working directory: + +- `_wildcard.localhost.pomerium.io.pem` +- `_wildcard.localhost.pomerium.io-key.pem` + +## Run Pomerium and the Verify application Create a `docker-compose.yaml` file in the root of your project. @@ -51,45 +113,49 @@ Add the configuration below to `docker-compose.yaml`: -## Run Docker Compose +**Run Docker Compose:** ```bash docker compose up ``` -Access the **verify route** you built in your policy: `https://verify.localhost.pomerium.io` +## Access the protected web app -If you get a self-signed certificate warning, see [Handle Self-Signed Certificate Warning](/docs/internals/troubleshooting#handle-self-signed-certificate-warning) to bypass it. +Go to the [Verify URL](https://verify.localhost.pomerium.io) you defined in `config.yaml`. -You should be redirected to the **verify** service. You'll see a page like this: +Pomerium will redirect you to our hosted identity provider to authenticate. -![Verify page](./img/quickstart/verify-service.png) +Then, it will redirect you to the **Verify** service. You'll see a page like this: -Although identity verification failed, you successfully integrated Pomerium with the upstream verify service. +![Accessing the Verify web app behind Pomerium](./img/quickstart/identity-verified.png) -:::tip +Identity verification was successful! -Because this guide doesn't include a [signing key](/docs/reference/signing-key) in the configuration, identity verification will fail. +Let's check the certificate, too: -See [Identity Verification](/docs/capabilities/getting-users-identity) for more information on how Pomerium can use JWTs for authentication. +![Browser showing that the locally trusted domain certificate is valid](./img/quickstart/valid-certificate.png) + +Congratulations! You successfully installed Pomerium and accessed your protected web app. + +:::caution + +This is a test environment! If you followed all the steps in this guide, then your Pomerium environment is not using trusted certificates. Remember to use a valid certificate solution before moving this configuration to a production environment. See [**TLS Certificates and Encryption**](/docs/concepts/certificates) for more information. ::: ## Next Steps -If you want to [try Enterprise](https://www.pomerium.com/enterprise-sales/), check out the [Enterprise with Docker quickstart](/docs/deploy/enterprise/quickstart). +- [**Build Routes**](/docs/courses/fundamentals/build-routes) to access your services +- [**Build Policies**](/docs/courses/fundamentals/build-policies) to protect your services -If you want to try connecting Pomerium with other services, see some of our [Guides](/docs/guides). +:::info -**Did you finish this quickstart guide?** We'd love to hear what you think. Get in touch with us on our [Discuss forum](https://discuss.pomerium.com/), message us on [Twitter](https://twitter.com/pomerium_io), [LinkedIn](https://www.linkedin.com/company/pomerium-inc), or check out our [Community](https://www.pomerium.com/docs/community) page. - -:::caution +For more information on routes and policies in Pomerium, see the following pages: -This is a test environment! If you followed all the steps in this doc your Pomerium environment is not using trusted certificates. Remember to use a valid certificate solution before moving this configuration to a production environment. See [Certificates](/docs/concepts/certificates) for more information. +- [**Routing, Proxying, and Load Balancing**](/docs/capabilities/routing) +- [**Pomerium Policy Language**](/docs/capabilities/ppl) **(PPL)** ::: -[configuration file]: /docs/reference -[container images]: https://hub.docker.com/r/pomerium/pomerium [docker]: https://docs.docker.com/install/ [docker compose]: https://docs.docker.com/compose/install/ diff --git a/content/examples/config/config.docker.yaml.md b/content/examples/config/config.docker.yaml.md index 51516bc93..ec9f48b9d 100644 --- a/content/examples/config/config.docker.yaml.md +++ b/content/examples/config/config.docker.yaml.md @@ -1,20 +1,7 @@ -```yaml -# See detailed configuration settings: https://www.pomerium.com/docs/reference/ +```yaml title="config.yaml" +# Replace signing key +signing_key: -##################################################################### -# If self-hosting, use the localhost authenticate service URL below # -# and remove the hosted URL. # -##################################################################### -# authenticate_service_url: https://authenticate.localhost.pomerium.io - -authenticate_service_url: https://authenticate.pomerium.app - -#################################################################################### -# If self-hosting, you must configure an identity provider. # -# See identity provider settings: https://www.pomerium.com/docs/identity-providers/# -#################################################################################### - -# https://pomerium.com/reference/#routes routes: - from: https://verify.localhost.pomerium.io to: http://verify:8000 @@ -22,6 +9,7 @@ routes: - allow: or: - email: + # Replace user@example.com with your email address is: user@example.com pass_identity_headers: true ``` diff --git a/content/examples/docker/basic.docker-compose.yml.md b/content/examples/docker/basic.docker-compose.yml.md index 78446f2f0..ff732d6b9 100644 --- a/content/examples/docker/basic.docker-compose.yml.md +++ b/content/examples/docker/basic.docker-compose.yml.md @@ -1,16 +1,19 @@ -```yaml -version: "3" +```yaml title="docker-compose.yaml" services: pomerium: image: pomerium/pomerium:latest volumes: - ## Mount your config file: https://www.pomerium.com/docs/reference/ + ## Mount your domain's certificates + - ./_wildcard.localhost.pomerium.io.pem:/pomerium/cert.pem:ro + - ./_wildcard.localhost.pomerium.io-key.pem:/pomerium/privkey.pem:ro + + ## Mount your config file - ./config.yaml:/pomerium/config.yaml:ro ports: - 443:443 ## https://verify.localhost.pomerium.io --> Pomerium --> http://verify verify: image: pomerium/verify:latest - expose: - - 8000 + environment: + - JWKS_ENDPOINT=https://pomerium/.well-known/pomerium/jwks.json ``` \ No newline at end of file diff --git a/cspell.json b/cspell.json index da5eb5411..246ffdb43 100644 --- a/cspell.json +++ b/cspell.json @@ -117,6 +117,7 @@ "pgsql", "pomerium", "posix", + "privkey", "proto", "proxied", "proxying",