mirror of
https://github.com/pomerium/pomerium.git
synced 2025-05-30 01:17:21 +02:00
remove user impersonation and service account cli (#1768)
* remove user impersonation and service account cli * update doc * remove user impersonation url query params * fix flaky test
This commit is contained in:
Caleb Doxsey
GitHub
parent
eadd8c2482
commit
ab4a68f56f
21 changed files with 258 additions and 831 deletions
|
|
@ -124,7 +124,6 @@ module.exports = {
|
|||
"topics/production-deployment",
|
||||
"topics/programmatic-access",
|
||||
"topics/tcp-support",
|
||||
"topics/impersonation",
|
||||
"topics/single-sign-out",
|
||||
],
|
||||
},
|
||||
|
|
|
|||
|
|
@ -9,10 +9,10 @@
|
|||
/community/index.html /docs/community/
|
||||
/community/contributing /docs/community/contributing.html
|
||||
/community/contributing.html /docs/community/contributing.html
|
||||
/community/code-of-conduct /docs/community/code-of-conduct.html
|
||||
/community/code-of-conduct.html /docs/community/code-of-conduct.html
|
||||
/community/security /docs/community/security.html
|
||||
/community/security.html /docs/community/security.html
|
||||
/community/code-of-conduct /docs/community/code-of-conduct.html
|
||||
/community/code-of-conduct.html /docs/community/code-of-conduct.html
|
||||
/community/security /docs/community/security.html
|
||||
/community/security.html /docs/community/security.html
|
||||
|
||||
/guide/ /docs/quick-start/
|
||||
/guide/kubernetes.html /docs/quick-start/kubernetes.html
|
||||
|
|
@ -34,12 +34,11 @@
|
|||
|
||||
|
||||
/docs/reference/ /docs/topics/
|
||||
/docs/reference/readme.html /docs/topics/readme.html
|
||||
/docs/reference/readme.html /docs/topics/readme.html
|
||||
/docs/reference/certificates.html /docs/topics/certificates.html
|
||||
/docs/reference/data-storage.html /docs/topics/data-storage.html
|
||||
/docs/reference/getting-users-identity.html /docs/topics/getting-users-identity.html
|
||||
/docs/reference/impersonation.html /docs/topics/impersonation.html
|
||||
/docs/reference/production-deployment.html /docs/topics/production-deployment.html
|
||||
/docs/reference/production-deployment.html /docs/topics/production-deployment.html
|
||||
/docs/reference/programmatic-access.html /docs/topics/programmatic-access.html
|
||||
|
||||
/docs/reference/examples.html /configuration/examples.html
|
||||
|
|
@ -52,4 +51,4 @@
|
|||
/jobs/Frontend-Engineer.html /careers/frontend-engineer/
|
||||
/jobs/Backend-Engineer.html /careers/backend-engineer/
|
||||
|
||||
/enterprise/ /
|
||||
/enterprise/ /
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ description: This article describes various ways to install pomerium
|
|||
Pomerium is shipped in multiple formats and architectures to suit a variety of deployment patterns. There are two binaries:
|
||||
|
||||
- `pomerium` is the primary server component. It is a monolithic binary that can perform the function of any [services mode](/reference/#service-mode).
|
||||
- `pomerium-cli` (optional) is a command-line client for working with Pomerium. Functions include generating service accounts, and acting as an authentication helper for tools like [kubtctl](topics/kubernetes-integration.md).
|
||||
- `pomerium-cli` (optional) is a command-line client for working with Pomerium. Functions include acting as an authentication helper for tools like [kubtctl](topics/kubernetes-integration.md).
|
||||
|
||||
|
||||
[[toc]]
|
||||
|
|
|
|||
|
|
@ -1,169 +0,0 @@
|
|||
---
|
||||
title: User impersonation
|
||||
description: >-
|
||||
This article describes how to configure Pomerium to allow an administrative
|
||||
user to impersonate another user or group.
|
||||
---
|
||||
|
||||
# User Impersonation & Service Accounts
|
||||
|
||||
## What
|
||||
|
||||
User impersonation and service accounts enables administrative users to temporarily "sign in as" another user in pomerium. Users with impersonation permissions can impersonate all other users and groups. The impersonating user will be subject to the authorization and access policies of the impersonated user.
|
||||
|
||||
## Why
|
||||
|
||||
In certain circumstances, it's useful for an administrative user to impersonate another user. For example:
|
||||
|
||||
- To help a user troubleshoot an issue. If your downstream authorization policies are configured differently, it's possible that your UI will look different from theirs and you'll need to impersonate the other user to be able to see what they see.
|
||||
- You want to make changes on behalf of another user (for example, the other user is away on vacation and you want to manage their orders or run a report).
|
||||
- You're an administrator who's setting up authorization policies, and you want to preview what other users will be able to see depending on the permissions you grant them.
|
||||
|
||||
## How
|
||||
|
||||
There are two mechanisms for doing user impersonation or service account generation. The first, is using the web-interface using the special (`/.pomerium`) endpoint, and the second is by using an included command line interface tool.
|
||||
|
||||
### Using the web-interface
|
||||
|
||||
Pomerium contains an endpoint that allows administrators to impersonate a user, and/or their groups.
|
||||
|
||||
1. Add an administrator to your [configuration settings].
|
||||
2. Navigate to user dashboard for any proxied route. (e.g. `https://{your-domain}/.pomerium`)
|
||||
3. Add the `email` and `user groups` you want to impersonate.
|
||||
4. That's it!
|
||||
|
||||
::: warning
|
||||
|
||||
**Note!** On session refresh, impersonation will be reset.
|
||||
|
||||
:::
|
||||
|
||||
Here's what it looks like.
|
||||
|
||||
<video width="100%" height="600" controls=""><source src="./img/pomerium-user-impersonation.mp4" type="video/mp4">
|
||||
Your browser does not support the video tag.
|
||||
</video>
|
||||
|
||||
### Using the command line interface
|
||||
|
||||
Pomerium also includes a command line interface (cli) for generating arbitrary route-scoped service account sessions. Generated service accounts can be used to impersonate users, perform service-to-service communication, and facilitate end-to-end testing for applications managed by Pomerium. The cli is especially useful in situations where an administrator needs more control over the sessions she generates, or if skipping the authentication portion of pomerium's flow is required.
|
||||
|
||||
### How
|
||||
|
||||
```bash
|
||||
pomerium-cli generates a pomerium service account from a shared key.
|
||||
|
||||
Usage: /bin/pomerium-cli [flags] [base64d shared secret setting]
|
||||
|
||||
For additional help see:
|
||||
|
||||
https://www.pomerium.io
|
||||
https://jwt.io/
|
||||
|
||||
Flags:
|
||||
|
||||
-aud value
|
||||
Audience (e.g. httpbin.int.pomerium.io,prometheus.int.pomerium.io)
|
||||
-email string
|
||||
Email
|
||||
-expiry duration
|
||||
Expiry (default 1h0m0s)
|
||||
-groups value
|
||||
Groups (e.g. admins@pomerium.io,users@pomerium.io)
|
||||
-impersonate_email string
|
||||
Impersonation Email (optional)
|
||||
-impersonate_groups value
|
||||
Impersonation Groups (optional)
|
||||
-iss string
|
||||
Issuing Server (e.g authenticate.int.pomerium.io)
|
||||
-sub string
|
||||
Subject (typically User's GUID)
|
||||
-user string
|
||||
User (typically User's GUID)
|
||||
```
|
||||
|
||||
The easiest way to generate that service account would be to use pomerium's docker image and run the `pomerium-cli` tool. Consider the following example:
|
||||
|
||||
```bash
|
||||
docker run -it --entrypoint "/bin/pomerium-cli" pomerium/pomerium:latest \
|
||||
-email bob@pomerium.io \
|
||||
-aud httpbin.int.pomerium.io \
|
||||
-sub bob \
|
||||
-user bob \
|
||||
-expiry 1h \
|
||||
-iss authenticate.int.pomerium.io
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
The cli will then prompt you for your base64 encoded shared secret. As a reminder, your shared secret key is _extremely_ sensitive and is used to cryptographically sign sessions here and elsewhere.
|
||||
|
||||
:::
|
||||
|
||||
:::tip
|
||||
|
||||
You can also pass the shared secret by setting the `POMERIUM_SHARED_KEY` environment variable.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
You should now see something like:
|
||||
|
||||
```jwt
|
||||
eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiaHR0cGJpbi5pbnQucG9tZXJpdW0uaW8iXSwiZW1haWwiOiJib2JAcG9tZXJpdW0uaW8iLCJleHAiOjE1ODY4NDI2NzksImlhdCI6MTU4NjgzOTA3OSwiaXNzIjoiYXV0aGVudGljYXRlLmludC5wb21lcml1bS5pbyIsIm5iZiI6MTU4NjgzOTA3OSwic3ViIjoiYm9iIiwidXNlciI6ImJvYiJ9.Z4LjZoap24YkWpX8QAhZzexSVKF4982Oma4GTHbdk4k
|
||||
```
|
||||
|
||||
The above generated [JSON Web Token](https://jwt.io/) (JWT) value can now be used as your service account. This JWT session can be used as a [bearer token](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization), or as a session cookie.
|
||||
|
||||
As JSON, the payload looks like this (plus a signature).
|
||||
|
||||
```json
|
||||
{
|
||||
"iss": "authenticate.int.pomerium.io",
|
||||
"sub": "bob",
|
||||
"aud": [
|
||||
"httpbin.int.pomerium.io"
|
||||
],
|
||||
"exp": 1586842679,
|
||||
"nbf": 1586839079,
|
||||
"iat": 1586839079,
|
||||
"email": "bob@pomerium.io",
|
||||
"user": "bob"
|
||||
}
|
||||
```
|
||||
|
||||
For example, here's what the full flow could look like from a bash script:
|
||||
|
||||
```bash
|
||||
jwt=$(docker run -it --entrypoint "/bin/pomerium-cli" pomerium/pomerium:latest \
|
||||
-email bob@pomerium.io \
|
||||
-aud httpbin.int.pomerium.io \
|
||||
-iss authenticate.int.pomerium.io \
|
||||
X/6+31jHCANkIbOajHMACNy+HmDreiXcDzRMRQepoVI=)
|
||||
|
||||
# note! you should probably use stdin to pass in your key for safety!
|
||||
|
||||
curl https://httpbin.imac.bdd.io/headers \
|
||||
-H "Accept: application/json" \
|
||||
-H "Authorization: Pomerium $jwt"
|
||||
```
|
||||
|
||||
And you should see something like the following in response:
|
||||
|
||||
```json
|
||||
{
|
||||
"headers": {
|
||||
"Accept": "application/json",
|
||||
"Accept-Encoding": "gzip",
|
||||
"Authorization": "Pomerium eyJhbGciOiJIUzI1NiJ9.REDACTED",
|
||||
"Cookie": "",
|
||||
"Host": "httpbin.org",
|
||||
"User-Agent": "curl/7.64.1",
|
||||
"X-Forwarded-Host": "httpbin.imac.bdd.io",
|
||||
"X-Pomerium-Jwt-Assertion": "eyJhbGciOiAiRVMyNTYifQ.REDACTED"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[configuration settings]: ../../reference/readme.md#administrators
|
||||
|
|
@ -5,6 +5,14 @@ description: >-
|
|||
for Pomerium. Please read it carefully.
|
||||
---
|
||||
|
||||
# Since 0.12.0
|
||||
|
||||
## Breaking
|
||||
|
||||
### User impersonation removed
|
||||
|
||||
With the v0.13.0 release, user impersonation has been removed.
|
||||
|
||||
# Since 0.11.0
|
||||
|
||||
## New
|
||||
|
|
|
|||
|
|
@ -40,25 +40,6 @@ These configuration variables are shared by all services, in all service modes.
|
|||
Address specifies the host and port to serve HTTP requests from. If empty, `:443` is used. Note, in all-in-one deployments, gRPC traffic will be served on loopback on port `:5443`.
|
||||
|
||||
|
||||
### Administrators
|
||||
- Environmental Variable: `ADMINISTRATORS`
|
||||
- Config File Key: `administrators`
|
||||
- Type: slice of `string`
|
||||
- Example: `"admin@example.com,admin2@example.com"`
|
||||
|
||||
Administrative users are [super users](https://en.wikipedia.org/wiki/Superuser) that can sign-in as another user or group. User impersonation allows administrators to temporarily impersonate a different user.
|
||||
|
||||
|
||||
### Enable User Impersonation
|
||||
- Environmental Variable: `ENABLE_USER_IMPERSONATION`
|
||||
- Config File Key: `enable_user_impersonation`
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
- Optional
|
||||
|
||||
Enabling user impersonation allows administrators to impersonate other user accounts. Prior to v0.11.0 this feature was enabled by default. It is now disabled by default.
|
||||
|
||||
|
||||
### Autocert
|
||||
- Environmental Variable: `AUTOCERT`
|
||||
- Config File Key: `autocert`
|
||||
|
|
|
|||
|
|
@ -57,27 +57,6 @@ settings:
|
|||
Address specifies the host and port to serve HTTP requests from. If empty, `:443` is used. Note, in all-in-one deployments, gRPC traffic will be served on loopback on port `:5443`.
|
||||
shortdoc: |
|
||||
Address specifies the host and port to serve HTTP requests from.
|
||||
- name: "Administrators"
|
||||
keys: ["administrators"]
|
||||
attributes: |
|
||||
- Environmental Variable: `ADMINISTRATORS`
|
||||
- Config File Key: `administrators`
|
||||
- Type: slice of `string`
|
||||
- Example: `"admin@example.com,admin2@example.com"`
|
||||
doc: |
|
||||
Administrative users are [super users](https://en.wikipedia.org/wiki/Superuser) that can sign-in as another user or group. User impersonation allows administrators to temporarily impersonate a different user.
|
||||
shortdoc: |
|
||||
Administrative users are super user that can sign in as another user or group.
|
||||
- name: "Enable User Impersonation"
|
||||
keys: ["enable_user_impersonation"]
|
||||
attributes: |
|
||||
- Environmental Variable: `ENABLE_USER_IMPERSONATION`
|
||||
- Config File Key: `enable_user_impersonation`
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
- Optional
|
||||
doc: |
|
||||
Enabling user impersonation allows administrators to impersonate other user accounts. Prior to v0.11.0 this feature was enabled by default. It is now disabled by default.
|
||||
- name: "Autocert"
|
||||
keys: ["autocert"]
|
||||
attributes: |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue