pomerium · Dec 7, 2023
diff --git a/‎content/docs/courses.mdx
+62 b/‎content/docs/courses.mdx
+62
diff --git a/‎content/docs/courses/fundamentals/_category_.json
+3 b/‎content/docs/courses/fundamentals/_category_.json
+3
diff --git a/‎content/docs/courses/fundamentals/advanced-policies.md
+186 b/‎content/docs/courses/fundamentals/advanced-policies.md
+186
@@ -0,0 +1,62 @@
+---
+title: Pomerium Fundamentals
+id: courses
+sidebar_label: Courses
+description: Welcome to Pomerium Fundamentals, a series of courses designed to teach you the fundamentals of Pomerium so you can secure your applications with confidence.
+---
+
+Welcome to **Pomerium Fundamentals**, a series of courses designed to teach you the basics of Pomerium so you can secure your apps with confidence.
+
+Each course provides a structured approach to learning how Pomerium works. There are 10 courses in all.
+
+Head to [**Get Started**](/docs/courses/fundamentals/get-started) to get a Pomerium instance up and running. From there, you'll add on to your configuration file in each tutorial.
+
+Below, we’ve included some background information about Pomerium and reverse proxies (if you're not unfamiliar).
+
+## Reverse Proxies: a Primer
+
+### What is a Reverse Proxy?
+
+A reverse proxy is a server that sits between a client (like your browser) and an application’s origin server. When a client sends a request to an application behind a reverse proxy, the proxy receives the request before forwarding it to the origin server. When the origin server responds, the reverse proxy receives the request before sending it back to the client.
+
+This model affords several benefits:
+
+#### **Security**
+
+Because reverse proxies sit in front of an application’s origin server, the origin server’s IP address is hidden. If a malicious attacker attempts to overload or compromise the origin server, the reverse proxy would be targeted instead.
+
+#### **Load Balancing**
+
+You can use reverse proxies in your load balancing strategy to distribute traffic to available, healthy servers. So, if a website experiences high volumes of traffic, the reverse proxy can distribute traffic to a healthy server so that no single server is overloaded.
+
+#### **Transport Layer Security (TLS)**
+
+TLS encryption is computationally expensive for an origin server. A reverse proxy relieves the burden on the origin server because it can decrypt incoming requests and encrypt outgoing responses.
+
+Check out these posts to learn more:
+
+- [Proxy vs. Reverse Proxy](https://www.pomerium.com/blog/proxy-vs-reverse-proxy/)
+- [Zero Trust](/docs/concepts/zero-trust)
+
+## Pomerium Architecture
+
+To use Pomerium effectively, it helps to understand how Pomerium communicates with clients, identity providers, and upstream applications.
+
+### Request Lifecycle
+
+This diagram illustrates how Pomerium handles client requests to access upstream applications:
+
+![The request lifecyle](./internals/img/architecture/pomerium-request-flow.svg)
+
+Head to our [Architecture](/docs/internals/architecture) page to see these steps in detail and to learn more about how Pomerium at a system and component level.
+
+## Pomerium Terminology
+
+You’ll come across a lot of reverse proxy terminology in our documentation and guided tutorials that may not be intuitive or understandable at first.
+
+Below are are a few terms you should know:
+
+- **Resource**, **Asset**, **Application**, or **Service**: These terms all essentially represent the same thing: a sensitive destination within your private network that you want to secure behind Pomerium. We typically try not to use “resource” or “asset” because, well, they can mean different things depending on the context.
+- **Downstream** and **Upstream**: Pomerium sits between a client and a web app or service. If Pomerium is in the middle, then the client is “downstream” of Pomerium, and the protected app or service is “upstream” of Pomerium.
+
+See our [Glossary](/docs/internals/glossary) to review more terms.
@@ -0,0 +1,3 @@
+{
+  "label": "Fundamentals"
+}
@@ -0,0 +1,186 @@
+---
+id: advanced-policies
+title: Build Advanced Policies
+description: In lesson 5, you'll learn how to build advanced policies.
+keywords: [pomerium, reverse proxy, authorization policy, advanced policies]
+sidebar_label: 5. Advanced Policies
+sidebar_position: 5
+---
+
+# Build Advanced Policies
+
+In this guide, you’ll learn how to build **Advanced Policies** with Pomerium.
+
+:::note **Before You Start**
+
+Make sure you’ve completed the following tutorials:
+
+- [**Get Started**](/docs/courses/fundamentals/get-started)
+- [**Build a Simple Route**](/docs/courses/fundamentals/build-routes)
+- [**Build a Simple Policy**](/docs/courses/fundamentals/build-policies)
+- [**Identity Verification with JWTs**](/docs/courses/fundamentals/jwt-verification)
+
+Each tutorial builds on the same configuration files. In this tutorial, you’ll add complexity to your authorization policy.
+
+:::
+
+## What’s an advanced policy?
+
+An “advanced policy” usually means the policy includes:
+
+- Chaining policy blocks
+- Additional operators, criteria, and matchers
+
+For example, the policy below will only grant access if a user’s email address includes an `example.com` domain:
+
+```yaml
+policy:
+  allow:
+    and:
+      - domain:
+          is: example.com
+```
+
+But, with Pomerium Policy Language (PPL), you can build richer policies that use all sorts of context to control access to upstream applications.
+
+:::info **Establishing house rules**
+
+Think of it like this: you have a dog, and obviously you normally let your dog in the house. But what if your dog was sprayed by a skunk? Suddenly the “allow my dog in the house” policy needs additional caveats. Advanced policies allow you to have better policy logic than what you currently have in your configuration file.
+
+:::
+
+### Evaluate claims
+
+Let’s extend the policy above to include a claim from your JWT. If a user doesn’t have the matching claim in their JWT, Pomerium will deny the user access.
+
+1. **Get the value of the** `Name` **claim**
+
+While running your Docker containers, access the Verify service. Under **Signed Identity Token**, you’ll see a list of claims:
+
+![JWT claims listed on a web page from the Verify service](../img/jwt-verification/01-jwt-claims.png)
+
+Find the **Name** claim and copy the value.
+
+2. **Update your policy**
+
+Right now, your policy consists of one `allow` block with the `and` logical operator.
+
+Change `and` to `or`.
+
+```yaml
+policy:
+  allow:
+    or:
+      - domain:
+          is: example.com
+```
+
+The `or` operator grants access if either of two criteria are true.
+
+Right now, you only have one criterion: `domain`.
+
+Let’s add a second criterion, `claim`, and add it to the same policy block:
+
+```yaml
+policy:
+  allow:
+    or:
+      - domain:
+          is: example.com
+      - claim/Name: <"Your Name">
+```
+
+The `claim` operator requires a sub-path and the value of a JWT claim.
+
+You use `/` to delimit the beginning of the sub-path. In this case, the claim we want is `Name`. The value of `Name` is the name included in your JWT.
+
+Replace `Your Name` with the value in your JWT.
+
+Now, if a user’s email address includes `example.com` _or_ their claim matches the `Name` claim, Pomerium will grant the user access.
+
+### Add a deny rule
+
+Now, let’s add a second `deny` block to this policy. We will write a policy that denies access if a user’s email starts with `admin`.
+
+```yaml
+policy:
+  allow:
+    or:
+      - domain:
+          is: example.com
+      - claim/Name: <"Your Name">
+  deny:
+    and:
+      - email:
+          starts_with: admin
+```
+
+As is, this policy will deny access if a user’s email starts with `admin` (of course, you can change this value to whatever you want).
+
+Swap out the value with the beginning of your email address to test it out. This policy will still deny you access, even if your email’s domain and your JWT claim satisfy the `allow` block’s criteria.
+
+## Summary
+
+In this tutorial, you built more advanced policies that require multiple rules, logical operators, matchers, and criteria. Then, you attached these policies to your routes.
+
+Now, your Pomerium instance can evaluate claims and grant or deny access based on additional policies you’ve built! We’re teaching Pomerium to do exactly what you want it to do: Verify authorization whenever someone accesses a route.
+
+Organizations with multiple applications and services will want to know how they can scale Pomerium for their needs.
+
+In the next tutorial, you’ll learn how to build more complex routes!
+
+### Configuration file state
+
+By now, your configuration files should look similar to this:
+
+```yaml
+authenticate_service_url: https://authenticate.pomerium.app
+
+signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUVSNThaeDA2SHJXTW9PUTRaNjlMaDdMZUtFZW5TSmJZcHJvZ3V3TEl0blNvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFK1FtamZKQ2ovdzkrOUhrRDVlbTlIZFhRM3ViUEhIdWNOMTlNOXJxR05PeEpTRmR3VHgvaAphdVkvcVFSWWR0YVpnVEpEUWZSYVQ2Q1pPYndSYTl2TXNnPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
+
+routes:
+  - from: https://verify.localhost.pomerium.io
+    to: http://verify:8000
+    pass_identity_headers: true
+    policy:
+      allow:
+        or:
+          - domain:
+              is: example.com
+          - claim/Name: <"Your Name">
+      deny:
+        and:
+          - email:
+              starts_with: admin
+  - from: https://grafana.localhost.pomerium.io
+    to: http://grafana:3000
+    pass_identity_headers: true
+    policy:
+      allow:
+        and:
+          - domain:
+              is: example.com
+```
+
+Docker Compose:
+
+```yaml
+version: '3'
+services:
+  pomerium:
+    image: pomerium/pomerium:latest
+    volumes:
+      - ./config.yaml:/pomerium/config.yaml:ro
+    ports:
+      - 443:443
+  verify:
+    image: pomerium/verify:latest
+    expose:
+      - 8000
+    environment:
+      - JWKS_ENDPOINT=https://pomerium/.well-known/pomerium/jwks.json
+  grafana:
+    image: grafana/grafana:latest
+    ports:
+      - 3000:3000
+```
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "label": "Fundamentals"`
	`3`	`+}`