diff --git a/content/docs/reference/bearer-token-format.mdx b/content/docs/reference/bearer-token-format.mdx new file mode 100644 index 000000000..f0a8dd685 --- /dev/null +++ b/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 `` with the issued token): + +- `X-Pomerium-IDP-Access-Token: ` +- `Authorization: Pomerium-IDP-Access-Token ` +- `Authorization: Bearer Pomerium-IDP-Access-Token-` +- `X-Pomerium-IDP-Identity-Token: ` +- `Authorization: Pomerium-IDP-Identity-Token ` +- `Authorization: Bearer Pomerium-IDP-Identity-Token-` + +## How to Configure + + + + +| **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` + + + + +Set **Bearer Token Format** under **Proxy** settings in the Console: + +![Set bearer token format in the Console](./img/global-settings/bearer-token-format.png) + + + + +```yaml +bearerTokenFormat: idp_access_token +``` + +See [Kubernetes - Global Configuration](/docs/deploy/k8s/configure) for more information. + + + diff --git a/content/docs/reference/idp-access-token-allowed-audiences.mdx b/content/docs/reference/idp-access-token-allowed-audiences.mdx new file mode 100644 index 000000000..2af9093b6 --- /dev/null +++ b/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 + + + + +| **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/ +``` + + + + +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) + + + + +```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. + + + diff --git a/content/docs/reference/img/global-settings/bearer-token-format.png b/content/docs/reference/img/global-settings/bearer-token-format.png new file mode 100644 index 000000000..c426d6c2d Binary files /dev/null and b/content/docs/reference/img/global-settings/bearer-token-format.png differ diff --git a/content/docs/reference/img/global-settings/idp-access-token-allowed-audiences.png b/content/docs/reference/img/global-settings/idp-access-token-allowed-audiences.png new file mode 100644 index 000000000..f84f9405f Binary files /dev/null and b/content/docs/reference/img/global-settings/idp-access-token-allowed-audiences.png differ diff --git a/content/docs/reference/reference.json b/content/docs/reference/reference.json index 5a9e12ad7..623617b61 100644 --- a/content/docs/reference/reference.json +++ b/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",