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

v0.4.0

Browse source 
deployment: prepare v0.4.0 (#350
Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com>
This commit is contained in:
Bobby DeSimone 2019-10-07 19:53:57 -07:00 • committed by GitHub
parent bca5caf77a
commit 28eae36ce1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
24 changed files with 222 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/docs/reference/getting-users-identity.md Normal file
View file

@ -0,0 +1,41 @@
---
title: Getting the user's identity
description: >-
This article describes how to to get a user's identity with Pomerium.
---
# Getting the user's identity
This article describes how to retrieve a user's identity from a pomerium managed application.
## Headers
By default, pomerium passes the following [response headers] to it's downstream applications to identify the requesting users.
| Header | description |
| :------------------------------------- | -------------------------------------------------------------- |
| `x-pomerium-authenticated-user-id` | Subject is the user's id. |
| `x-pomerium-authenticated-user-email` | Email is the user's email. |
| `x-pomerium-authenticated-user-groups` | Groups is the user's groups. |
| `x-pomerium-iap-jwt-assertion` | **Recommended** Contains the user's details as a signed [JWT]. |
In an ideal environment, the cryptographic authenticity of the user's identifying headers should be enforced at the protocol level using mTLS.
### Recommended : Signed JWT header
For whatever reason, (e.g. an attacker bypasses pomerium's protocol encryption, or it is accidentally turned off), it is possible that the `x-pomerium-authenticated-user-{email,id,groups}` headers could be forged. Therefore, it is highly recommended to use and validate the [JWT] assertion header which adds an additional layer of authenticity.
Verify that the [JWT assertion header](./signed-headers.md) conforms to the following constraints:
| [JWT] | description |
| :------: | ------------------------------------------------------------------------------------------------------ |
| `exp` | Expiration time in seconds since the UNIX epoch. Allow 1 minute for skew. |
| `iat` | Issued-at time in seconds since the UNIX epoch. Allow 1 minute for skew. |
| `aud` | The client's final domain e.g. `httpbin.corp.example.com`. |
| `iss` | Issuer must be `pomerium-proxy`. |
| `sub` | Subject is the user's id. Can be used instead of the `x-pomerium-authenticated-user-id` header. |
| `email` | Email is the user's email. Can be used instead of the `x-pomerium-authenticated-user-email` header. |
| `groups` | Groups is the user's groups. Can be used instead of the `x-pomerium-authenticated-user-groups` header. |
[jwt]: https://jwt.io
[response headers]: https://developer.mozilla.org/en-US/docs/Glossary/Response_header