Skip to content

Commit ff39225

Browse files
greedy52greedy52
committed
add mermaid
1 parent b587f96 commit ff39225

File tree

1 file changed

+89
-51
lines changed

1 file changed

+89
-51
lines changed

‎rfd/0202-db-multi-session-mfa.md

Lines changed: 89 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -58,22 +58,28 @@ MFA is required to execute database sessions
5858
Tap any security key
5959
Detected security key tap
6060

61-
[mysql-db1] @@hostname
62-
[mysql-db1] mysql-db1-hostname
63-
[mysql-db2] @@hostname
64-
[mysql-db2] mysql-db2-hostname
61+
Executing command for 'mysql-db1':
62+
@@hostname
63+
mysql-db1-hostname
64+
65+
Executing command for 'mysql-db2':
66+
@@hostname
67+
mysql-db2-hostname
6568
```
6669

6770
I would like to search databases by labels, run the sql scripts in parallel, and
6871
record the outputs to a directory:
6972
```bash
70-
$ tsh db exec --search-by-labels env=dev --db-user mysql --exec-query "source my_script.sql" --output-dir exec-logs --max-connections 3
73+
$ tsh db exec --search-by-labels env=dev --db-user mysql --exec-query "source my_script.sql" --log-dir exec-logs --max-connections 3
7174
Found 5 databases:
72-
- mysql-db1
73-
- mysql-db2
74-
- mysql-db3
75-
- mysql-db4
76-
- mysql-db5
75+
76+
Name Protocol Description Labels
77+
--------- -------- ----------- -------
78+
mysql-db1 mysql instance 1 env=dev
79+
mysql-db2 mysql instance 2 env=dev
80+
mysql-db3 mysql instance 3 env=dev
81+
mysql-db4 mysql instance 4 env=dev
82+
mysql-db5 mysql instance 5 env=dev
7783

7884
Tip: use --skip-confirm to skip this confirmation.
7985
Do you want to continue? (Press any key to proceed or Ctrl+C to exit): <enter>
@@ -82,21 +88,38 @@ MFA is required to execute database sessions
8288
Tap any security key
8389
Detected security key tap
8490

85-
Executing command for 'mysql-db1'
86-
Executing command for 'mysql-db2'
87-
Executing command for 'mysql-db3'
88-
Executing command for 'mysql-db4'
89-
Executing command for 'mysql-db5'
90-
91-
$ ls exec-logs/
92-
mysql-db1.output mysql-db2.output mysql-db3.output mysql-db4.output mysql-db5.output
91+
Executing command for 'mysql-db1'. Outputs will be saved at 'exec-logs/mysql-db1.log'.
92+
Executing command for 'mysql-db2'. Outputs will be saved at 'exec-logs/mysql-db2.log'.
93+
Executing command for 'mysql-db3'. Outputs will be saved at 'exec-logs/mysql-db3.log'.
94+
Executing command for 'mysql-db4'. Outputs will be saved at 'exec-logs/mysql-db4.log'.
95+
Executing command for 'mysql-db5'. Outputs will be saved at 'exec-logs/mysql-db5.log'.
9396
```
97+
(where you can expect the first 3 connections happen right away, and the other 2
98+
connections happen after the previous ones finish.)
9499

95100
### Multi-session MFA
96101

97-
TODO(greedy52) add a diagram.
102+
Overview:
103+
```mermaid
104+
sequenceDiagram
105+
participant user
106+
participant tsh
107+
participant Teleport
108+
109+
user -> tsh: tsh db exec
110+
tsh -> Teleport: CreateAuthenticateChallengeRequest<br/>Scope: SCOPE_DATABASE_MULTI_SESSION<br/>Reuse: true
111+
Teleport -> tsh: challenge
112+
tsh -> user: prompt
113+
user -> tsh: tap
114+
tsh -> Teleport: WebAuthn login
115+
Teleport -> tsh: MFA Response
116+
loop
117+
tsh -> Teleport: GenerateUserCerts with MFA response
118+
Teleport -> tsh: User cert with database route
119+
end
120+
```
98121

99-
A new role option is added to preserve existing behavior if not set:
122+
A new role option is added to decide the mode for session MFA:
100123
```diff
101124
kind: role
102125
version: v7
@@ -109,6 +132,9 @@ spec:
109132
+ # supported for `tsh db exec` command with WebAuthn as the second factor.
110133
+ requie_session_mfa_mode: "multi-session"
111134
```
135+
Mode defaults to `per-session` if not set. If a resource matches a role set with
136+
some roles on `per-session` but others on `multi-session`, the stricter mode
137+
`per-session` should be applied.
112138

113139
The multi-session MFA extends [RFD 155 Scoped Webauthn
114140
Credentials](https://github.com/gravitational/teleport/blob/master/rfd/0155-scoped-webauthn-credentials.md)
@@ -122,59 +148,71 @@ enum ChallengeScope {
122148
}
123149
```
124150

125-
Similar to `SCOPE_ADMIN_ACTION`, the new scope will allow reuse of the MFA
126-
session data until it expires (5 minutes for WebAuthn).
151+
Similar to `SCOPE_ADMIN_ACTION`, the new scope `SCOPE_DATABASE_MULTI_SESSION`
152+
will allow reuse of the MFA session data until it expires (5 minutes for
153+
WebAuthn).
127154

