Skip to content

Commit 6d7a6cc

Browse files
calebdoxseycalebdoxsey
committed
add documentation for bearer_token_format and idp_access_token_allowed_audiences
1 parent 1a21d25 commit 6d7a6cc

5 files changed

+170
-0
lines changed

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

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
id: bearer-token-format
3+
title: Bearer Token Format
4+
description: |
5+
Bearer token format controls how HTTP bearer token authentication is handled.
6+
keywords:
7+
- reference
8+
- Bearer Token Format
9+
pagination_prev: null
10+
pagination_next: null
11+
toc_max_heading_level: 2
12+
---
13+
14+
import Tabs from '@theme/Tabs';
15+
import TabItem from '@theme/TabItem';
16+
17+
# Bearer Token Format
18+
19+
## Summary
20+
21+
**Bearer Token Format** controls how HTTP bearer token authentication is handled. There are 3 possible options: `default`, `idp_access_token` and `idp_identity_token`.
22+
23+
HTTP bearer tokens are tokens stored in the `Authorization` header prefixed by `Bearer `:
24+
25+
```text
26+
GET / HTTP/1.1
27+
Authorization: Bearer Token
28+
```
29+
30+
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.
31+
32+
Currently only [Microsoft Entra](../../integrations/user-identity/azure) is supported with this option.
33+
34+
This option can also be configured at the route-level.
35+
36+
## Additional Headers
37+
38+
Pomerium also always supports passing IdP access and identity tokens via the following headers (replacing `<TOKEN>` with the issued token):
39+
40+
- `X-Pomerium-IDP-Access-Token: <TOKEN>`
41+
- `Authorization: Pomerium-IDP-Access-Token <TOKEN>`
42+
- `Authorization: Bearer Pomerium-IDP-Access-Token-<TOKEN>`
43+
- `X-Pomerium-IDP-Identity-Token: <TOKEN>`
44+
- `Authorization: Pomerium-IDP-Identity-Token <TOKEN>`
45+
- `Authorization: Bearer Pomerium-IDP-Identity-Token-<TOKEN>`
46+
47+
## How to Configure
48+
49+
<Tabs>
50+
<TabItem value="Core" label="Core">
51+
52+
| **Config file keys** | **Environment variables** | **Type** | **Default** |
53+
| :-------------------- | :------------------------ | :------- | :---------- |
54+
| `bearer_token_format` | `BEARER_TOKEN_FORMAT` | `string` | `default` |
55+
56+
### Examples
57+
58+
```yaml
59+
bearer_token_format: idp_access_token
60+
```
61+
62+
```bash
63+
BEARER_TOKEN_FORMAT=idp_access_token
64+
```
65+
66+
### Options
67+
68+
- `default`
69+
- `idp_access_token`
70+
- `idp_identity_token`
71+
72+
</TabItem>
73+
<TabItem value="Enterprise" label="Enterprise">
74+
75+
Set **Bearer Token Format** under **Proxy** settings in the Console:
76+
77+
![Set bearer token format in the Console](./img/global-settings/bearer-token-format.png)
78+
79+
</TabItem>
80+
<TabItem value="Kubernetes" label="Kubernetes">
81+
82+
```yaml
83+
bearerTokenFormat: idp_access_token
84+
```
85+
86+
See [Kubernetes - Global Configuration](/docs/deploy/k8s/configure) for more information.
87+
88+
</TabItem>
89+
</Tabs>

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

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
id: idp-access-token-allowed-audiences
3+
title: IdP Access Token Allowed Audiences
4+
description: |
5+
IdP access token allowed audiences controls how the audience claim of an incoming IdP-issued access token is validated.
6+
keywords:
7+
- reference
8+
- IdP Access Token Allowed Audiences
9+
pagination_prev: null
10+
pagination_next: null
11+
toc_max_heading_level: 2
12+
---
13+
14+
import Tabs from '@theme/Tabs';
15+
import TabItem from '@theme/TabItem';
16+
17+
# IdP Access Token Allowed Audiences
18+
19+
## Summary
20+
21+
**IdP Access Token Allowed Audiences** controls how the audience claim of an incoming IdP-issued access token is validated.
22+
23+
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.
24+
25+
This option can also be configured at the route-level.
26+
27+
## How to Configure
28+
29+
<Tabs>
30+
<TabItem value="Core" label="Core">
31+
32+
| **Config file keys** | **Environment variables** | **Type** |
33+
| :-- | :-- | :-- |
34+
| `idp_access_token_allowed_audiences` | `IDP_ACCESS_TOKEN_ALLOWED_AUDIENCES` | Array of strings |
35+
36+
### Examples
37+
38+
```yaml
39+
idp_access_token_allowed_audiences:
40+
- https://sts.windows.net/f42bce3b-671c-4162-b24c-00ecc7641897/
41+
- https://login.microsoftonline.com/f42bce3b-671c-4162-b24c-00ecc7641897/
42+
```
43+
44+
</TabItem>
45+
<TabItem value="Enterprise" label="Enterprise">
46+
47+
Set **IdP Access Token Allowed Audiences** under **Authenticate** settings in the Console:
48+
49+
![Set **IdP Access Token Allowed Audiences** in the Console](./img/global-settings/idp-access-token-allowed-audiences.png)
50+
51+
</TabItem>
52+
<TabItem value="Kubernetes" label="Kubernetes">
53+
54+
```yaml
55+
idpAccessTokenAllowedAudiences:
56+
- https://sts.windows.net/f42bce3b-671c-4162-b24c-00ecc7641897/
57+
- https://login.microsoftonline.com/f42bce3b-671c-4162-b24c-00ecc7641897/
58+
```
59+
60+
See [Kubernetes - Global Configuration](/docs/deploy/k8s/configure) for more information.
61+
62+
</TabItem>
63+
</Tabs>

‎content/docs/reference/img/global-settings/bearer-token-format.png

261 KB
Loading

‎content/docs/reference/img/global-settings/idp-access-token-allowed-audiences.png

197 KB
Loading

‎content/docs/reference/reference.json

+18
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,15 @@
114114
"type": "string",
115115
"short_description": ""
116116
},
117+
"bearer-token-format": {
118+
"id": "bearer-token-format",
119+
"title": "Bearer Token Format",
120+
"path": "/bearer-token-format",
121+
"services": ["authorize", "proxy"],
122+
"type": "string",
123+
"description": "Bearer Token Format controls how HTTP bearer token authentication is handled.",
124+
"short_description": "Bearer Token Format controls how HTTP bearer token authentication is handled."
125+
},
117126
"branding-settings": {
118127
"id": "branding",
119128
"title": "Branding Settings",
@@ -404,6 +413,15 @@
404413
"services": [],
405414
"type": ""
406415
},
416+
"idp-access-token-allowed-audiences": {
417+
"id": "idp-access-token-allowed-audiences",
418+
"title": "IDP Access Token Allowed Audiences",
419+
"path": "/idp-access-token-allowed-audiences",
420+
"description": "IdP Access Token Allowed Audiences controls how the audience claim of an incoming IdP-issued access token is validated.",
421+
"short_description": "IdP Access Token Allowed Audiences controls how the audience claim of an incoming IdP-issued access token is validated.",
422+
"services": ["authenticate"],
423+
"type": "string[]"
424+
},
407425
"grpc-settings": {
408426
"id": "grpc-settings",
409427
"title": "gRPC Settings",

0 commit comments

Comments
 (0)