add documentation for bearer_token_format and idp_access_token_allowed_audiences

content/docs/reference/bearer-token-format.mdx

@@ -0,0 +1,89 @@
+---
+id: bearer-token-format
+title: Bearer Token Format
+description: |
+  Bearer token format controls how HTTP bearer token authentication is handled.
+keywords:
+  - reference
+  - Bearer Token Format
+pagination_prev: null
+pagination_next: null
+toc_max_heading_level: 2
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Bearer Token Format
+
+## Summary
+
+**Bearer Token Format** controls how HTTP bearer token authentication is handled. There are 3 possible options: `default`, `idp_access_token` and `idp_identity_token`.
+
+HTTP bearer tokens are tokens stored in the `Authorization` header prefixed by `Bearer `:
+
+```text
+GET / HTTP/1.1
+Authorization: Bearer Token
+```
+
+Pomerium's `default` behavior is to pass bearer tokens to upstream applications without interpreting them. Pomerium also supports creating sessions from tokens issued by an identity provider without needing to initiate an interactive login. If the `idp_access_token` option is used, then the bearer token will be interpreted as an IdP-issued access token. If the `idp_identity_token` option is used, then the bearer token will be interpreted as an IdP-issued identity token.
+
+Currently only [Microsoft Entra](../integrations/user-identity/azure) is supported with this option.
+
+This option can also be configured at the route-level.
+
+## Additional Headers
+
+Pomerium also always supports passing IdP access and identity tokens via the following headers (replacing `<TOKEN>` with the issued token):
+
+- `X-Pomerium-IDP-Access-Token: <TOKEN>`
+- `Authorization: Pomerium-IDP-Access-Token <TOKEN>`
+- `Authorization: Bearer Pomerium-IDP-Access-Token-<TOKEN>`
+- `X-Pomerium-IDP-Identity-Token: <TOKEN>`
+- `Authorization: Pomerium-IDP-Identity-Token <TOKEN>`
+- `Authorization: Bearer Pomerium-IDP-Identity-Token-<TOKEN>`
+
+## How to Configure
+
+<Tabs>
+<TabItem value="Core" label="Core">
+
+| **Config file keys**  | **Environment variables** | **Type** | **Default** |
+| :-------------------- | :------------------------ | :------- | :---------- |
+| `bearer_token_format` | `BEARER_TOKEN_FORMAT`     | `string` | `default`   |
+
+### Examples
+
+```yaml
+bearer_token_format: idp_access_token
+```
+
+```bash
+BEARER_TOKEN_FORMAT=idp_access_token
+```
+
+### Options
+
+- `default`
+- `idp_access_token`
+- `idp_identity_token`
+
+</TabItem>
+<TabItem value="Enterprise" label="Enterprise">
+
+Set **Bearer Token Format** under **Proxy** settings in the Console:
+
+![Set bearer token format in the Console](./img/global-settings/bearer-token-format.png)
+
+</TabItem>
+<TabItem value="Kubernetes" label="Kubernetes">
+
+```yaml
+bearerTokenFormat: idp_access_token
+```
+
+See [Kubernetes - Global Configuration](/docs/deploy/k8s/configure) for more information.
+
+</TabItem>
+</Tabs>

content/docs/reference/idp-access-token-allowed-audiences.mdx

@@ -0,0 +1,63 @@
+---
+id: idp-access-token-allowed-audiences
+title: IdP Access Token Allowed Audiences
+description: |
+  IdP access token allowed audiences controls how the audience claim of an incoming IdP-issued access token is validated.
+keywords:
+  - reference
+  - IdP Access Token Allowed Audiences
+pagination_prev: null
+pagination_next: null
+toc_max_heading_level: 2
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# IdP Access Token Allowed Audiences
+
+## Summary
+
+**IdP Access Token Allowed Audiences** controls how the audience claim of an incoming IdP-issued access token is validated.
+
+For [Microsoft Entra](../integrations/user-identity/azure) an access-token is a JWT with an audience claim. When the IdP Access Token Allowed Audiences option is set, the `aud` claim of the access token JWT must match one of the entries.
+
+This option can also be configured at the route-level.
+
+## How to Configure
+
+<Tabs>
+<TabItem value="Core" label="Core">
+
+| **Config file keys** | **Environment variables** | **Type** |
+| :-- | :-- | :-- |
+| `idp_access_token_allowed_audiences` | `IDP_ACCESS_TOKEN_ALLOWED_AUDIENCES` | Array of strings |
+
+### Examples
+
+```yaml
+idp_access_token_allowed_audiences:
+  - https://sts.windows.net/f42bce3b-671c-4162-b24c-00ecc7641897/
+  - https://login.microsoftonline.com/f42bce3b-671c-4162-b24c-00ecc7641897/
+```
+
+</TabItem>
+<TabItem value="Enterprise" label="Enterprise">
+
+Set **IdP Access Token Allowed Audiences** under **Authenticate** settings in the Console:
+
+![Set **IdP Access Token Allowed Audiences** in the Console](./img/global-settings/idp-access-token-allowed-audiences.png)
+
+</TabItem>
+<TabItem value="Kubernetes" label="Kubernetes">
+
+```yaml
+idpAccessTokenAllowedAudiences:
+  - https://sts.windows.net/f42bce3b-671c-4162-b24c-00ecc7641897/
+  - https://login.microsoftonline.com/f42bce3b-671c-4162-b24c-00ecc7641897/
+```
+
+See [Kubernetes - Global Configuration](/docs/deploy/k8s/configure) for more information.
+
+</TabItem>
+</Tabs>

content/docs/reference/reference.json

@@ -114,6 +114,15 @@
     "type": "string",
     "short_description": ""
   },
+  "bearer-token-format": {
+    "id": "bearer-token-format",
+    "title": "Bearer Token Format",
+    "path": "/bearer-token-format",
+    "services": ["authorize", "proxy"],
+    "type": "string",
+    "description": "Bearer Token Format controls how HTTP bearer token authentication is handled.",
+    "short_description": "Bearer Token Format controls how HTTP bearer token authentication is handled."
+  },
   "branding-settings": {
     "id": "branding",
     "title": "Branding Settings",
@@ -404,6 +413,15 @@
     "services": [],
     "type": ""
   },
+  "idp-access-token-allowed-audiences": {
+    "id": "idp-access-token-allowed-audiences",
+    "title": "IDP Access Token Allowed Audiences",
+    "path": "/idp-access-token-allowed-audiences",
+    "description": "IdP Access Token Allowed Audiences controls how the audience claim of an incoming IdP-issued access token is validated.",
+    "short_description": "IdP Access Token Allowed Audiences controls how the audience claim of an incoming IdP-issued access token is validated.",
+    "services": ["authenticate"],
+    "type": "string[]"
+  },
   "grpc-settings": {
     "id": "grpc-settings",
     "title": "gRPC Settings",