128155
The MFA response will be checked upon auth call of `GenerateUserCerts` where
129156
user requests a TLS user cert with database route. New logic is added to
130157
`GenerateUserCerts` where the new scope with reuse is allowed only if the role
131158
set matching the requested database has `roleset.option.requie_session_mfa_mode`
132159
option set to `multi-session`.
133160

134-
If MFA response is validated with existing non-reusable `SCOPE_SESSION`, the
135-
action should be allowed regardless of `roleset.option.requie_session_mfa_mode`.
161+
The new scope cannot be used for `GenerateUserCerts` for non-database targets.
162+
And if the MFA response is validated with existing non-reusable `SCOPE_SESSION`,
163+
the action should be allowed regardless of
164+
`roleset.option.requie_session_mfa_mode`.
136165

137166
Here is a quick matrix:
138167

139-
| `session_mfa_mode` | MFA response scope | Access |
140-
| ------------------ | ------------------ | ------ |
141-
| `multi-session` | `SCOPE_SESSION` | allow |
142-
| `multi-session` | `SCOPE_DATABASE_MULTI_SESSION` | allow |
143-
| `per-session` | `SCOPE_SESSION` | allow |
144-
| `per-session` | `SCOPE_DATABASE_MULTI_SESSION` | denied |
168+
| `session_mfa_mode` | MFA response scope | Requested Target | Access |
169+
|--------------------|--------------------------------|------------------|--------|
170+
| `multi-session` | `SCOPE_SESSION` | Database | Allow |
171+
| `multi-session` | `SCOPE_DATABASE_MULTI_SESSION` | Database | Allow |
172+
| `multi-session` | `SCOPE_DATABASE_MULTI_SESSION` | Non-Database | Denied |
173+
| `per-session` | `SCOPE_SESSION` | Database | Allow |
174+
| `per-session` | `SCOPE_DATABASE_MULTI_SESSION` | Database | Denied |
175+
| `per-session` | `SCOPE_DATABASE_MULTI_SESSION` | Non-Database | Denied |
145176

146177
### The `tsh db exec` command
147178

148179
General flow of the command:
149180
- Fetch databases (either specified directly or through search).
150-
- Fetch roles and use access checker to pre-determine MFA requirement.
151-
- For each database
152-
- Prompt MFA if necessary
153-
- Starts a local proxy in tunnel mode for this database
154-
- Craft a command and `os.exec`.
155-
156-
For MVP, only PostgreSQL and MySQL databases will be supported.
157-
158-
#### `tsh db exec` search
159-
`tsh db exec` supports searching database by specifying one the following flags:
181+
- Fetch roles and use access checker to determine MFA requirement.
182+
- For each database:
183+
- Prompt MFA if necessary.
184+
- Starts a local proxy in tunnel mode for this database.
185+
- Craft a command for `os.exec`. The command is not interactive (e.g. does not
186+
take in `stdin` input). Outputs are printed to `stdout` unless `--log-dir`
187+
is specified.
188+
- Execute the command.
189+
190+
The command supports searching database by specifying one the following flags:
160191
- `--search`: List of comma separated search keywords or phrases enclosed in quotations, e.g. `--search=foo,bar`
161192
- `--search-by-labels`: List of comma separated labels to filter by labels, e.g. `key1=value1,key2=value2`
162193
- `--search-by-query`: Query by predicate language enclosed in single quotes.
163194

164195
The command presents the search results then asks user to confirm before
165196
proceeding. `--skip-confirm` can be used to skip the confirmation.
166197

198+
Some other details:
199+
- If the multi-session MFA response is expired, the command should ask for MFA
200+
again.
201+
- For MVP implementation, only PostgreSQL and MySQL databases will be supported.
202+
- A warning will be printed if the target databases have different protocols
203+
(e.g. `postgres` vs `mysql`).
204+
- For databases that require per-session MFA, a prompt will still be presented
205+
per database.
206+
207+
#### Possible enhancements for `tsh db exec`
208+
- `tsh db exec --exec-config` to support a config file which allows specifying
209+
different flags like `--db-user`, `--db-name`, `--exec-query` per target
210+
database or per search.
211+
- `tsh db exec --exec-command` to support custom command template like `$ tsh
212+
db exec --exec-command "bash -c './myscript {{.DB_SERVICE}} {{.DB_USER}}
213+
{{.DB_LOCAL_PORT}}'"`. An env var `TSH_UNSTABLE_DB_EXEC_COMMAND` can be
214+
supported for the initial MVP.
215+
167216
### Security
168217

169218
TODO
170-
171-
### Possible enhancements
172-
#### `tsh db exec --exec-config`
173-
To support a config file which allows specifying different flags like
174-
`--db-user`, `--db-name`, `--exec-query` per target database.
175-
176-
#### `tsh db exec --exec-command`
177-
To support custom command template like:
178-
```
179-
$ tsh db exec --exec-command "bash -c './myscript {{.DB_SERVICE}} {{.DB_LOCAL_PORT}}'
180-
```

0 commit comments

Comments
 (0)