diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 0a6a4ac0c..a729cdd20 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -4,6 +4,10 @@ module.exports = { description: "Pomerium is a beyond-corp inspired, zero trust, open source identity-aware access proxy.", plugins: { + "check-md": { + pattern: "**/*.md", + }, + sitemap: { hostname: "https://www.pomerium.io", }, diff --git a/docs/_posts/2020-05-11-release-0-8.md b/docs/_posts/2020-05-11-release-0-8.md index c0d5ce43b..5e293bc2b 100644 --- a/docs/_posts/2020-05-11-release-0-8.md +++ b/docs/_posts/2020-05-11-release-0-8.md @@ -22,13 +22,13 @@ As always, we recommend upgrading and testing this release in an isolated enviro -[**advanced route matching**]: ../configuration/readme.md#policy -[**automatic certificate management**]: ../docs/reference/certificates.md#per-route-automatic-certificates +[**advanced route matching**]: ../reference/readme.md#policy +[**automatic certificate management**]: ../docs/topics/certificates.md#per-route-automatic-certificates [0.8 release]: https://github.com/pomerium/pomerium/releases/tag/v8.0.0 [changelog]: ../docs/CHANGELOG.md [**github**]: ../docs/identity-providers/github.md [issue tracker]: https://github.com/pomerium/pomerium/issues [let's encrypt]: https://letsencrypt.org/ -[path]: ../configuration/readme.md#path -[prefix]: ../configuration/readme.md#prefix -[regex]: ../configuration/readme.md#regex +[path]: ../reference/readme.md#path +[prefix]: ../reference/readme.md#prefix +[regex]: ../reference/readme.md#regex diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md index aa7007742..8a9ea2015 100644 --- a/docs/docs/CHANGELOG.md +++ b/docs/docs/CHANGELOG.md @@ -553,7 +553,7 @@ There were no changes in the v0.7.1 release, but we updated the build process sl - `http.Server` and `httputil.NewSingleHostReverseProxy` now uses pomerium's logging package instead of the standard library's built in one. [GH-58] -[certificates documentation]: ../reference/certificates.md +[certificates documentation]: ../docs/topics/certificates.md [gh-1]: https://github.com/pomerium/pomerium/issues/1 [gh-10]: https://github.com/pomerium/pomerium/issues/10 [gh-100]: https://github.com/pomerium/pomerium/issues/100 diff --git a/docs/docs/background.md b/docs/docs/background.md index 217cb7142..11c048733 100644 --- a/docs/docs/background.md +++ b/docs/docs/background.md @@ -41,7 +41,7 @@ In summary, perimeter based security suffers from the following shortcomings: - Even just defining what the network perimeter is is an increasingly difficult proposition in a remote-work, BYOD, multi-cloud world. Most organizations are a heterogeneous mix of clouds, servers, devices, and organizational units. - VPNs are often misused and exacerbate the issue by opening yet another door into your network organization. -### Zero-trust, security behind the gates +### Zero-trust [Zero-trust](https://ldapwiki.com/wiki/Zero%20Trust) instead attempts to mitigate these shortcomings by adopting the following principles: diff --git a/docs/docs/community/contributing.md b/docs/docs/community/contributing.md index 6553dc67b..6262531e0 100644 --- a/docs/docs/community/contributing.md +++ b/docs/docs/community/contributing.md @@ -86,10 +86,10 @@ To add a new document to the side or top-bar navigation, see `docs/.vuepress/con We use [Netlify](https://www.netlify.com) to build and host our docs. One of nice features of Netlify, is that a preview of the docs are automatically created for each new pull request that is made, which lets you be sure that the version of your docs that you see locally match what will ultimately be deployed in production. -[configuration variables]: ../reference/readme.md +[configuration variables]: ../../reference/readme.md [download]: https://github.com/pomerium/pomerium/releases [environmental configuration variables]: https://12factor.net/config [httpbin]: https://httpbin.org/ [identity provider]: ../identity-providers/readme.md [make]: https://en.wikipedia.org/wiki/Make_(software) -[tls certificates]: ../reference/certificates.md +[tls certificates]: ../topics/certificates.md diff --git a/docs/docs/identity-providers/azure.md b/docs/docs/identity-providers/azure.md index 17d867053..913e4a333 100644 --- a/docs/docs/identity-providers/azure.md +++ b/docs/docs/identity-providers/azure.md @@ -124,8 +124,8 @@ IDP_CLIENT_SECRET="REPLACE-ME" IDP_SERVICE_ACCOUNT="REPLACE-ME-SEE-ABOVE" ``` -[client id]: ../../configuration/readme.md#identity-provider-client-id -[client secret]: ../../configuration/readme.md#identity-provider-client-secret +[client id]: ../../reference/readme.md#identity-provider-client-id +[client secret]: ../../reference/readme.md#identity-provider-client-secret [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable [oauth2]: https://oauth.net/2/ [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect diff --git a/docs/docs/identity-providers/gitlab.md b/docs/docs/identity-providers/gitlab.md index 67a67eede..283a84610 100644 --- a/docs/docs/identity-providers/gitlab.md +++ b/docs/docs/identity-providers/gitlab.md @@ -68,4 +68,4 @@ When a user first uses pomerium to login, they will be presented with an authori Please be aware that [Group ID](https://docs.gitlab.com/ee/api/groups.html#details-of-a-group) will be used to affirm group(s) a user belongs to. -[identity scopes]: ../../configuration/readme.md#identity-provider-scopes +[identity scopes]: ../../reference/readme.md#identity-provider-scopes diff --git a/docs/docs/identity-providers/google.md b/docs/docs/identity-providers/google.md index d95bd665d..d442889e1 100644 --- a/docs/docs/identity-providers/google.md +++ b/docs/docs/identity-providers/google.md @@ -89,8 +89,8 @@ IDP_CLIENT_SECRET="xxxxxx" IDP_SERVICE_ACCOUNT="zzzz" # output of `base64 -i service-account-key.json` ``` -[client id]: ../../configuration/readme.md#identity-provider-client-id -[client secret]: ../../configuration/readme.md#identity-provider-client-secret +[client id]: ../../reference/readme.md#identity-provider-client-id +[client secret]: ../../reference/readme.md#identity-provider-client-secret [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable [oauth2]: https://oauth.net/2/ [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect diff --git a/docs/docs/identity-providers/okta.md b/docs/docs/identity-providers/okta.md index 0f531b4cb..44fcf3b47 100644 --- a/docs/docs/identity-providers/okta.md +++ b/docs/docs/identity-providers/okta.md @@ -63,8 +63,8 @@ IDP_CLIENT_SECRET="REPLACE_ME" IDP_SERVICE_ACCOUNT="REPLACE_ME" # service account ``` -[client id]: ../../configuration/readme.md#identity-provider-client-id -[client secret]: ../../configuration/readme.md#identity-provider-client-secret +[client id]: ../../reference/readme.md#identity-provider-client-id +[client secret]: ../../reference/readme.md#identity-provider-client-secret [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable [oauth2]: https://oauth.net/2/ [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect diff --git a/docs/docs/identity-providers/one-login.md b/docs/docs/identity-providers/one-login.md index ca6c35885..ce773223a 100644 --- a/docs/docs/identity-providers/one-login.md +++ b/docs/docs/identity-providers/one-login.md @@ -58,8 +58,8 @@ After reloading Pomerium, you should be able to see any login events from your O ![One Login Events Dashboard](./img/one-login-events.png) -[client id]: ../../configuration/readme.md#identity-provider-client-id -[client secret]: ../../configuration/readme.md#identity-provider-client-secret +[client id]: ../../reference/readme.md#identity-provider-client-id +[client secret]: ../../reference/readme.md#identity-provider-client-secret [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable [oauth2]: https://oauth.net/2/ [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect diff --git a/docs/docs/identity-providers/readme.md b/docs/docs/identity-providers/readme.md index 72bc9c584..66348f69b 100644 --- a/docs/docs/identity-providers/readme.md +++ b/docs/docs/identity-providers/readme.md @@ -24,10 +24,10 @@ In this guide we'll cover how to do the following for each identity provider: You must configure an IdP **[Service Account]** to write policy against group membership, or any other data that does not uniquely identify an end-user. -[client id]: ../../configuration/readme.md#identity-provider-client-id -[client secret]: ../../configuration/readme.md#identity-provider-client-secret +[client id]: ../../reference/readme.md#identity-provider-client-id +[client secret]: ../../reference/readme.md#identity-provider-client-secret [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable [oauth2]: https://oauth.net/2/ [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect -[service account]: ../../configuration/#identity-provider-service-account +[service account]: ../../reference/readme.md#identity-provider-service-account diff --git a/docs/docs/quick-start/binary.md b/docs/docs/quick-start/binary.md index 95b103d01..ad6d28330 100644 --- a/docs/docs/quick-start/binary.md +++ b/docs/docs/quick-start/binary.md @@ -48,10 +48,10 @@ source ./env Browse to `external-httpbin.your.domain.example`. Connections between you and [httpbin] will now be proxied and managed by Pomerium. -[configuration variables]: ../../configuration/readme.md +[configuration variables]: ../../reference/readme.md [download]: https://github.com/pomerium/pomerium/releases [environmental configuration variables]: https://12factor.net/config [httpbin]: https://httpbin.org/ [identity provider]: ../identity-providers/ [make]: https://en.wikipedia.org/wiki/Make_(software) -[tls certificates]: ../reference/certificates.md +[tls certificates]: ../topics/certificates.md diff --git a/docs/docs/quick-start/from-source.md b/docs/docs/quick-start/from-source.md index 0b7bad1d1..e0858adc7 100644 --- a/docs/docs/quick-start/from-source.md +++ b/docs/docs/quick-start/from-source.md @@ -71,8 +71,8 @@ make && ./bin/pomerium -config config.yaml Browse to `httpbin.localhost.pomerium.io`. Connections between you and [httpbin] will now be proxied and managed by Pomerium. -[configuration variables]: ../../configuration/readme.md +[configuration variables]: ../../reference/readme.md [httpbin]: https://httpbin.org/ [identity provider]: ../identity-providers/ [make]: https://en.wikipedia.org/wiki/Make_(software) -[tls certificates]: ../reference/certificates.md +[tls certificates]: ../topics/certificates.md diff --git a/docs/docs/quick-start/helm.md b/docs/docs/quick-start/helm.md index 9d62d94be..cfd02d6d9 100644 --- a/docs/docs/quick-start/helm.md +++ b/docs/docs/quick-start/helm.md @@ -52,10 +52,10 @@ You can also navigate to the special pomerium endpoint `httpbin.your.domain.exam ![currently logged in user](./img/logged-in-as.png) -[./scripts/helm_gke.sh]: ../reference/examples.html#helm -[./scripts/kubernetes_gke.sh]: ../reference/examples.html#google-kubernetes-engine -[example kubernetes files]: ../reference/examples.html#google-kubernetes-engine +[./scripts/helm_gke.sh]: https://github.com/pomerium/pomerium/tree/master/examples +[./scripts/kubernetes_gke.sh]: https://github.com/pomerium/pomerium/tree/master/examples +[example kubernetes files]: https://github.com/pomerium/pomerium/tree/master/examples [identity provider]: ../identity-providers/readme.md [letsencrypt]: https://letsencrypt.org/ [script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh -[tls certificates]: ../reference/certificates.md +[tls certificates]: ../topics/certificates.md diff --git a/docs/docs/quick-start/kubernetes.md b/docs/docs/quick-start/kubernetes.md index c552be909..9ae639d42 100644 --- a/docs/docs/quick-start/kubernetes.md +++ b/docs/docs/quick-start/kubernetes.md @@ -63,9 +63,9 @@ You can also navigate to the special pomerium endpoint `httpbin.your.domain.exam ![currently logged in user](./img/logged-in-as.png) -[./kubernetes_gke.sh]: ../../configuration/examples.md#google-kubernetes-engine -[example kubernetes files]: ../../configuration/examples.md#google-kubernetes-engine +[./kubernetes_gke.sh]: https://github.com/pomerium/pomerium/tree/master/examples +[example kubernetes files]: https://github.com/pomerium/pomerium/tree/master/examples [identity provider]: ../identity-providers/readme.md [letsencrypt]: https://letsencrypt.org/ [script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh -[tls certificates]: ../reference/certificates.md +[tls certificates]: ../topics/certificates.md diff --git a/docs/docs/quick-start/readme.md b/docs/docs/quick-start/readme.md index d1c1ac0ce..148087b42 100644 --- a/docs/docs/quick-start/readme.md +++ b/docs/docs/quick-start/readme.md @@ -66,10 +66,10 @@ You can also navigate to the special pomerium endpoint `httpbin.corp.yourdomain. ![currently logged in user](./img/logged-in-as.png) -[configuration file]: ../../configuration/readme.md +[configuration file]: ../../reference/readme.md [container images]: https://hub.docker.com/r/pomerium/pomerium [docker]: https://docs.docker.com/install/ [docker-compose]: https://docs.docker.com/compose/install/ [httpbin]: https://httpbin.org/ [identity provider]: ../identity-providers/readme.md -[tls certificates]: ../reference/certificates.md +[tls certificates]: ../topics/certificates.md diff --git a/docs/docs/quick-start/synology.md b/docs/docs/quick-start/synology.md index cbe4cc746..94dbc869d 100644 --- a/docs/docs/quick-start/synology.md +++ b/docs/docs/quick-start/synology.md @@ -214,8 +214,8 @@ And just to be safe, try logging in from another google account to see what happ ![Synology done](./img/synology-step-4-unauthorized.png) -[certificate documentation]: ../reference/certificates.md -[configuration variable docs]: ../../configuration/readme.md +[certificate documentation]: ../topics/certificates.md +[configuration variable docs]: ../../reference/readme.md [diskstation manager]: https://www.synology.com/en-us/dsm [docker-capable]: https://www.synology.com/en-us/dsm/packages/Docker [httpbin]: https://httpbin.org diff --git a/docs/docs/topics/certificates.md b/docs/docs/topics/certificates.md index e28bcd9a0..6395c1d12 100644 --- a/docs/docs/topics/certificates.md +++ b/docs/docs/topics/certificates.md @@ -100,11 +100,11 @@ Certificates, TLS, and Public Key Cryptography is a vast subject we cannot adequ - [Use TLS](https://smallstep.com/blog/use-tls.html) covers why TLS should be used everywhere; not just for securing typical internet traffic but for securing service communication in both "trusted" and adversarial situations. - [Everything you should know about certificates and PKI but are too afraid to ask](https://smallstep.com/blog/everything-pki.html) -[autocert]: ../../configuration/readme.md#autocert -[autocert directory]: ../../configuration/readme.md#autocert-directory -[certificate]: ../../configuration/readme.md#certificates -[certificate_authority]: ../../configuration/readme.md#certificate-authority -[certificate_key]: ../../configuration/readme.md#certificates -[override_certificate_name]: ../../configuration/readme.md#override-certificate-name -[principles]: ../#why -[zero-trust]: ../#why +[autocert]: ../../reference/readme.md#autocert +[autocert directory]: ../../reference/readme.md#autocert-directory +[certificate]: ../../reference/readme.md#certificates +[certificate_authority]: ../../reference/readme.md#certificate-authority +[certificate_key]: ../../reference/readme.md#certificates +[override_certificate_name]: ../../reference/readme.md#override-certificate-name +[principles]: ../background.md#history +[zero-trust]: ../background.md#zero-trust diff --git a/docs/docs/topics/getting-users-identity.md b/docs/docs/topics/getting-users-identity.md index 73a291739..f5ca2dea7 100644 --- a/docs/docs/topics/getting-users-identity.md +++ b/docs/docs/topics/getting-users-identity.md @@ -110,4 +110,4 @@ In the future, we will be adding example client implementations for: [key management service]: https://en.wikipedia.org/wiki/Key_management [nist p-256]: https://csrc.nist.gov/csrc/media/events/workshop-on-elliptic-curve-cryptography-standards/documents/papers/session6-adalier-mehmet.pdf [secp256r1]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations -[signing key]: ./../../configuration/readme.md#signing-key +[signing key]: ./../../reference/readme.md#signing-key diff --git a/docs/docs/topics/impersonation.md b/docs/docs/topics/impersonation.md index add773551..b79d8ffa5 100644 --- a/docs/docs/topics/impersonation.md +++ b/docs/docs/topics/impersonation.md @@ -158,4 +158,4 @@ And you should see something like the following in response: } ``` -[configuration settings]: ../../configuration/readme.md#administrators +[configuration settings]: ../../reference/readme.md#administrators diff --git a/docs/docs/topics/production-deployment.md b/docs/docs/topics/production-deployment.md index 4bfd50724..4f4e1cde5 100644 --- a/docs/docs/topics/production-deployment.md +++ b/docs/docs/topics/production-deployment.md @@ -12,7 +12,7 @@ Please also see [architecture](../#architecture) for information on component in ## Service Mode -For configuration of the service mode, see [Service Mode](../../configuration/readme.md#service-mode). +For configuration of the service mode, see [Service Mode](../../reference/readme.md#service-mode). ### All in One @@ -27,7 +27,7 @@ In more complicated deployments, you may also choose to share aspects of the con 1. You want central AuthN and AuthZ but need to support a number of independently configured Proxy clusters 2. You want central AuthZ but different Proxy clusters need different IDPs -In both configurations, you must ensure the [Shared Secret](../../configuration/readme.md#shared-secret) matches across services. You must also ensure Proxy and Authenticate external names sit within the same domain. +In both configurations, you must ensure the [Shared Secret](../../reference/readme.md#shared-secret) matches across services. You must also ensure Proxy and Authenticate external names sit within the same domain. ## Scaling diff --git a/docs/docs/topics/programmatic-access.md b/docs/docs/topics/programmatic-access.md index 0f6172b0b..2194ded6d 100644 --- a/docs/docs/topics/programmatic-access.md +++ b/docs/docs/topics/programmatic-access.md @@ -7,13 +7,13 @@ description: >- # Programmatic access -This page describes how to obtain Pomerium access credentials programmatically via a web-based oauth2 based authorization flow. If you have ever used Google's `gcloud` commandline app, the mechanism is very similar. +This page describes how to obtain Pomerium access credentials programmatically via a web-based oauth2 style authorization flow. If you have ever used Google's `gcloud` commandline app, the mechanism is very similar. ## Components ### Login API -The API returns a signed, sign-in url that can be used to complete a user-driven login process with Pomerium and your identity provider. The Login API endpoints takes a `redirect_uri` query param as an argument which points to the location of the callback server to be called following a successful login. +The API returns a cryptographically signed sign-in url that can be used to complete a user-driven login process with Pomerium and your identity provider. The login API endpoint takes a `redirect_uri` query parameter as an argument which points to the location of the callback server to be called following a successful login. For example: @@ -25,7 +25,7 @@ https://authenticate.example.com/.pomerium/sign_in?redirect_uri=http%3A%2F%2Floc ### Callback handler -It is the script or application's responsibility to create a HTTP callback handler. Authenticated sessions are returned in the form of a [callback](https://developer.okta.com/docs/concepts/auth-overview/#what-kind-of-client-are-you-building) from pomerium to a HTTP server. This is the `redirect_uri` value used to build Login API's URL, and represents the URL of a (usually local) http server responsible for receiving the resulting user session in the form of `pomerium_jwt` and `pomerium_refresh_token` query parameters. +It is the script or application's responsibility to create a HTTP callback handler. Authenticated sessions are returned in the form of a [callback](https://developer.okta.com/docs/concepts/auth-overview/#what-kind-of-client-are-you-building) from pomerium to a HTTP server. This is the `redirect_uri` value used to build login API's URL, and represents the URL of a (usually local) HTTP server responsible for receiving the resulting user session in the form of `pomerium_jwt` and `pomerium_refresh_token` query parameters. See the python script below for example of how to start a callback server, and store the session payload. @@ -44,9 +44,9 @@ The application interacting with Pomerium must manage the following workflow. Co 1. The user completes the identity providers login flow. 1. The identity provider makes a callback to pomerium's authenticate service (e.g. `authenticate.corp.domain.example`) . 1. Pomerium's authenticate service creates a user session and redirect token, then redirects back to the managed endpoint (e.g. `httpbin.corp.domain.example`) -1. Pomerium's proxy service and makes a callback request to the original `redirect_uri` with the user session and refresh token as arguments. -1. The script or application is responsible for handling that http callback request, and securely handling the callback session (`pomerium_jwt`) and refresh token (`pomerium_refresh_token`) queryparams. -1. The script or application can now make any requests as normal, by setting the `Authorization: Pomerium ${pomerium_jwt}` header. +1. Pomerium's proxy service makes a callback request to the original `redirect_uri` with the user session and as an argument. +1. The script or application is responsible for handling that http callback request, and securely handling the callback session (`pomerium_jwt`) queryparam. +1. The script or application can now make any requests as normal to the upstrream application by setting the `Authorization: Pomerium ${pomerium_jwt}` header. ## Example Code diff --git a/docs/docs/upgrading.md b/docs/docs/upgrading.md index 08ac407d6..b52d56488 100644 --- a/docs/docs/upgrading.md +++ b/docs/docs/upgrading.md @@ -5,43 +5,52 @@ description: >- for Pomerium. Please read it carefully. --- -# Since 0.10.0 +# Since 0.9.0 ## Breaking -### Service Accounts and `allowed_groups` +### Service accounts required for groups and directory data -With this release we now query group information asynchronously using a service account. This was already the behavior -for Google, but for all other providers a `idp_service_account` configuration will need to be supplied. The format of -this field varies and is specified in each identity provider's documentation. +With the v0.10.0 release, Pomerium now queries group information asynchronously using a service account. While a service account was already required for a few identity providers like Google's GSuite, an [Identity Provider Service Account] is now required for all other providers as well. The format of this field varies and is specified in each identity provider's documentation. -If no `idp_service_account` is supplied, the `allowed_groups` policy configuration will not work. +:::warning -### Cache Service +If no [Identity Provider Service Account] is supplied, policies using groups (e.g. `allowed_groups` will not work). -The cache service now stores user and session data in storage backend (rather than in a browser cookie). There are two storage -backend types supported, `memory` or `redis`. +::: + +### Cache service builds stateful context + +With the v0.10 release, Pomerium now asynchronously fetches associated authorization context (e.g. identity provider directory context, groups, user-data, session data, etc) in the `cache` service. In previous versions, Pomerium used session cookies to associated identity state which authorization policy was evaluated against. While using session tokens had the advantage of making Pomerium a relatively stateless application, that approach has many shortcomings which is more extensively covered in the [data storage docs](./topics/data-storage.md). + +There are two [storage backend types] available: `memory` or `redis`. You can see the existing [storage backend configuration settings in the docs][cache service docs]. + +#### Memory Storage Backend + +For `memory` storage, restarting the cache service will result in all users having to re-login. Code for the in-memory database used by the cache service can be found here: [internal/databroker/memory](https://github.com/pomerium/pomerium/tree/master/internal/databroker/memory). + +:::warning Running more than one instance of the `memory` type cache service is not supported. -For `memory` storage, restarting the cache service will result in all users having to re-login. The in-memory database used by the cache -service can be found here: [internal/databroker/memory](https://github.com/pomerium/pomerium/tree/master/internal/databroker/memory). +::: -The `redis` storage can be used for persistent data, you can see the existing [storage backend configuration here]. +#### Redis Storage Backend -You can see: +In production deployments, we recommend using the `redis` storage backend. Unlike the `memory` backend, `redis` can be used for persistent data. - - [databroker gRPC interface](https://github.com/pomerium/pomerium/blob/master/pkg/grpc/databroker/databroker.proto) - - [storage backend interface](https://github.com/pomerium/pomerium/blob/master/pkg/storage/storage.go) - -for reference to implement your own. +#### Implementing your own storage backend + +Please see the following interfaces for reference to implement your storage backend interface. + +- [databroker gRPC interface](https://github.com/pomerium/pomerium/blob/master/pkg/grpc/databroker/databroker.proto) +- [storage backend interface](https://github.com/pomerium/pomerium/blob/master/pkg/storage/storage.go) ### Identity headers -With this release, pomerium will not insert identity headers (X-Pomerium-Jwt-Asserttion/X-Pomerium-Claim-*) by default. To get pre 0.9.0 behavior, you -can set `pass_identity_headers` to true on a per-policy basis. +With this release, pomerium will not insert identity headers (X-Pomerium-Jwt-Asserttion/X-Pomerium-Claim-*) by default. To get pre 0.9.0 behavior, you can set `pass_identity_headers` to true on a per-policy basis. -# Since 0.9.0 +# Since 0.8.0 ## Breaking @@ -51,32 +60,26 @@ With this release, default log level has been changed to INFO. ### HTTP 1.0 -HTTP 1.0 is not supported anymore. If you relied on it make sure to upgrade to HTTP 1.1 or higher. +HTTP 1.0 (not to be confused with HTTP 1.1) is not supported anymore. If you relied on it make sure to upgrade to HTTP 1.1 or higher. Example for HAProxy health check, in pre `0.9.0`: -```shell script -option httpchk GET /ping +```sh +shell script option httpchk GET /ping ``` In `0.9.0`: -```shell script - +```sh option httpchk GET /ping HTTP/1.1\r\nHost:pomerium ``` ### preserve_host_header option -With this release, Pomerium uses an embedded envoy proxy instead hand-written one. Thus, we defer the preserve host header -functionality to [envoy's auto_host_rewrite](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-auto-host-rewrite), -which does not affect if the policy routes to a static IP. +With this release, Pomerium uses an embedded envoy proxy instead hand-written one. Thus, we defer the preserve host header functionality to [envoys auto_host_rewrite](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-auto-host-rewrite), which does not affect if the policy routes to a static IP. To preserve 0.8.x behavior, you can use the `set_request_headers` option to explicitly set the Host header. -# Since 0.8.0 - -## Breaking ### Unsupported platforms @@ -145,7 +148,7 @@ policy: :::warning -This changed was partially reverted in v0.7.2\. Session details like `user`, `email`, and `groups` can still be explicitly extracted by setting the [jwt_claims_header](../configuration/readme.md#jwt-claim-headers) configuration option. +This changed was partially reverted in v0.7.2\. Session details like `user`, `email`, and `groups` can still be explicitly extracted by setting the [jwt_claims_header](../reference/readme.md#jwt-claim-headers) configuration option. ::: @@ -368,8 +371,9 @@ Usage of the POLICY_FILE envvar is no longer supported. Support for file based p The configuration variable [Authenticate Internal Service URL] must now be a valid [URL](https://golang.org/pkg/net/url/#URL) type and contain both a hostname and valid `https` schema. -[authenticate internal service url]: ../configuration/readme.md#authenticate-service-url -[cache service docs]: ../configuration/readme.md#cache-service -[policy]: ../configuration/readme.md#policy -[split service example]: ../configuration/examples.md#distinct-services +[authenticate internal service url]: ../reference/readme.md#authenticate-service-url +[cache service docs]: ../reference/readme.md#cache-service +[identity provider service account]: ../reference/readme.md#identity-provider-service-account +[policy]: ../reference/readme.md#policy [storage backend configuration here]: ../reference/readme.md#cache-service +[storage backend types]: ../reference/readme.md#data-broker-storage-type diff --git a/docs/guides/ad-guard.md b/docs/guides/ad-guard.md index 427aae3dd..e3bdf98e4 100644 --- a/docs/guides/ad-guard.md +++ b/docs/guides/ad-guard.md @@ -5,12 +5,13 @@ meta: - name: keywords content: pomerium identity-access-proxy adguard ad-guard pi-hole piehole description: >- - This guide covers how to add authentication and authorization to a hosted, fully, online instance of adguard. + This guide covers how to add authentication and authorization to a hosted, + fully, online instance of adguard. --- # Securing AdGuard Home -This guide covers how to add authentication and authorization to an instance of AdGuard while giving us a great excuse to demonstrate how to use Pomerium's [add headers](../docs/configuration/readme.md) functionality to **transparently pass along basic authentication credentials to a downstream app**. +This guide covers how to add authentication and authorization to an instance of AdGuard while giving us a great excuse to demonstrate how to use Pomerium's [add headers](../reference/readme.md) functionality to **transparently pass along basic authentication credentials to a downstream app**. ## What is AdGuard? @@ -75,4 +76,4 @@ Simply navigate to your new adguard instance (e.g. `https://adguard.domain.examp ![adguard dashboard](./img/adguard-dashboard.png) -[quick start]: ../docs/quick-start +[quick start]: ../docs/quick-start/readme.md diff --git a/docs/guides/cloud-run.md b/docs/guides/cloud-run.md index c6f288aa0..f64c8cc25 100644 --- a/docs/guides/cloud-run.md +++ b/docs/guides/cloud-run.md @@ -3,9 +3,10 @@ title: Cloud Run lang: en-US meta: - name: keywords - content: pomerium identity-access-proxy gcp google iap serverless cloudrun + content: pomerium identity-access-proxy gcp google iap serverless cloudrun description: >- - This guide covers how to deploy Pomerium to Cloud Run and use it to protect other endpoints via Authorization Headers. + This guide covers how to deploy Pomerium to Cloud Run and use it to protect + other endpoints via Authorization Headers. --- # Securing Cloud Run endpoints @@ -14,9 +15,9 @@ This recipe's sources can be found [on github](https://github.com/pomerium/pomer ## Background -Services on [Cloud Run](https://cloud.google.com/run) and other Google Cloud serverless products can be restricted to only permit access with a properly signed [bearer token](https://cloud.google.com/run/docs/authenticating/service-to-service). This allows requests from other services running in GCP or elsewhere to be securely authorized despite the endpoints being public. +Services on [Cloud Run](https://cloud.google.com/run) and other Google Cloud serverless products can be restricted to only permit access with a properly signed [bearer token](https://cloud.google.com/run/docs/authenticating/service-to-service). This allows requests from other services running in GCP or elsewhere to be securely authorized despite the endpoints being public. -These bearer tokens are not easily set in a browser session and must be refreshed on a regular basis, preventing them from being useful for end user authorization. Pomerium, however, can generate compatible tokens on behalf of end users and proxy the request to these services. +These bearer tokens are not easily set in a browser session and must be refreshed on a regular basis, preventing them from being useful for end user authorization. Pomerium, however, can generate compatible tokens on behalf of end users and proxy the request to these services. ## How it works @@ -25,29 +26,27 @@ These bearer tokens are not easily set in a browser session and must be refreshe - Publish DNS records for each protected application pointing to Pomerium - Configure Pomerium with appropriate policy and `enable_google_cloud_serverless_authentication` -The protected application delegates trust to a GCP service account which Pomerium runs as, and Pomerium performs user based authorization on a per route basis. This turns Pomerium into a bridge between a user-centric and service-centric authorization models. +The protected application delegates trust to a GCP service account which Pomerium runs as, and Pomerium performs user based authorization on a per route basis. This turns Pomerium into a bridge between a user-centric and service-centric authorization models. ## Pre-requisites -This guide assumes you have Editor access to a Google Cloud project which can be used for isolated testing, and a DNS zone which you are also able to control. DNS does not need to be inside Google Cloud for the example to work. +This guide assumes you have Editor access to a Google Cloud project which can be used for isolated testing, and a DNS zone which you are also able to control. DNS does not need to be inside Google Cloud for the example to work. ## Set Up -To deploy Pomerium to Cloud Run securely and easily, a special [image](https://console.cloud.google.com/gcr/images/pomerium-io/GLOBAL/pomerium) is available at `gcr.io/pomerium-io/pomerium-[version]-cloudrun`. It allows sourcing configuration from GCP Secrets Manager, and sets some defaults for Cloud Run to keep configuration minimal. We will be leveraging it in this example to store IdP credentials. Our policy contains no secrets so we can place it directly in an ENV var. +To deploy Pomerium to Cloud Run securely and easily, a special [image](https://console.cloud.google.com/gcr/images/pomerium-io/GLOBAL/pomerium) is available at `gcr.io/pomerium-io/pomerium-[version]-cloudrun`. It allows sourcing configuration from GCP Secrets Manager, and sets some defaults for Cloud Run to keep configuration minimal. We will be leveraging it in this example to store IdP credentials. Our policy contains no secrets so we can place it directly in an ENV var. -[Dockerfile](https://github.com/pomerium/pomerium/blob/master/.github/Dockerfile-cloudrun) -Based on [vals-entrypoint](https://github.com/pomerium/vals-entrypoint) +[Dockerfile](https://github.com/pomerium/pomerium/blob/master/.github/Dockerfile-cloudrun) Based on [vals-entrypoint](https://github.com/pomerium/vals-entrypoint) -The image expects a config file at `/pomerium/config.yaml`. Set `VALS_FILES=[secretref]:/pomerium/config.yaml` and set any other -Pomerium Environment Variables directly or with secret refs such as `ref+gcpsecrets://PROJECT/SECRET(#/key])`. +The image expects a config file at `/pomerium/config.yaml`. Set `VALS_FILES=[secretref]:/pomerium/config.yaml` and set any other Pomerium Environment Variables directly or with secret refs such as `ref+gcpsecrets://PROJECT/SECRET(#/key])`. ### Config + Set up a config.yaml to contain your IdP credentials and secrets (config.yaml): <<< @/examples/cloudrun/config.yaml -Substitute `cloudrun.pomerium.io` for your own subdomain and your e-mail domain if -appropriate (policy.template.yaml): +Substitute `cloudrun.pomerium.io` for your own subdomain and your e-mail domain if appropriate (policy.template.yaml): <<< @/examples/cloudrun/policy.template.yaml @@ -59,7 +58,6 @@ Substitute `cloudrun.pomerium.io` for your own subdomain (zonefile.txt): Or set an equivalent CNAME in your DNS provider. - ## Deploy Ensure you have set a default project: @@ -74,7 +72,7 @@ glcoud config set default-project MYTESTPROJECT ### Overview -We should see two applications deployed. The `hello` app is our protected app, and pomerium is...Pomerium! +We should see two applications deployed. The `hello` app is our protected app, and pomerium is...Pomerium! ![Cloud Run Overview](./img/cloud-run/cloudrun-overview.png) @@ -86,7 +84,7 @@ Here are the domain mappings set up: ### Direct Access -Let's verify we cannot access the main application directly by visiting [https://hello-direct.cloudrun.pomerium.io](https://hello-direct.cloudrun.pomerium.io) +Let's verify we cannot access the main application directly by visiting ![Hello Direct Access](./img/cloud-run/hello-direct.png) @@ -94,7 +92,7 @@ You should see a 403 error because you do not have the proper credentials. ### Authenticated Access -Now let's access via [https://hello.cloudrun.pomerium.io](https://hello.cloudrun.pomerium.io) +Now let's access via We should get an auth flow through your IdP: @@ -114,4 +112,4 @@ You should see your identity header set: ![Hello](./img/cloud-run/headers.png) -See [getting user's identity](/docs/reference/getting-users-identity.html) for more details on using this header. \ No newline at end of file +See [getting user's identity](../docs/topics/getting-users-identity.md) for more details on using this header. diff --git a/docs/guides/kubernetes-dashboard.md b/docs/guides/kubernetes-dashboard.md index ca4a218a7..075bf1bb1 100644 --- a/docs/guides/kubernetes-dashboard.md +++ b/docs/guides/kubernetes-dashboard.md @@ -350,7 +350,7 @@ Whichever option you choose to go with, πŸŽ‰πŸΎπŸŽŠ **congratulations** πŸŽ‰ [creating sample users]: https://github.com/kubernetes/dashboard/blob/master/docs/user/access-control/creating-sample-user.md [dashboard ui]: https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/#deploying-the-dashboard-ui [dns01 challenge provider]: https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme/dns01/index.html -[forward-auth]: ../docs/topics/reference.html#forward-auth +[forward-auth]: ../reference/readme.md#forward-auth [helm install]: https://helm.sh/docs/using_helm/#installing-the-helm-client [helm]: https://helm.sh [homebrew]: https://brew.sh @@ -362,5 +362,5 @@ Whichever option you choose to go with, πŸŽ‰πŸΎπŸŽŠ **congratulations** πŸŽ‰ [nginx]: https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/ [securing your helm installation]: https://helm.sh/docs/using_helm/#securing-your-helm-installation [snap]: https://github.com/snapcrafters/helm -[with pomerium]: ../docs/topics/reference.html#forward-auth +[with pomerium]: ../reference/readme.md#forward-auth [your dashboard]: http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/#/login diff --git a/docs/guides/vs-code-server.md b/docs/guides/vs-code-server.md index c77cf818e..30987c7b0 100644 --- a/docs/guides/vs-code-server.md +++ b/docs/guides/vs-code-server.md @@ -3,9 +3,12 @@ title: VS Code Server lang: en-US meta: - name: keywords - content: pomerium identity-access-proxy visual-studio-code visual studio code authentication authorization + content: >- + pomerium identity-access-proxy visual-studio-code visual studio code + authentication authorization description: >- - This guide covers how to add authentication and authorization to a hosted, fully, online instance of visual studio code. + This guide covers how to add authentication and authorization to a hosted, + fully, online instance of visual studio code. --- # Securing Visual Studio Code Server @@ -18,9 +21,9 @@ This guide covers using Pomerium to secure an instance of [Visual Studio Code Se [Visual Studio Code] is an open source code editor by Microsoft that has become [incredibly popular](https://insights.stackoverflow.com/survey/2019#technology-_-most-popular-development-environments) in the last few years. For many developers, [Visual Studio Code] hits the sweet spot between no frills editors like vim/emacs and full feature IDE's like Eclipse and IntelliJ. VS Code offers some of the creature comforts like intellisense, git integration, and plugins, while staying relatively lightweight. -One of the interesting attributes of [Visual Studio Code] is that it is built on the [Electron]() framework which uses a headless instance of Chrome rendered as a desktop application. It didn't take long for folks to realize that if we already had this great IDE written in Javascript, it may be possible to make [Visual Studio Code] run remotely. +One of the interesting attributes of [Visual Studio Code] is that it is built on the [Electron](https://en.wikipedia.org/wiki/Electron_(software_framework)) framework which uses a headless instance of Chrome rendered as a desktop application. It didn't take long for folks to realize that if we already had this great IDE written in Javascript, it may be possible to make [Visual Studio Code] run remotely. -> "Any application that can be written in JavaScript, will eventually be written in JavaScript." β€” [Jeff Atwood](https://blog.codinghorror.com/the-principle-of-least-power/) +> "Any application that can be written in JavaScript, will eventually be written in JavaScript." -- [Jeff Atwood](https://blog.codinghorror.com/the-principle-of-least-power/) ### VS Code Server @@ -116,9 +119,9 @@ v0.2.0+e1c00b1 Happy remote hacking!!!😁 -[visual studio code server]: https://github.com/cdr/code-server -[visual studio code]: https://code.visualstudio.com/ -[synology nas]: ../docs/quick-start/synology.md -[quick start]: ../docs/quick-start [integrated terminal]: https://code.visualstudio.com/docs/editor/integrated-terminal [path]: https://en.wikipedia.org/wiki/PATH_(variable) +[quick start]: ../docs/quick-start +[synology nas]: ../docs/quick-start/synology.md +[visual studio code]: https://code.visualstudio.com/ +[visual studio code server]: https://github.com/cdr/code-server diff --git a/docs/reference/readme.md b/docs/reference/readme.md index fe3e68cf9..fb4c87d2e 100644 --- a/docs/reference/readme.md +++ b/docs/reference/readme.md @@ -490,7 +490,7 @@ storage_operation_duration_ms | Histogram | Storage operation du #### Envoy Proxy Metrics -As of `v0.9`, Pomerium uses [envoy proxy](https://www.envoyproxy.io/) for the data plane. Proxy related metrics are sourced from envoy, and use envoy's internal [stats data model](https://www.envoyproxy.io/docs/envoy/latest/operations/stats_overview). Please see Envoy's documentation for information about specific metrics. +As of `v0.9`, Pomerium uses [envoy](https://www.envoyproxy.io/) for the data plane. As such, proxy related metrics are sourced from envoy, and use envoy's internal [stats data model](https://www.envoyproxy.io/docs/envoy/latest/operations/stats_overview). Please see Envoy's documentation for information about specific metrics. All metrics coming from envoy will be labeled with `service="pomerium"` or `service="pomerium-proxy"`, depending if you're running all-in-one or distributed service mode. @@ -995,7 +995,7 @@ Requires setting [Google Cloud Serverless Authentication Service Account](./#goo Use this token to authenticate requests to a Kubernetes API server. -Pomerium will [https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation](impersonate) the Pomerium user's identity, and Kubernetes RBAC can be applied to IdP user and groups. +Pomerium will [impersonate](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) the Pomerium user's identity, and Kubernetes RBAC can be applied to IdP user and groups. ### Path @@ -1262,7 +1262,7 @@ If no certificate is specified, one will be generated and the base64'd public ke [letsencrypt]: https://letsencrypt.org/ [oidc rfc]: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest [script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh -[signed headers]: ./signed-headers.md +[signed headers]: ../docs/topics/getting-users-identity.md [toml]: https://en.wikipedia.org/wiki/TOML [yaml]: https://en.wikipedia.org/wiki/YAML [Elliptic Curve]: https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations#Generating_EC_Keys_and_Parameters diff --git a/package.json b/package.json index d25f3cd97..fc22e8da4 100644 --- a/package.json +++ b/package.json @@ -3,12 +3,14 @@ "@vuepress/plugin-blog": "1.9.2", "@vuepress/plugin-google-analytics": "1.5.2", "vuepress": "1.5.2", + "vuepress-plugin-check-md": "^0.0.2", "vuepress-plugin-mailchimp": "1.4.2", "vuepress-plugin-sitemap": "2.3.1" }, "scripts": { "docs:dev": "vuepress dev docs", - "docs:build": "vuepress build docs" + "docs:build": "vuepress build docs", + "docs:check-md": "vuepress check-md" }, "dependencies": { "esm": "3.2.25"