docs: Cloud Run / GCP Serverless (#1101)

* Add GCP Serverless and Cloud Run docs

docs/.vuepress/config.js

@@ -150,7 +150,7 @@ module.exports = {
 
           collapsable: false,
           sidebarDepth: 1,
-          children: ["", "ad-guard", "vs-code-server", "kubernetes", "argo", "mtls"],
+          children: ["", "ad-guard", "cloud-run", "vs-code-server", "kubernetes", "argo", "mtls"],
         },
       ],
       "/enterprise/": [

docs/configuration/readme.md

@@ -877,6 +877,18 @@ Allowed users is a collection of whitelisted users to authorize for a given rout
 
 Allow unauthenticated HTTP OPTIONS requests as [per the CORS spec](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Preflighted_requests).
 
+
+### Enable Google Cloud Serverless Authentication
+
+- Environmental Variable: `ENABLE_GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION`
+- Config File Key: `enable_google_cloud_serverless_authentication`
+- Type: `bool`
+- Default: `false`
+
+Enable sending a signed [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) to upstream GCP services.
+
+Requires setting [Google Cloud Serverless Authentication Service Account](./#google-cloud-serverless-authentication-service-account) or running Pomerium in an environment with a GCP service account present in default locations.
+
 ### From
 
 - `yaml`/`json` setting: `from`
@@ -1083,6 +1095,17 @@ When enabled, this option will pass the identity headers to the downstream appli
 
 Authenticate Service URL is the externally accessible URL for the authenticate service.
 
+### Google Cloud Serverless Authentication Service Account
+
+- Environmental Variable: `GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION_SERVICE_ACCOUNT`
+- Config File Key: `google_cloud_serverless_authentication_service_account`
+- Type: [base64 encoded] `string`
+- Optional
+
+Manually specify the service account credentials to support GCP's [Authorization Header](https://cloud.google.com/run/docs/authenticating/service-to-service) format.
+
+If unspecified, will default to ambient credentials in the default locations searched by the Google SDK.  This includes GCE metadata server tokens.
+
 ### Signing Key
 
 - Environmental Variable: `SIGNING_KEY`
@@ -1126,3 +1149,4 @@ If no certificate is specified, one will be generated and the base64'd public ke
 [signed headers]: ./signed-headers.md
 [toml]: https://en.wikipedia.org/wiki/TOML
 [yaml]: https://en.wikipedia.org/wiki/YAML
+

docs/recipes/cloud-run.md

@@ -0,0 +1,117 @@
+---
+title: Cloud Run
+lang: en-US
+meta:
+  - name: keywords
+    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.
+---
+
+# Securing Cloud Run endpoints
+
+This recipe's sources can be found [on github](https://github.com/pomerium/pomerium/tree/master/examples/cloudrun)
+
+## 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.
+
+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
+
+- Add an IAM policy delegating `roles/run.invoker` permissions to a service account
+- Run Pomerium with access to a key for the corresponding service account
+- 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.
+
+## 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.
+
+## 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.  
+
+[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])`.
+
+### 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):
+
+<<< @/examples/cloudrun/policy.template.yaml
+
+### DNS
+
+Substitute `cloudrun.pomerium.io` for your own subdomain (zonefile.txt):
+
+<<< @/examples/cloudrun/zonefile.txt
+
+Or set an equivalent CNAME in your DNS provider.
+
+
+## Deploy
+
+Ensure you have set a default project:
+
+```shell
+glcoud config set default-project MYTESTPROJECT
+```
+
+<<< @/examples/cloudrun/deploy.sh
+
+## Results
+
+### Overview
+
+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)
+
+Notice that Pomerium allows unauthenticated access, but `hello` does not.
+
+Here are the domain mappings set up:
+
+![Cloud Run Domains](./img/cloud-run/cloudrun-domains.png)
+
+### 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)
+
+![Hello Direct Access](./img/cloud-run/hello-direct.png)
+
+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)
+
+We should get an auth flow through your IdP:
+
+![Hello Sign In](./img/cloud-run/hello-signin.png)
+
+And a hello page:
+
+![Hello](./img/cloud-run/hello-success.png)
+
+### Non-GCP Applications
+
+If your target application is not running on GCP, you can also perform your own header validation.
+
+Browse to [https://httpbin.cloudrun.pomerium.io](https://httpbin.cloudrun.pomerium.io/headers)
+
+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.

docs/recipes/readme.md

@@ -3,6 +3,7 @@
 This section contains applications, and scenario specific guides for Pomerium.
 
 - The [ad-guard](./ad-guard.md) recipe demonstrates how pomerium can be used to augment web applications that only support simplistic authorization mechanisms like basic-auth with single-sign-on driven access policy.
+- The [Cloud Run](./cloud-run.md) recipe demonstrates deploying pomerium to Google Cloud Run as well as using it to Authorize users to protected Cloud Run endpoints.
 - The [kubernetes](./kubernetes.md) guide covers how to add authentication and authorization to kubernetes dashboard using helm, and letsencrypt certificates. This guide also shows how third party reverse-proxies like nginx/traefik can be used in conjunction with pomerium using forward-auth.
 - The [visual studio code](./vs-code-server.md) guide demonstrates how pomerium can be used to add access control to third-party applications that don't ship with [fine-grained access control](https://github.com/cdr/code-server/issues/905).
 - The [argo](./argo.md) guide demonstrates how pomerium can be used to add access control to [Argo](https://argoproj.github.io/projects/argo).

examples/cloudrun/README.md

@@ -0,0 +1,33 @@
+# Pomerium on Cloud Run
+
+Run this demo with gcloud command line configured for your project.  The commands assume 
+all resources (Cloud Run, Cloud DNS, and Secret Manager) are in a single project.  
+
+We recommend a dedicated project that is easy to clean up.
+
+## Note
+When deployed to [Cloud Run](https://cloud.google.com/run), your protected application must authenticate requests from Pomerium
+by either inspecting the [X-Pomerium-Jwt-Assertion](https://www.pomerium.com/docs/reference/getting-users-identity.html),
+or [GCP Serverless Authorization](https://cloud.google.com/run/docs/authenticating/service-to-service) header.
+
+This demo includes a Cloud Run target configured to only accept requests from the Pomerium deployment.
+
+## Includes
+
+- Authentication and Authorization managed by pomerium
+- Custom Cloud Run domains
+- Cloud Run target
+- HTTPBin target
+
+## How
+
+- Update `config.yaml` for your e-mail address, if not using gmail/google.
+- Replace secrets in `config.yaml`.
+- Replace `cloudrun.pomerium.io` with your own domain.
+- Update your DNS
+- Deploy config.yaml to Secret Manager
+- Deploy the demo hello world app
+- Deploy pomerium with policy
+- Navigate to `https://httpbin.cloudrun.pomerium.io`
+- Navigate to `https://hello-direct.cloudrun.pomerium.io`
+- Navigate to `https://hello.cloudrun.pomerium.io`

examples/cloudrun/config.yaml

@@ -0,0 +1,7 @@
+# config.yaml
+authenticate_service_url: https://authn.cloudrun.pomerium.io
+shared_secret: XXXXXX
+cookie_secret: XXXXXX
+idp_provider: "google"
+idp_client_id: XXXXXX
+idp_client_secret: "XXXXXX"

examples/cloudrun/deploy.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Install gcloud beta
+gcloud components install beta
+
+# Capture current project number
+PROJECT=$(gcloud projects describe $(gcloud config get-value project) --format='get(projectNumber)')
+
+# Point a wildcard domain of *.cloudrun.pomerium.io to the cloudrun front end
+gcloud dns record-sets import --zone pomerium-io zonefile --zone-file-format
+
+# Deploy our protected application and associate a DNS name
+gcloud run deploy hello --image=gcr.io/cloudrun/hello --region us-central1 --platform managed --no-allow-unauthenticated
+gcloud run services add-iam-policy-binding hello --platform managed --region us-central1 \
+    --member=serviceAccount:${PROJECT}-compute@developer.gserviceaccount.com \
+    --role=roles/run.invoker
+gcloud beta run domain-mappings --platform managed --region us-central1 create --service=hello --domain hello-direct.cloudrun.pomerium.io
+
+# Rewrite policy file with unique 'hello' service URL
+HELLO_URL=$(gcloud run services describe hello --platform managed --region us-central1 --format 'value(status.address.url)') envsubst <policy.template.yaml >policy.yaml
+
+# Install our base configuration in a GCP secret
+gcloud secrets create --data-file config.yaml pomerium-config --replication-policy automatic
+
+# Grant the default compute account access to the secret
+gcloud secrets add-iam-policy-binding pomerium-config \
+    --member=serviceAccount:${PROJECT}-compute@developer.gserviceaccount.com \
+    --role=roles/secretmanager.secretAccessor
+
+# Deploy pomerium with policy and configuration references
+gcloud run deploy pomerium --region us-central1 --platform managed --allow-unauthenticated --max-instances 1 \
+    --image=gcr.io/pomerium-io/pomerium:v0.10.0-rc2-cloudrun \
+    --set-env-vars VALS_FILES="/pomerium/config.yaml:ref+gcpsecrets://${PROJECT}/pomerium-config",POLICY=$(base64 policy.yaml)
+
+# Set domain mappings for the protected routes and authenticate
+gcloud beta run domain-mappings --platform managed --region us-central1 create --service=pomerium --domain hello.cloudrun.pomerium.io
+gcloud beta run domain-mappings --platform managed --region us-central1 create --service=pomerium --domain authn.cloudrun.pomerium.io
+gcloud beta run domain-mappings --platform managed --region us-central1 create --service=pomerium --domain httpbin.cloudrun.pomerium.io

examples/cloudrun/policy.template.yaml

@@ -0,0 +1,11 @@
+# policy.template.yaml
+- from: https://hello.cloudrun.pomerium.io
+  to: ${HELLO_URL}
+  allowed_domains:
+    - gmail.com
+  enable_google_cloud_serverless_authentication: true
+- from: https://httpbin.cloudrun.pomerium.io
+  to: https://httpbin.org
+  pass_identity_headers: true
+  allowed_domains:
+    - gmail.com

examples/cloudrun/zonefile.txt

@@ -0,0 +1,2 @@
+; zonefile.txt
+*.cloudrun.pomerium.io. 18000 IN CNAME ghs.googlehosted.com.