3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-05-10 15:47:36 +02:00
Code Issues Projects Releases Packages Wiki Activity

DOCS: Document webauthn with device ID (#2830) (#2868)

Browse source 
* init device identity topic page

* add device options to PPL

* init device enrollment guide

* adjust for #2835 and crosslink

* tooltip in PPL on finding device ID

* sort and link matchers

* adjust terminology and crosslink

* standardize new topic name

* Apply suggestions from code review

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* rewrite device identity topic page

* rebase cleanup

* Apply suggestions from code review

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* add links from review with footer refs

* Apply suggestions from code review

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* rm errant newlines

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

Co-authored-by: Alex Fornuto <afornuto@pomerium.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
This commit is contained in:
backport-actions-token[bot] 2021-12-29 10:10:20 -08:00 • committed by GitHub
parent 6c7fdc2dfc
commit 992e33fc0c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 228 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/.vuepress/config.js
View file

@ -178,6 +178,7 @@ module.exports = {
children: [
"topics/certificates",
"topics/data-storage",
"topics/device-identity",
"topics/getting-users-identity",
"topics/original-request-context",
"topics/ppl",
@ -215,6 +216,7 @@ module.exports = {
"cloud-run",
"mtls",
"code-server",
"enroll-device",
"grafana",
"istio",
"jwt-verification",

80
docs/docs/topics/device-identity.md Normal file
View file

@ -0,0 +1,80 @@
---
title: Device Identity
description: >-
Learn about how WebAuthn is used to authenticate and authorize access using Device ID and state.
sidebarDepth: 1
---
# Device Identity
One of the core components of the zero-trust security model is **device identity**, which is the ability for a device to have a unique, unclonable identity string that can be authenticated and factored into access control decisions. This topic page covers the concept of device identity, and how it applies to the zero-trust model.
## Why Device Identity Is Important
The history of IT security has, until recently, mostly focused on user identity verification. In this model, access to a service is granted only after verifying a user's identity and authorization to that service. This was usually sufficient in scenarios where the user's access was physically limited to trusted devices in trusted physical and network spaces; a PC sitting in an office in the company headquarters on a local network, for example.
Hardware-backed device identity is becoming more widely discussed as more products begin to implement or require it across all tech industries. For example, Windows 11 generated a lot of news by [requiring TPM 2.0][win11-reqs], and Apple is taking steps to [eliminate passwords][apple-passkeys]:
| ![Verge Article Header and Apple Video Page](./img/verge-apple.png) |
|:--|
| **Sources:**<br />- <https://www.theverge.com/2021/6/25/22550376/microsoft-windows-11-tpm-chips-requirement-security><br/>- <https://developer.apple.com/videos/play/wwdc2021/10106/> |
Device identity protects a trusted user from accessing sensitive data from a potentially unsafe device, like their personal computer or phone. Think of it as similar to multi-factor authentication (**MFA**); where MFA covers "what you know" (password) and "who you are" (biometrics, face recognition, etc), device identity asks "is this device safe?" by confirming that the device you are using to access a system is trusted.
Device identity is similar but unique to MFA. Where MFA is an additional layer of protection on user identity, hardware-backed device identity can be used to enhance and augment authorization decisions beyond the initial authentication flow. Where MFA increases the trust-level of a user, device identity provides trust for the device being used. More importantly, it denies access for non-trusted, potentially insecure devices.
## What Is Device Identity
> When you remove "[the perimeter]" as the source of trust to your infrastructure, you must replace it with a level of trust for every person, **device**, and hop in the communication path. Where the other, more commonly implemented facets of zero-trust validates the user and traffic, device identity (through WebAuthn) validates the end user's device.
Device ID is a unique identifying key that can only be created by the specific combination of hardware and software present on a specific device. How this is accomplished is largely dependent on the tools available on the user hardware, which we've detailed below.
### Authenticated Device Types
Device identity is made possible through trusted execution environment (**TEE**) devices that provide a hardware-attested identity. The specific implementation of this general concept is different across the devices that provide device identity, but they generally fall into two categories: [secure enclaves and cross-platform security keys].
#### Secure Enclaves
Also called platform or internal authenticators, a secure enclave is physically bound to a specific computing device.
- TPM (Trusted Platform Module): These devices are usually built into a product's mainboard, or can be installed in devices with a TPM header, as shown [here][toms-hardware-tpm]. They include a small processor to carry out cryptographic functions on the device, instead of on the system's processor where it could be interfered with. Trust is usually derived from a private key or certificate signed by a trusted manufacture's certificate authority.
- Mobile devices: Most newer Apple and Android devices include a [Secure Enclave][apple-enclave] or [Hardware-backed Keystore][android-keystore]
#### Hardware Security Keys
Also known as cross-platform or roaming authenticators, these are authentication devices which can move with the user across different computers.
- FIDO U2F: This [open standard][fido-spec] is used by many products like Yubico's [Yubikey][yubikey-products] and Google's [Titan Security Key](https://support.google.com/titansecuritykey/answer/9115487?hl=en). They usually secure a private key used to decrypt information signed by an accessible public key.
::: tip Note
The nature of cross-platform keys mean they are not associated with a single end-user device. Pomerium policies can be written to allow these keys, or specified to only accept secure enclaves.
:::
## Implement Device Identity with Pomerium
Pomerium supports policies that use device identity since version [0.16.0](/docs/upgrading.md#policy-for-device-identity). We use the [Web Authentication][webauthn-api] (**WebAuthN**) API to bring authentication and authorization based on device identity into your security framework. Pomerium's device identity support enables users to register their devices, and administrators to enforce access to applications and services to a particular set of trusted devices.
To get started, review the following pages:
- [Pomerium Policy Language](/docs/topcics/ppl.md) to learn how to build policies that use device ID.
- [Enroll a Device](/guides/enroll-device.md) to teach end-users how to enroll devices on Pomerium.
- [pomerium/webauthn](https://github.com/pomerium/webauthn) on GitHub, our implementation of the WebAuthn specification.
## Looking Ahead: Device Posture
Even if access is restricted to known devices, what happens when a user is found to have a vulnerable OS or browser version? How can an administrator ensure their network is not exposed, and that the user's system is promptly patched and remediated? As secure enclave technologies evolve, **device posture** -- which is sometimes referred to as device state -- will play an increasingly important role in not only authorization decisions but also in helping to quickly remediate vulnerable corporate devices. Device posture is a more complex superset of device identity, with more information about the device and software being used to generate the resulting identifier.
Designing your security model to use device identity also primes your infrastructure to implement advanced security rules based on device posture down the road.
[android-keystore]: https://source.android.com/security/keystore
[apple-enclave]: https://support.apple.com/guide/security/secure-enclave-sec59b0b31ff/web
[apple-passkeys]: https://developer.apple.com/documentation/authenticationservices/public-private_key_authentication/supporting_passkeys
[fido-spec]: https://fidoalliance.org/specifications/
[secure enclaves and cross-platform security keys]: https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Platform_vs_Cross-Platform.html
[the perimeter]: https://www.microsoft.com/security/blog/2019/10/23/perimeter-based-network-defense-transform-zero-trust-model/
[toms-hardware-tpm]: https://www.tomshardware.com/reviews/tpm-trusted-platform-module-header,5766.html
[verge-tpm]: https://www.theverge.com/2021/6/25/22550376/microsoft-windows-11-tpm-chips-requirement-security
[webauthn-api]: https://www.w3.org/TR/webauthn-2/#registration-extension
[win11-reqs]: https://www.microsoft.com/en-us/windows/windows-11-specifications
[yubikey-products]: https://www.yubico.com/products/

BIN
docs/docs/topics/img/verge-apple.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 208 KiB

130
docs/docs/topics/ppl.md
View file

@ -75,65 +75,32 @@ allow:
PPL supports many different criteria:
| Criterion Name | Data Format | Description |
| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ---------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accept` | Anything. Typically `true`. | Always returns true, thus always allowing access. Equivalent to the [`allow_public_unauthenticated_access`] option. |
| `authenticated_user` | Anything. Typically `true`. | Always returns true for logged-in users. Equivalent to the [`allow_any_authenticated_user`] option. |
| `claim` | Anything. Typically a string. | Returns true if a token claim matches the supplied value **exactly**. The claim to check is determined via the sub-path. <br/> For example, `claim/family_name: Smith` matches if the user's `family_name` claim is `Smith`. |
| `cors_preflight` | Anything. Typically `true`. | Returns true if the incoming request uses the `OPTIONS` method and has both the `Access-Control-Request-Method` and `Origin` headers. Used to allow [CORS pre-flight requests]. |
| `domain` | String Matcher | Returns true if the logged-in user's email address domain (the part after `@`) matches the given value. |
| `email` | String Matcher | Returns true if the logged-in user's email address matches the given value. |
| `groups` | List Matcher | Returns true if the logged-in user is a member of the given group. |
| `http_method` | String Matcher | Returns true if the HTTP method matches the given value. |
| `http_path` | String Matcher | Returns true if the HTTP path matches the given value. |
| `device` | [Device matcher] | Returns true if the incoming request includes a valid device ID or type. |
| `domain` | [String Matcher] | Returns true if the logged-in user's email address domain (the part after `@`) matches the given value. |
| `email` | [String Matcher] | Returns true if the logged-in user's email address matches the given value. |
| `groups` | [List Matcher] | Returns true if the logged-in user is a member of the given group. |
| `http_method` | [String Matcher] | Returns true if the HTTP method matches the given value. |
| `http_path` | [String Matcher] | Returns true if the HTTP path matches the given value. |
| `invalid_client_certificate` | Anything. Typically `true`. | Returns true if the incoming request has an invalid client certificate. A default `deny` rule using this criterion is added to all Pomerium policies when an mTLS [client certificate authority] is set. |
| `pomerium_routes` | Anything. Typically `true`. | Returns true if the incoming request is for the special `.pomerium` routes. A default `allow` rule using this criterion is added to all Pomerium policies. |
| `reject` | Anything. Typically `true`. | Always returns false. The opposite of `accept`. |
| `user` | String Matcher | Returns true if the logged-in user's id matches the given value. |
| `user` | [String Matcher] | Returns true if the logged-in user's id matches the given value. |
[Pomerium Enterprise] supports all the open source criteria, but also supports these additional criteria:
| Criterion Name | Data Format | Description |
| -------------- | ------------------- | -------------------------------------------------------------------------------------- |
| `date` | Date Matcher | Returns true if the time of the request matches the constraints. |
| `day_of_week` | Day of Week Matcher | Returns true if the day of the request matches the constraints. |
| `time_of_day` | Time of Day Matcher | Returns true if the time of the request (for the current day) matches the constraints. |
| `date` | [Date Matcher] | Returns true if the time of the request matches the constraints. |
| `day_of_week` | [Day of Week Matcher] | Returns true if the day of the request matches the constraints. |
| `time_of_day` | [Time of Day Matcher] | Returns true if the time of the request (for the current day) matches the constraints. |
## Matchers
### String Matcher
A string matcher is an object with operators as keys. It supports the following operators: `contains`, `ends_with`, `is` and `starts_with`. For example:
```yaml
allow:
and:
- email:
starts_with: 'admin@'
```
### List Matcher
A list matcher is an object with operators as keys. It supports the following operators: `has`. For example:
```yaml
allow:
and:
- groups:
has: 'admin'
```
## Date Matcher
The date matcher is an object with operators as keys. It supports the following operators: `after` and `before`. The values are [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) date strings. `after` means that the time of the request must be after the supplied date and `before` means that the time of the request must be before the supplied date. For example:
```yaml
allow:
and:
- date:
after: 2020-01-02T16:20:00
before: 2150-01-02T16:20:00
```
## Day of Week Matcher
The day of week matcher is a **string**. The string can either be `*`, a comma-separated list of days, or a dash-separated list of days.
@ -148,6 +115,75 @@ The day of week matcher is a **string**. The string can either be `*`, a comma-s
- day_of_week: tue-fri
```
## Date Matcher
The date matcher is an object with operators as keys. It supports the following operators: `after` and `before`. The values are [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) date strings. `after` means that the time of the request must be after the supplied date and `before` means that the time of the request must be before the supplied date. For example:
```yaml
allow:
and:
- date:
after: 2020-01-02T16:20:00
before: 2150-01-02T16:20:00
```
## Device Matcher
A device matcher is an object with operators as keys. It supports the following operators:
- `is` - an exact match of the device ID.
- `approved` - true if the device has been approved. This is an enterprise-only feature.
- `type` - Specifies the type of device to match on. The available types are `enclave_only` and `any`.
- `enclave_only` will only match [platform authenticators](/docs/topics/device-identity.md#secure-enclaves). These include TPM modules and hardware-backed keystores built into mobile devices.
- `any` will also match [hardware security keys](/docs/topics/device-identity.md#hardware-security-keys).
For example, a policy to allow any user with a registered device:
```yaml
- allow:
or:
- device:
type: any
```
Compare to a policy that only allows a set of specific devices:
```yaml
- allow:
or:
- device:
is: "5Vn3...C1RS"
or:
- device:
is: "GAtL...doqu"
```
::: tip
Users can [find their device IDs](/guides/enroll-device.md#find-device-id) at the `/.pomerium` endpoint from any route.
:::
### List Matcher
A list matcher is an object with operators as keys. It supports the following operators: `has`. For example:
```yaml
allow:
and:
- groups:
has: 'admin'
```
### String Matcher
A string matcher is an object with operators as keys. It supports the following operators: `contains`, `ends_with`, `is` and `starts_with`. For example:
```yaml
allow:
and:
- email:
starts_with: 'admin@'
```
## Time of Day Matcher
The time of day matcher is an object with operators as keys. It supports the following operators: `timezone`, `after`, and `before`.
@ -171,3 +207,9 @@ allow:
[client certificate authority]: /reference/readme.md#client-certificate-authority
[Pomerium Enterprise]: /enterprise/about.md
[yaml]: https://en.wikipedia.org/wiki/YAML
[String Matcher]: #string-matcher
[Date Matcher]: #date-matcher
[Day of Week Matcher]: #day-of-week-matcher
[Time of Day Matcher]: #time-of-day-matcher
[List Matcher]: #list-matcher
[Device matcher]: #device-matcher

52
docs/guides/enroll-device.md Normal file
View file

@ -0,0 +1,52 @@
---
title: Enroll a Device
lang: en-US
meta:
- name: keywords
content: >-
pomerium identity-access-proxy webauthn device id enroll
authentication authorization
description: >-
This guide covers how to enroll a trusted execution environment device as a Pomerium end-user.
---
# Enroll a Device
If a Pomerium route is configured to [require device authentication](/docs/topics/ppl.md#device-matcher), then the user must register a [trusted execution environment](/docs/topics/device-identity.md#authenticated-device-types) (**TEE**) device before accessing the route. Registration is easy, but different depending on the device being used to provide ID.
1. Users are prompted to register a new device when accessing a route that requires device authentication:
![The WebAuthn Registration page with no devices registered](./img/webauthn/no-device.png)
Users can also get to the registration page from the special `.pomerium` endpoint available on any route, at the bottom of the page:
![The Device Credentials section of the .pomerium endpoint with the WebAuthn link highlighted](./img/webauthn/device-credentials-empty-highlight.png)
1. Click on **Register New Device**. Your browser will prompt you to provide access to a device. This will look different depending on the browser, operating system, and device type:
::::: tabs
:::: tab Windows
![The device authentication prompt on Windows](./img/webauthn/security-key-windows.png)
::::
:::: tab Chrome
![The device authentication prompt in Google Chrome](./img/webauthn/security-key-google.png)
::::
:::: tab Firefox
![The device authentication prompt in Firefox](./img/webauthn/security-key-firefox.png)
::::
:::: tab ChromeOS
![The device authentication prompt on ChromeOS](./img/webauthn/security-key-chromebook.png)
::::
## Find Device ID
If a route's policy is configured to only allow specific device IDs you will see a 450 error even after registering:
![450 device not authorized error screen](./img/webauthn/450-error.png)
From the `.pomerium` endpoint you can copy your device ID to provide to your Pomerium administrator.
![Device ID list at /.pomerium](./img/webauthn/device-id-list.png)
From here you can also delete the ID for devices that should no longer be associated with your account.

BIN
docs/guides/img/webauthn/450-error.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
docs/guides/img/webauthn/device-credentials-empty-highlight.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/guides/img/webauthn/device-id-list.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 37 KiB

BIN
docs/guides/img/webauthn/no-device.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/guides/img/webauthn/security-key-chromebook.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
docs/guides/img/webauthn/security-key-firefox.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/guides/img/webauthn/security-key-google.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
docs/guides/img/webauthn/security-key-windows.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 20 KiB

1
docs/guides/readme.md
View file

@ -7,6 +7,7 @@ This section contains applications, and scenario specific guides for Pomerium.
- The [Client-Side mTLS](./mtls.md) guide demonstrates how Pomerium can be used to add mutual authentication to end-user connections using client certificates and a custom certificate authority.
- The [Cloud Run](./cloud-run.md) recipe demonstrates deploying Pomerium to Google Cloud Run as well as using it to Authorize users to protected Cloud Run endpoints.
- The [code-server](./code-server.md) guide demonstrates how Pomerium can be used to add access control to third-party applications that don't ship with [fine-grained access control](https://github.com/cdr/code-server/issues/905). code-server is a tool to run Visual Studio code as a web application.
- See [Enroll a Device](./enroll-device.md) to learn how to register a security device (TPM, Yubikey, etc) to access routes requiring a device ID.
- Our [Grafana](./grafana.md) guide explains how to secure Grafana with Pomerium and integrate user sign-in using our JWT.
- The [JWT Verification](./jwt-verification.md) guide demonstrates how to verify the Pomerium JWT assertion header using Envoy.
- The [Kubernetes Dashboard](./kubernetes-dashboard.md) guide covers how to secure Kubernetes dashboard using Pomerium.