From 82c7d1ee7acd786c6be466befc1f5f99e2ed933c Mon Sep 17 00:00:00 2001
From: Travis Groth <travisgroth@users.noreply.github.com>
Date: Wed, 9 Dec 2020 12:16:13 -0500
Subject: [PATCH] docs: add allowed_idp_claims docs (#1665)

---
 docs/reference/readme.md     | 37 ++++++++++++++++++++++++++++++++++-
 docs/reference/settings.yaml | 38 ++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/docs/reference/readme.md b/docs/reference/readme.md
index e2faa4474..628b0d721 100644
--- a/docs/reference/readme.md
+++ b/docs/reference/readme.md
@@ -65,7 +65,7 @@ Enabling user impersonation allows administrators to impersonate other user acco
 - Type: `bool`
 - Optional
 
-Turning on autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS certificates from [Let's Encrypt][letsencrypt] which includes managed routes and the authenticate service. [Autocert Directory](./#autocert-directory) must be used with Autocert must have a place to persist, and share certificate data between services. Note that autocert also provides [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).
+Turning on autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS certificates from [Let's Encrypt][letsencrypt] which includes managed routes and the authenticate service.  [Autocert Directory](./#autocert-directory) must be used with Autocert must have a place to persist, and share certificate data between services. Note that autocert also provides [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).
 
 This setting can be useful in situations where you may not have Pomerium behind a TLS terminating ingress or proxy that is already handling your public certificates on your behalf.
 
@@ -975,6 +975,41 @@ Allowed domains is a collection of whitelisted domains to authorize for a given
 Allowed groups is a collection of whitelisted groups to authorize for a given route.
 
 
+### Allowed IdP Claims
+- `yaml`/`json` setting: `allowed_idp_claims`
+- Type: map of `strings` lists
+- Required
+
+Allowed IdP Claims is a collection of whitelisted claim key-value pairs to authorize for a given route.
+
+This is useful if your identity provider has extra information about a user that is not in the directory.  It can also be useful if you wish to use groups with the generic OIDC provider.
+
+Example:
+
+```yaml
+  - from: http://from.example.com
+    to: http://to.example.com
+    allowed_idp_claims:
+      family_name:
+        - Doe
+        - Smith
+```
+
+This policy would match users with the `family_name` claim containing `Smith` or `Doe`.
+
+Claims are represented as a map of strings to a list of values:
+
+```json
+{
+  "family_name": ["Doe"],
+  "given_name": ["John"]
+}
+```
+
+- Nested maps are flattened: `{ "a": { "b": ["c"] } }` becomes `{ "a.b": ["c"] }`
+- Values are always a list: `{ "a": "b" }` becomes `{ "a": ["b"] }`
+
+
 ### Allowed Users
 - `yaml`/`json` setting: `allowed_users`
 - Type: list of `string`
diff --git a/docs/reference/settings.yaml b/docs/reference/settings.yaml
index 4bd16c25c..77553673d 100644
--- a/docs/reference/settings.yaml
+++ b/docs/reference/settings.yaml
@@ -1087,6 +1087,44 @@ settings:
           - Example: `admins` , `support@company.com`
         doc: |
           Allowed groups is a collection of whitelisted groups to authorize for a given route.
+      - name: "Allowed IdP Claims"
+        keys: ["allowed_idp_claims"]
+        attributes: |
+          - `yaml`/`json` setting: `allowed_idp_claims`
+          - Type: map of `strings` lists
+          - Required
+        shortdoc: |
+          Authorize users by matching claims attached to a user's identity token by their identity provider
+        doc: |
+          Allowed IdP Claims is a collection of whitelisted claim key-value pairs to authorize for a given route.
+
+          This is useful if your identity provider has extra information about a user that is not in the directory.  It can also be useful if you wish to use groups with the generic OIDC provider.
+
+          Example:
+
+          ```yaml
+            - from: http://from.example.com
+              to: http://to.example.com
+              allowed_idp_claims:
+                family_name:
+                  - Doe
+                  - Smith
+          ```
+
+          This policy would match users with the `family_name` claim containing `Smith` or `Doe`.
+
+          Claims are represented as a map of strings to a list of values:
+
+          ```json
+          {
+            "family_name": ["Doe"],
+            "given_name": ["John"]
+          }
+          ```
+
+          - Nested maps are flattened: `{ "a": { "b": ["c"] } }` becomes `{ "a.b": ["c"] }`
+          - Values are always a list: `{ "a": "b" }` becomes `{ "a": ["b"] }`
+
       - name: "Allowed Users"
         keys: ["allowed_users"]
         attributes: |