identity: add single page app example (#112)

calebdoxsey · cmo-pomerium · web-flow · commit 54df2782b3ac · 2022-08-29T15:17:42.000-06:00
* identity: add single page app example

* Update content/docs/topics/getting-users-identity.md

Co-authored-by: cmo-pomerium &lt;91488121+cmo-pomerium@users.noreply.github.com&gt;

* Update content/docs/topics/getting-users-identity.md

Co-authored-by: cmo-pomerium &lt;91488121+cmo-pomerium@users.noreply.github.com&gt;

Co-authored-by: cmo-pomerium &lt;91488121+cmo-pomerium@users.noreply.github.com&gt;
diff --git a/content/docs/topics/getting-users-identity.md b/content/docs/topics/getting-users-identity.md
@@ -14,17 +14,19 @@ To secure your app with signed headers, you'll need the following:
 
 ## Verification
 
-If a [signing key] is set, the user's associated identity information will be included in a signed attestation JWT that will be added to each requests's upstream header `X-Pomerium-Jwt-Assertion`. You should verify that the JWT contains at least the following claims:
-
- |  [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 the URL of your authentication domain e.g. `authenticate.corp.example`.    |
- |  `sub`   | Subject is the user's id. Can be used instead of the `X-Pomerium-Claim-Sub` header.       |
- | `email`  | Email is the user's email. Can be used instead of the `X-Pomerium-Claim-Email` header.    |
- | `groups` | Groups is the user's groups. Can be used instead of the `X-Pomerium-Claim-Groups` header. |
+If a [signing key] is set, the user's associated identity information will be included in a signed attestation JWT that will be added to each requests's upstream header `X-Pomerium-Jwt-Assertion`. The signed attestation JWT is also available at the special `/.pomerium/jwt` endpoint of any URL handled by Pomerium.
+
+You should verify that the JWT contains at least the following claims:
+
+|  [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 the URL of your authentication domain e.g. `authenticate.corp.example`.    |
+|  `sub`   | Subject is the user's id. Can be used instead of the `X-Pomerium-Claim-Sub` header.       |
+| `email`  | Email is the user's email. Can be used instead of the `X-Pomerium-Claim-Email` header.    |
+| `groups` | Groups is the user's groups. Can be used instead of the `X-Pomerium-Claim-Groups` header. |
 
 The attestation JWT's signature can be verified using the public key which can be retrieved at Pomerium's `/.well-known/pomerium/jwks.json` endpoint which lives on the authenticate service. A `jwks_uri` is useful when integrating with other systems like [istio](https://istio.io/docs/reference/config/security/istio.authentication.v1alpha1/). For example:
 
@@ -63,38 +65,77 @@ curl https://authenticate.int.example.com/.well-known/pomerium/jwks.json | jq
 }
 ```
 
+### Verification in a Single-Page Application
+
+A single-page javascript application can verify the JWT using a fetch to `/.pomerium/jwt` and a JWT library like [`jose`](https://github.com/panva/jose).
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script type="module">
+      import {
+        decodeJwt,
+        createRemoteJWKSet,
+        jwtVerify,
+      } from "https://cdn.skypack.dev/jose";
+
+      async function main() {
+        const result1 = await fetch("/.pomerium/jwt");
+        const jwt = await result1.text();
+        const claims = decodeJwt(jwt);
+        console.log("Unverified Claims:", claims);
+
+        const jwksURL =
+          "https://" + claims.iss + "/.well-known/pomerium/jwks.json";
+        const jwks = await createRemoteJWKSet(new URL(jwksURL));
+
+        const { payload } = await jwtVerify(jwt, jwks, {
+          audience: claims.aud,
+          issuer: claims.iss,
+        });
+        console.log("Verified Claims:", payload);
+      }
+
+      main();
+    </script>
+  </head>
+  <body></body>
+</html>
+```
+
 ### Manual verification
 
 Though you will very likely be verifying signed-headers programmatically in your application's middleware, and using a third-party JWT library, if you are new to JWT it may be helpful to show what manual verification looks like.
 
-1. Provide pomerium with a base64 encoded Elliptic Curve ([NIST P-256] aka [secp256r1] aka prime256v1) Private Key. In production, you'd likely want to get these from your KMS.
+1. Provide Pomerium with a base64 encoded Elliptic Curve ([NIST P-256] aka [secp256r1] aka prime256v1) Private Key. In production, you'd likely want to get these from your KMS.
 
-  ```bash
-  openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
-  openssl ec -in ec_private.pem -pubout -out ec_public.pem
-  # careful! this will output your private key in terminal
-  cat ec_private.pem | base64
-  ```
+   ```bash
+   openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
+   openssl ec -in ec_private.pem -pubout -out ec_public.pem
+   # careful! this will output your private key in terminal
+   cat ec_private.pem | base64
+   ```
 
-  Copy the base64 encoded value of your private key to `pomerium-proxy`'s environmental configuration variable `SIGNING_KEY`.
+   Copy the base64 encoded value of your private key to `pomerium-proxy`'s environmental configuration variable `SIGNING_KEY`.
 
-  ```bash
-  SIGNING_KEY=ZxqyyIPPX0oWrrOwsxXgl0hHnTx3mBVhQ2kvW1YB4MM=
-  ```
+   ```bash
+   SIGNING_KEY=ZxqyyIPPX0oWrrOwsxXgl0hHnTx3mBVhQ2kvW1YB4MM=
+   ```
 
 1. Reload `pomerium-proxy`. Navigate to httpbin (by default, `https://httpbin.corp.${YOUR-DOMAIN}.com`), and login as usual. Click **request inspection**. Select `/headers`. Click **try it out** and then **execute**. You should see something like the following.
 
-  ![httpbin displaying jwt headers](./img/inspect-headers.png)
+   ![httpbin displaying jwt headers](./img/inspect-headers.png)
 
 1. `X-Pomerium-Jwt-Assertion` is the signature value. It's less scary than it looks and basically just a compressed, json blob as described above. Navigate to [jwt.io] which provides a helpful GUI to manually verify JWT values.
 
 1. Paste the value of `X-Pomerium-Jwt-Assertion` header token into the `Encoded` form. You should notice that the decoded values look much more familiar.
 
-  ![httpbin displaying decoded jwt](./img/verifying-headers-1.png)
+   ![httpbin displaying decoded jwt](./img/verifying-headers-1.png)
 
 1. Finally, we want to cryptographically verify the validity of the token. To do this, we will need the signer's public key. You can simply copy and past the output of `cat ec_public.pem`.
 
-  ![httpbin displaying verified jwt](./img/verifying-headers-2.png)
+   ![httpbin displaying verified jwt](./img/verifying-headers-2.png)
 
 **Voila!** Hopefully walking through a manual verification has helped give you a better feel for how signed JWT tokens are used as a secondary validation mechanism in pomerium.
 
