diff --git a/VERSION b/VERSION index d4dfa5639..01e994d3d 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -v0.3.0 \ No newline at end of file +v0.4.0 \ No newline at end of file diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index e1a68406a..2facf2ce0 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -26,10 +26,11 @@ module.exports = { { text: "Recipes", link: "/recipes/" }, { text: "Community", link: "/community/" }, { - text: "🚧Dev", // current tagged version + text: "v0.4.0", // current tagged version ariaLabel: "Version menu", items: [ { text: "🚧Dev", link: "https://master.docs.pomerium.io/docs" }, + { text: "v0.4.x", link: "https://0-4-0.docs.pomerium.io/docs" }, { text: "v0.3.x", link: "https://0-3-0.docs.pomerium.io/docs" }, { text: "v0.2.x", link: "https://0-2-0.docs.pomerium.io/docs" }, { text: "v0.1.x", link: "https://0-1-0.docs.pomerium.io/docs" } @@ -90,6 +91,7 @@ module.exports = { "reference/certificates", "reference/impersonation", "reference/programmatic-access", + "reference/getting-users-identity", "reference/signed-headers", "reference/examples", "reference/reference", diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md index 72f5af580..b33675d56 100644 --- a/docs/docs/CHANGELOG.md +++ b/docs/docs/CHANGELOG.md @@ -1,15 +1,16 @@ # Changelog -## vUNRELEASED +## v0.4.0 ### New -- Allow setting request headers for back-end requests on per route basis in policy. [GH-308] -- Add endpoint to support "forward-auth" integration with third-party ingresses and proxies. Supports [nginx]https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/, [nginx-ingress](https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/), and [Traefik](https://docs.traefik.io/middlewares/forwardauth/). [GH-324] -- Add insecure transport support. [GH-328] -- Add setting to override HTTPS backend's TLS Server Name. [GH-297] -- Add setting to set pomerium's encrypted session in a auth bearer token, or query param. +- Allow setting request headers on a per route basis in policy. [GH-308] +- Support "forward-auth" integration with third-party ingresses and proxies. [nginx](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/), [nginx-ingress](https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/), and [Traefik](https://docs.traefik.io/middlewares/forwardauth/) are currently supported. [GH-324] +- Add insecure transport / TLS termination support. [GH-328] +- Add setting to override a route's TLS Server Name. [GH-297] +- Pomerium's session can now be passed as a [bearer-auth header](https://tools.ietf.org/html/rfc6750) or [query string](https://en.wikipedia.org/wiki/Query_string) in addition to as a session cookie. - Add host to the main request logger middleware. [GH-308] +- Add AWS cognito identity provider settings. [GH-314] ### Security @@ -21,6 +22,7 @@ - Fixed an issue where CSRF would fail if multiple tabs were open. [GH-306] - Fixed an issue where pomerium would clean double slashes from paths. [GH-262] - Fixed a bug where the impersonate form would persist an empty string for groups value if none set. [GH-303] +- Fixed HTTP redirect server which was not redirecting the correct hostname. ### Changed @@ -35,6 +37,12 @@ - Removed `AUTHENTICATE_INTERNAL_URL`/`authenticate_internal_url` which is no longer used. +## v0.3.1 + +### Security + +- Fixes vulnerabilities fixed in [Go 1.13.1](https://groups.google.com/forum/m/#!msg/golang-announce/cszieYyuL9Q/g4Z7pKaqAgAJ) including CVE-2019-16276. + ## v0.3.0 ### New @@ -61,7 +69,7 @@ - Remove references to [service named ports](https://golang.org/src/net/lookup.go) and instead use their numeric equivalent. [GH-266] -## v0.2.0 +## v0.2.1 ### Security @@ -285,6 +293,7 @@ [gh-303]: https://github.com/pomerium/pomerium/issues/303 [gh-306]: https://github.com/pomerium/pomerium/issues/306 [gh-308]: https://github.com/pomerium/pomerium/issues/308 +[gh-314]: https://github.com/pomerium/pomerium/pull/314 [gh-316]: https://github.com/pomerium/pomerium/pull/316 [gh-319]: https://github.com/pomerium/pomerium/issues/319 [gh-328]: https://github.com/pomerium/pomerium/issues/328 diff --git a/docs/docs/identity-providers/cognito.md b/docs/docs/identity-providers/cognito.md index bd131ba0e..df8e2a320 100644 --- a/docs/docs/identity-providers/cognito.md +++ b/docs/docs/identity-providers/cognito.md @@ -2,7 +2,7 @@ ## Setting up AWS Cognito -Log in to the [AWS Console](https://console.aws.amazon.com) account. +Log in to the [AWS Console](https://console.aws.amazon.com) account. Go to **Services** on the top menu, and then search for **Cognito** @@ -24,9 +24,9 @@ Assuming you have chosen to **Review defaults**, you will be presented with the ![AWS Cognito Pool Settings](./img/cognito-pool-settings.png) -You can enable Multi-Factor Authentication (MFA), change your Password requirements, Tag the pool, among many other settings. +You can enable Multi-Factor Authentication (MFA), change your Password requirements, Tag the pool, among many other settings. -If you need to make changes after creating your pool, be aware that some settings will recreate the pool rather than update the existing pool. This will also generate new **Client IDs** and **Client Secrets**. An example would be changing *How do you want your end users to sign in?* in **Attributes** from **Username** to **Email address or phone number** +If you need to make changes after creating your pool, be aware that some settings will recreate the pool rather than update the existing pool. This will also generate new **Client IDs** and **Client Secrets**. An example would be changing _How do you want your end users to sign in?_ in **Attributes** from **Username** to **Email address or phone number** Once you have created the pool, you can create an **App Client**. This is where you will configure the Pomerium application settings. Choose **Add an App Client** @@ -42,12 +42,12 @@ After this is done, go to **App client settings** (in the Side menu under **App In the setings for **Pomerium** app, put in the following details -|**Field**|**Description**| -|---------|---------------| -|Callback URL(s)|https://authenticate.corp.example.com/oauth2/callback| -|Enabled Identity Providers|Choose **Cognito User Pool**, unless you have set up another **Identity Provider** (eg SAML)| -|Allowed OAuth Flows|Authorization code grant| -|Allowed OAuth Scopes|Email, OpenID, Profile| +| **Field** | **Description** | +| -------------------------- | -------------------------------------------------------------------------------------------- | +| Callback URL(s) | https://authenticate.corp.example.com/oauth2/callback | +| Enabled Identity Providers | Choose **Cognito User Pool**, unless you have set up another **Identity Provider** (eg SAML) | +| Allowed OAuth Flows | Authorization code grant | +| Allowed OAuth Scopes | Email, OpenID, Profile | ![AWS Cognito App Client Settings](./img/cognito-app-client-settings.png) @@ -77,17 +77,16 @@ An example of using this in a Kubernetes ConfigMap is below: - apiVersion: v1 data: config.yaml: | - # Main configuration flags : https://www.pomerium.io/reference/ - authenticate_service_url: https://k8s-auth-prod.example.com # The URL you have set up for the Pomerium Authentication service - authenticate_internal_url: https://pomerium-authenticate-service.default.svc.cluster.local - authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local - - - idp_provider: oidc - idp_provider_url: https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER_POOL_ID} - idp_client_id: 304a12ktcc5djt9d7enj6dsjkg - idp_client_secret: "1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7" - idp_scopes: ["openid", "email", "profile"] + # Main configuration flags : https://www.pomerium.io/reference/ + authenticate_service_url: https://k8s-auth-prod.example.com # The URL you have set up for the Pomerium Authentication service + authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local + + + idp_provider: oidc + idp_provider_url: https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER_POOL_ID} + idp_client_id: 304a12ktcc5djt9d7enj6dsjkg + idp_client_secret: "1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7" + idp_scopes: ["openid", "email", "profile"] kind: ConfigMap metadata: name: pomerium-config diff --git a/docs/docs/quick-start/helm.md b/docs/docs/quick-start/helm.md index 8bf436b44..9b8e97ed0 100644 --- a/docs/docs/quick-start/helm.md +++ b/docs/docs/quick-start/helm.md @@ -8,7 +8,7 @@ meta: # Pomerium using Helm -This quickstart will show you how to deploy Pomerium with Kubernetes. +This quick-start will show you how to deploy Pomerium with [Helm](https://helm.sh) on [Kubernetes](https://kubernetes.io). ## Prerequisites diff --git a/docs/docs/quick-start/img/synology-reverse-proxy.png b/docs/docs/quick-start/img/synology-reverse-proxy.png index 794e5c56b..1b13436b9 100644 Binary files a/docs/docs/quick-start/img/synology-reverse-proxy.png and b/docs/docs/quick-start/img/synology-reverse-proxy.png differ diff --git a/docs/docs/quick-start/kubernetes.md b/docs/docs/quick-start/kubernetes.md index 7d821332f..aee617d3e 100644 --- a/docs/docs/quick-start/kubernetes.md +++ b/docs/docs/quick-start/kubernetes.md @@ -8,7 +8,7 @@ meta: # Pomerium using Kubernetes -This quickstart will cover how to deploy Pomerium with Kubernetes. Though there are [many ways](https://kubernetes.io/docs/setup/pick-right-solution/) to work with Kubernetes, for the purpose of this guide, we will use Google's [Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). That said, most of the following steps should be very similar using any other provider. +This quickstart will cover how to deploy Pomerium with Kubernetes. ## Prerequisites diff --git a/docs/docs/quick-start/synology.md b/docs/docs/quick-start/synology.md index a68bff5f8..98c4601ff 100644 --- a/docs/docs/quick-start/synology.md +++ b/docs/docs/quick-start/synology.md @@ -26,7 +26,7 @@ Pomerium is lightweight, can easily handle hundreds of concurrent requests, and - A configured Google OAuth2 [identity provider] - A [wild-card TLS certificate][certificate documentation] -Though any supported identity provider would work, this guide uses google. +Though any supported [identity provider] would work, this guide uses google. ## Port forwarding @@ -54,7 +54,7 @@ Set the following **Reverse Proxy Rules**. | Destination Port | 8443 | | HTTP/2 | Enabled | | HSTS | Enabled | -| Destination Protocol | HTTPS | +| Destination Protocol | HTTP | | Destination Hostname | localhost | | Destination Port | 32443 | @@ -170,20 +170,15 @@ These are the minimum set of configuration settings to get Pomerium running in t Go to **Environment** tab. -| Field | Value | -| ------------------------- | ---------------------------------------------------------------------------------------- | -| POLICY | output of `base64 -i policy.yaml` | -| CERTIFICATE | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/fullchain.cer"` | -| CERTIFICATE_KEY | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/*.int.nas.example.io.key"` | -| CERTIFICATE_AUTHORITY | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/ca.cer"` | -| OVERRIDE_CERTIFICATE_NAME | `*.int.nas.example` | -| IDP_CLIENT_SECRET | Values from setting up your [identity provider] | -| IDP_CLIENT_ID | Values from setting up your [identity provider] | -| IDP_PROVIDER | Values from setting up your [identity provider] (e.g. `google`) | -| COOKIE_SECRET | output of `head -c32 /dev/urandom | base64` | -| SHARED_SECRET | output of `head -c32 /dev/urandom | base64` | -| AUTHORIZE_SERVICE_URL | `https://localhost` | -| AUTHENTICATE_SERVICE_URL | `https://authenticate.int.nas.example` | +| Field | Value | +| ------------------------ | --------------------------------------------------------------- | +| POLICY | output of `base64 -i policy.yaml` | +| INSECURE_SERVER | `TRUE`, internal routing within docker will not be encrypted. | +| IDP_CLIENT_SECRET | Values from setting up your [identity provider] | +| IDP_CLIENT_ID | Values from setting up your [identity provider] | +| IDP_PROVIDER | Values from setting up your [identity provider] (e.g. `google`) | +| COOKIE_SECRET | output of `head -c32 /dev/urandom | base64` | +| AUTHENTICATE_SERVICE_URL | `https://authenticate.int.nas.example` | For a detailed explanation, and additional options, please refer to the [configuration variable docs]. Also note, though not covered in this guide, settings can be made via a mounted configuration file. diff --git a/docs/docs/readme.md b/docs/docs/readme.md index 7d2ba507d..2b7da0d8d 100644 --- a/docs/docs/readme.md +++ b/docs/docs/readme.md @@ -24,7 +24,7 @@ Pomerium can be used to: ### System Level -Pomerium sits between end users and services which require strong authentication. After verifying identity with your IDP, Pomerium uses a configurable policy to decide how to route your user's request and if they are authorized to the service. +Pomerium sits between end users and services which require strong authentication. After verifying identity with your identity provider (IdP), Pomerium uses a configurable policy to decide how to route your user's request and if they are authorized to the service. pomerium architecture diagram @@ -38,7 +38,7 @@ Pomerium is composed of 3 logical components: - Verifies all requests with Authentication service - Processes policy to determine external/internal route mappings - Authentication Service - - Handles authentication flow to your IDP as needed + - Handles authentication flow to your IdP as needed - Handles identity verification after initial Authentication - Authorization Service - Processes policy to determine permissions for each service diff --git a/docs/docs/reference/certificates.md b/docs/docs/reference/certificates.md index b2b5aa579..033f63f96 100644 --- a/docs/docs/reference/certificates.md +++ b/docs/docs/reference/certificates.md @@ -42,7 +42,7 @@ Once you've setup your wildcard domain, we can use acme.sh to create a certifica ```bash # Requires acme.sh @ https://github.com/Neilpang/acme.sh -# Install (after reviewing, obviously) by running : +# Install (after reviewing, obviously) by running : # $ curl https://get.acme.sh | sh $HOME/.acme.sh/acme.sh \ --issue \ @@ -91,7 +91,7 @@ Success Verify finished, start to sign. Cert success. -----BEGIN CERTIFICATE----- -.... snip... +.... snip... -----END CERTIFICATE----- Your cert is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.cer Your cert key is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key @@ -101,12 +101,12 @@ And the full chain certs is there: $HOME/.acme.sh/*.corp.example.com_ecc/fullch Here's how the above certificates signed by LetsEncrypt correspond to their respective Pomerium configuration settings: -Pomerium Config | Certificate file ---------------------------- | -------------------------------------------------------------- -[CERTIFICATE] | `$HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer` -[CERTIFICATE_KEY] | `$HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key` -[CERTIFICATE_AUTHORITY] | `$HOME/.acme.sh/*.corp.example.com_ecc/ca.cer` -[OVERRIDE_CERTIFICATE_NAME] | `*.corp.example.com` +| Pomerium Config | Certificate file | +| --------------------------- | -------------------------------------------------------------- | +| [CERTIFICATE] | `$HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer` | +| [CERTIFICATE_KEY] | `$HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key` | +| [CERTIFICATE_AUTHORITY] | `$HOME/.acme.sh/*.corp.example.com_ecc/ca.cer` | +| [OVERRIDE_CERTIFICATE_NAME] | `*.corp.example.com` | Your end users will see a valid certificate for all domains delegated by Pomerium. diff --git a/docs/docs/reference/examples/config/config.example.env b/docs/docs/reference/examples/config/config.example.env index 52088016a..c94cd5844 100644 --- a/docs/docs/reference/examples/config/config.example.env +++ b/docs/docs/reference/examples/config/config.example.env @@ -8,10 +8,10 @@ # export LOG_LEVEL="info" # optional, default is debug export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.beyondperimeter.com -export AUTHORIZE_SERVICE_URL=https://authorize.corp.beyondperimeter.com +# AUTHORIZE_SERVICE_URL defaults to `localhost:5443` in all-in-one mode +# export AUTHORIZE_SERVICE_URL=https://authorize.corp.beyondperimeter.com -# Certificates can be loaded as files or base64 encoded bytes. If neither is set, a -# pomerium will attempt to locate a pair in the root directory +# Certificates can be loaded as files or base64 encoded bytes. # See : https://www.pomerium.io/docs/reference/certificates export CERTIFICATE_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer" # optional, defaults to `./cert.pem` export CERTIFICATE_KEY_FILE="$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key" # optional, defaults to `./certprivkey.pem` diff --git a/docs/docs/reference/examples/config/config.example.yaml b/docs/docs/reference/examples/config/config.example.yaml index ad1b32dbe..f1b24d2ba 100644 --- a/docs/docs/reference/examples/config/config.example.yaml +++ b/docs/docs/reference/examples/config/config.example.yaml @@ -6,14 +6,17 @@ # log_level: info # optional, default is debug authenticate_service_url: https://authenticate.corp.beyondperimeter.com -authorize_service_url: https://authorize.corp.beyondperimeter.com +# authorize_service_url: https://authorize.corp.beyondperimeter.com # usually a behind an ingress url -# Certificates can be loaded as files or base64 encoded bytes. If neither is set, a -# pomerium will attempt to locate a pair in the root directory +# Certificates can be loaded as files or base64 encoded bytes. # certificate_file: "./cert.pem" # optional, defaults to `./cert.pem` # certificate_key_file: "./privkey.pem" # optional, defaults to `./certprivkey.pem` # certificate_authority_file: "./cert.pem" +# alternatively, insecure mode can be used if behind a TLS terminating ingress, +# or when using a sidecar proxy +# insecure_server: true + # base64 encoded cert, eg. `base64 -i cert.pem` / `base64 -i privkey.pem` # certificate: | # "xxxxxx" diff --git a/docs/docs/reference/examples/docker/basic.docker-compose.yml b/docs/docs/reference/examples/docker/basic.docker-compose.yml index d0159c4bc..faa8ddfea 100644 --- a/docs/docs/reference/examples/docker/basic.docker-compose.yml +++ b/docs/docs/reference/examples/docker/basic.docker-compose.yml @@ -1,7 +1,7 @@ version: "3" services: pomerium: - image: pomerium/pomerium:master + image: pomerium/pomerium:v0.4.0 environment: # Generate new secret keys. e.g. `head -c32 /dev/urandom | base64` - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI= diff --git a/docs/docs/reference/examples/docker/nginx.docker-compose.yml b/docs/docs/reference/examples/docker/nginx.docker-compose.yml index f5ab77d85..b38944d45 100644 --- a/docs/docs/reference/examples/docker/nginx.docker-compose.yml +++ b/docs/docs/reference/examples/docker/nginx.docker-compose.yml @@ -12,10 +12,11 @@ services: - /var/run/docker.sock:/tmp/docker.sock:ro pomerium-authenticate: - image: pomerium/pomerium:master # or `build: .` to build from source + image: pomerium/pomerium:v0.4.0 # or `build: .` to build from source restart: always environment: - SERVICES=authenticate + - INSECURE_SERVER=TRUE # NOTE!: Replace with your identity provider settings https://www.pomerium.io/docs/identity-providers.html # - IDP_PROVIDER=google # - IDP_PROVIDER_URL=https://accounts.google.com @@ -24,62 +25,50 @@ services: # - IDP_SERVICE_ACCOUNT=REPLACE_ME # NOTE! Generate new secret keys! e.g. `head -c32 /dev/urandom | base64` # Generated secret keys must match between services - - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M= - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI= # Tell nginx how to proxy pomerium's routes - - VIRTUAL_PROTO=https + - VIRTUAL_PROTO=http - VIRTUAL_HOST=authenticate.corp.beyondperimeter.com - VIRTUAL_PORT=443 volumes: - - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro - - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro - # Retrieve non-secret config keys from the config file : https://www.pomerium.io/docs/reference/reference/ - # See `config.example.yaml` and modify to fit your needs. - ../config/config.example.yaml:/pomerium/config.yaml:ro expose: - 443 pomerium-proxy: - image: pomerium/pomerium:master # or `build: .` to build from source + image: pomerium/pomerium:v0.4.0 # or `build: .` to build from source restart: always environment: - SERVICES=proxy + - INSECURE_SERVER=TRUE # IMPORTANT! If you are running pomerium behind another ingress (loadbalancer/firewall/etc) # you must tell pomerium proxy how to communicate using an internal hostname for RPC - - AUTHORIZE_SERVICE_URL=https://pomerium-authorize + - AUTHORIZE_SERVICE_URL=http://pomerium-authorize:443 # When communicating internally, rPC is going to get a name conflict expecting an external # facing certificate name (i.e. authenticate-service.local vs *.corp.example.com). - - OVERRIDE_CERTIFICATE_NAME=*.corp.beyondperimeter.com - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M= - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI= # Tell nginx how to proxy pomerium's routes - - VIRTUAL_PROTO=https + - VIRTUAL_PROTO=http - VIRTUAL_HOST=*.corp.beyondperimeter.com - VIRTUAL_PORT=443 volumes: - - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro - - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro - # Retrieve non-secret config keys from the config file : https://www.pomerium.io/docs/reference/reference/ - # See `config.example.yaml` and modify to fit your needs. - ../config/config.example.yaml:/pomerium/config.yaml:ro expose: - 443 pomerium-authorize: - image: pomerium/pomerium:master # or `build: .` to build from source + image: pomerium/pomerium:v0.4.0 # or `build: .` to build from source restart: always environment: - SERVICES=authorize - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M= - # Tell nginx how to proxy pomerium's routes - - VIRTUAL_PROTO=https - - VIRTUAL_HOST=authorize.corp.beyondperimeter.com - - VIRTUAL_PORT=443 + - GRPC_INSECURE=TRUE + - GRPC_ADDRESS=:443 + volumes: - - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro - - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro # Retrieve non-secret config keys from the config file : https://www.pomerium.io/docs/reference/reference/ # See `config.example.yaml` and modify to fit your needs. - ../config/config.example.yaml:/pomerium/config.yaml:ro diff --git a/docs/docs/reference/examples/kubernetes/ingress.nginx.yml b/docs/docs/reference/examples/kubernetes/ingress.nginx.yml index aa09bc1a0..18669b065 100644 --- a/docs/docs/reference/examples/kubernetes/ingress.nginx.yml +++ b/docs/docs/reference/examples/kubernetes/ingress.nginx.yml @@ -1,12 +1,14 @@ apiVersion: extensions/v1beta1 kind: Ingress metadata: - name: pomerium-http + name: pomerium-ingress annotations: kubernetes.io/ingress.class: "nginx" - nginx.ingress.kubernetes.io/force-ssl-redirect: "true" - nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" - nginx.ingress.kubernetes.io/proxy-buffer-size: "16k" + # kubernetes.io/tls-acme: "true" + # certmanager.k8s.io/issuer: "letsencrypt-prod" + # nginx.ingress.kubernetes.io/force-ssl-redirect: "true" + # nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" + # nginx.ingress.kubernetes.io/proxy-buffer-size: "16k" # to avoid ingress routing, enable # nginx.ingress.kubernetes.io/ssl-passthrough: "true" @@ -16,7 +18,6 @@ spec: hosts: - "*.corp.beyondperimeter.com" - "authenticate.corp.beyondperimeter.com" - - "authorize.corp.beyondperimeter.com" rules: - host: "*.corp.beyondperimeter.com" @@ -25,7 +26,7 @@ spec: - paths: backend: serviceName: pomerium-proxy-service - servicePort: https + servicePort: http - host: "authenticate.corp.beyondperimeter.com" http: @@ -33,4 +34,4 @@ spec: - paths: backend: serviceName: pomerium-authenticate-service - servicePort: https + servicePort: http diff --git a/docs/docs/reference/examples/kubernetes/kubernetes-config.yaml b/docs/docs/reference/examples/kubernetes/kubernetes-config.yaml index b0edc115f..7865f520f 100644 --- a/docs/docs/reference/examples/kubernetes/kubernetes-config.yaml +++ b/docs/docs/reference/examples/kubernetes/kubernetes-config.yaml @@ -1,4 +1,7 @@ # Main configuration flags : https://www.pomerium.io/docs/reference/reference/ +address: ":80" +insecure_server: true + authenticate_service_url: https://authenticate.corp.beyondperimeter.com authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local diff --git a/docs/docs/reference/examples/kubernetes/kubernetes_nginx.sh b/docs/docs/reference/examples/kubernetes/kubernetes_nginx.sh new file mode 100644 index 000000000..c5ff19b36 --- /dev/null +++ b/docs/docs/reference/examples/kubernetes/kubernetes_nginx.sh @@ -0,0 +1,18 @@ +#!/bin/bash +echo "=> create config from kubernetes-config.yaml which we will mount" +kubectl create configmap config --from-file="config.yaml"="kubernetes-config.yaml" + +echo "=> create our random shared-secret and cookie-secret keys as envars" +kubectl create secret generic shared-secret --from-literal=shared-secret=$(head -c32 /dev/urandom | base64) +kubectl create secret generic cookie-secret --from-literal=cookie-secret=$(head -c32 /dev/urandom | base64) + +echo "=> deploy pomerium proxy, authorize, and authenticate" +kubectl apply -f pomerium-proxy.yml +kubectl apply -f pomerium-authenticate.yml +kubectl apply -f pomerium-authorize.yml + +echo "=> deploy our test app, httpbin" +kubectl apply -f httpbin.yml + +echo "=> deploy nginx-ingress" +kubectl apply -f ingress.yml diff --git a/docs/docs/reference/examples/kubernetes/pomerium-authenticate.yml b/docs/docs/reference/examples/kubernetes/pomerium-authenticate.yml index e0f5b28f7..3b5fee28e 100644 --- a/docs/docs/reference/examples/kubernetes/pomerium-authenticate.yml +++ b/docs/docs/reference/examples/kubernetes/pomerium-authenticate.yml @@ -2,12 +2,10 @@ apiVersion: v1 kind: Service metadata: name: pomerium-authenticate-service - annotations: - cloud.google.com/app-protocols: '{"https":"HTTPS"}' spec: ports: - - port: 443 - name: https + - port: 80 + name: http selector: app: pomerium-authenticate type: NodePort @@ -29,13 +27,13 @@ spec: app: pomerium-authenticate spec: containers: - - image: pomerium/pomerium:master + - image: pomerium/pomerium:v0.4.0 name: pomerium-authenticate args: - --config=/etc/pomerium/config.yaml ports: - - containerPort: 443 - name: https + - containerPort: 80 + name: http protocol: TCP env: - name: SERVICES @@ -50,27 +48,17 @@ spec: secretKeyRef: name: cookie-secret key: cookie-secret - - name: CERTIFICATE - valueFrom: - secretKeyRef: - name: certificate - key: certificate - - name: CERTIFICATE_KEY - valueFrom: - secretKeyRef: - name: certificate-key - key: certificate-key readinessProbe: httpGet: path: /ping - port: 443 - scheme: HTTPS + port: 80 + scheme: HTTP livenessProbe: httpGet: path: /ping - port: 443 - scheme: HTTPS - initialDelaySeconds: 10 + port: 80 + scheme: HTTP + initialDelaySeconds: 5 timeoutSeconds: 1 volumeMounts: - mountPath: /etc/pomerium/ diff --git a/docs/docs/reference/examples/kubernetes/pomerium-authorize.yml b/docs/docs/reference/examples/kubernetes/pomerium-authorize.yml index 177693a10..b23229f29 100644 --- a/docs/docs/reference/examples/kubernetes/pomerium-authorize.yml +++ b/docs/docs/reference/examples/kubernetes/pomerium-authorize.yml @@ -2,15 +2,13 @@ apiVersion: v1 kind: Service metadata: name: pomerium-authorize-service - annotations: - cloud.google.com/app-protocols: '{"https":"HTTPS"}' spec: ports: - - port: 443 - name: https + - port: 80 + name: grpc selector: app: pomerium-authorize - type: NodePort + type: ClusterIP --- apiVersion: apps/v1 kind: Deployment @@ -29,13 +27,13 @@ spec: app: pomerium-authorize spec: containers: - - image: pomerium/pomerium:master + - image: pomerium/pomerium:v0.4.0 name: pomerium-authorize args: - --config=/etc/pomerium/config.yaml ports: - - containerPort: 443 - name: https + - containerPort: 80 + name: grpc protocol: TCP env: - name: SERVICES @@ -45,28 +43,17 @@ spec: secretKeyRef: name: shared-secret key: shared-secret - - name: CERTIFICATE - valueFrom: - secretKeyRef: - name: certificate - key: certificate - - name: CERTIFICATE_KEY - valueFrom: - secretKeyRef: - name: certificate-key - key: certificate-key readinessProbe: - httpGet: - path: /ping - port: 443 - scheme: HTTPS + tcpSocket: + port: 80 + initialDelaySeconds: 5 + periodSeconds: 10 livenessProbe: - httpGet: - path: /ping - port: 443 - scheme: HTTPS - initialDelaySeconds: 10 - timeoutSeconds: 1 + tcpSocket: + port: 80 + initialDelaySeconds: 15 + periodSeconds: 20 + volumeMounts: - mountPath: /etc/pomerium/ name: config diff --git a/docs/docs/reference/examples/kubernetes/pomerium-proxy.yml b/docs/docs/reference/examples/kubernetes/pomerium-proxy.yml index 927059ded..2bdc83a6d 100644 --- a/docs/docs/reference/examples/kubernetes/pomerium-proxy.yml +++ b/docs/docs/reference/examples/kubernetes/pomerium-proxy.yml @@ -2,14 +2,12 @@ apiVersion: v1 kind: Service metadata: name: pomerium-proxy-service - annotations: - cloud.google.com/app-protocols: '{"https":"HTTPS"}' spec: ports: - - port: 443 + - port: 80 protocol: TCP - name: https - targetPort: https + name: http + targetPort: http selector: app: pomerium-proxy type: NodePort @@ -31,13 +29,13 @@ spec: app: pomerium-proxy spec: containers: - - image: pomerium/pomerium:master + - image: pomerium/pomerium:v0.4.0 name: pomerium-proxy args: - --config=/etc/pomerium/config.yaml ports: - - containerPort: 443 - name: https + - containerPort: 80 + name: http protocol: TCP env: - name: SERVICES @@ -52,26 +50,16 @@ spec: secretKeyRef: name: cookie-secret key: cookie-secret - - name: CERTIFICATE - valueFrom: - secretKeyRef: - name: certificate - key: certificate - - name: CERTIFICATE_KEY - valueFrom: - secretKeyRef: - name: certificate-key - key: certificate-key readinessProbe: httpGet: path: /ping - port: 443 - scheme: HTTPS + port: 80 + scheme: HTTP livenessProbe: httpGet: path: /ping - port: 443 - scheme: HTTPS + port: 80 + scheme: HTTP initialDelaySeconds: 10 timeoutSeconds: 1 volumeMounts: diff --git a/docs/docs/reference/getting-users-identity.md b/docs/docs/reference/getting-users-identity.md new file mode 100644 index 000000000..e92102e3b --- /dev/null +++ b/docs/docs/reference/getting-users-identity.md @@ -0,0 +1,41 @@ +--- +title: Getting the user's identity +description: >- + This article describes how to to get a user's identity with Pomerium. +--- + +# Getting the user's identity + +This article describes how to retrieve a user's identity from a pomerium managed application. + +## Headers + +By default, pomerium passes the following [response headers] to it's downstream applications to identify the requesting users. + +| Header | description | +| :------------------------------------- | -------------------------------------------------------------- | +| `x-pomerium-authenticated-user-id` | Subject is the user's id. | +| `x-pomerium-authenticated-user-email` | Email is the user's email. | +| `x-pomerium-authenticated-user-groups` | Groups is the user's groups. | +| `x-pomerium-iap-jwt-assertion` | **Recommended** Contains the user's details as a signed [JWT]. | + +In an ideal environment, the cryptographic authenticity of the user's identifying headers should be enforced at the protocol level using mTLS. + +### Recommended : Signed JWT header + +For whatever reason, (e.g. an attacker bypasses pomerium's protocol encryption, or it is accidentally turned off), it is possible that the `x-pomerium-authenticated-user-{email,id,groups}` headers could be forged. Therefore, it is highly recommended to use and validate the [JWT] assertion header which adds an additional layer of authenticity. + +Verify that the [JWT assertion header](./signed-headers.md) conforms to the following constraints: + +| [JWT] | description | +| :------: | ------------------------------------------------------------------------------------------------------ | +| `exp` | Expiration time in seconds since the UNIX epoch. Allow 1 minute for skew. | +| `iat` | Issued-at time in seconds since the UNIX epoch. Allow 1 minute for skew. | +| `aud` | The client's final domain e.g. `httpbin.corp.example.com`. | +| `iss` | Issuer must be `pomerium-proxy`. | +| `sub` | Subject is the user's id. Can be used instead of the `x-pomerium-authenticated-user-id` header. | +| `email` | Email is the user's email. Can be used instead of the `x-pomerium-authenticated-user-email` header. | +| `groups` | Groups is the user's groups. Can be used instead of the `x-pomerium-authenticated-user-groups` header. | + +[jwt]: https://jwt.io +[response headers]: https://developer.mozilla.org/en-US/docs/Glossary/Response_header diff --git a/docs/docs/reference/reference.md b/docs/docs/reference/reference.md index bc247d1f3..967ef8b2f 100644 --- a/docs/docs/reference/reference.md +++ b/docs/docs/reference/reference.md @@ -610,7 +610,7 @@ Authenticate Service URL is the externally accessible URL for the authenticate s - Config File Key: `authorize_service_url` - Type: `URL` - Required -- Example: `https://authorize.corp.example.com` or `https://pomerium-authorize-service.default.svc.cluster.local` +- Example: `https://authorize.corp.example.com` or `https://pomerium-authorize-service.default.svc.cluster.local` or `https://localhost:5443` Authorize Service URL is the location of the internally accessible authorize service. NOTE: Unlike authenticate, authorize has no publicly accessible http handlers so this setting is purely for gRPC communication. diff --git a/docs/docs/releases.md b/docs/docs/releases.md index 85443405e..9dab05f98 100644 --- a/docs/docs/releases.md +++ b/docs/docs/releases.md @@ -54,6 +54,8 @@ To see difference between releases, please refer to the changelog and upgrading For convenience, we maintain hosted documentation for each tagged release. The format for which is `https://{MAJOR}-{MINOR}-{PATCH}.docs.pomerium.io`. For example: +- [github@master](https://master.docs.pomerium.io/) +- [v0.4.0](https://0-4-0.docs.pomerium.io/) - [v0.3.0](https://0-3-0.docs.pomerium.io/) - [v0.2.0](https://0-2-0.docs.pomerium.io/) - [v0.1.0](https://0-1-0.docs.pomerium.io/) diff --git a/docs/docs/upgrading.md b/docs/docs/upgrading.md index d84dcfc79..d3098f575 100644 --- a/docs/docs/upgrading.md +++ b/docs/docs/upgrading.md @@ -9,10 +9,40 @@ description: >- ## Since 0.3.0 -### Breaking: No default certificate location +### Breaking + +#### Removed Authenticate Internal URL + +The authenticate service no longer uses gRPC to do back channel communication. As a result, `AUTHENTICATE_INTERNAL_URL`/`authenticate_internal_url` is no longer required. + +#### No default certificate location In previous versions, if no explicit certificate pair (in base64 or file form) was set, Pomerium would make a last ditch effort to check for certificate files (`cert.key`/`privkey.pem`) in the root directory. With the introduction of insecure server configuration, we've removed that functionality. If there settings for certificates and insecure server mode are unset, pomerium will give a appropriate error instead of a failed to find/open certificate error. +#### Authorize service health-check is non-http + +The Authorize service will no longer respond to `HTTP`-based healthcheck queries when run as a distinct service (vs all-in-one). As an alternative, you can used on TCP based checks. For example, if using [Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-tcp-liveness-probe): + +```yaml +--- +readinessProbe: + tcpSocket: + port: 443 + initialDelaySeconds: 5 + periodSeconds: 10 +livenessProbe: + tcpSocket: + port: 443 + initialDelaySeconds: 15 + periodSeconds: 20 +``` + +### Non-breaking changes + +#### All-in-one + +If service mode (`SERVICES`/`services`) is set to `all`, gRPC communication with the authorize service will by default occur over localhost, on port `:5443`. + ## Since 0.2.0 Pomerium `v0.3.0` has no known breaking changes compared to `v0.2.0`.