Skip to content

Commit

Permalink
updating some language and diagrams around policies and email recovery
Browse files Browse the repository at this point in the history
  • Loading branch information
hmarnold committed Nov 17, 2023
1 parent e89a3e2 commit 59a34f9
Show file tree
Hide file tree
Showing 6 changed files with 13 additions and 6 deletions.
9 changes: 7 additions & 2 deletions docs/getting-started/email-recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,15 @@ Once a user receives a recovery email, recovery credential _decryption_ needs to

## Authorization

Authorization for email recovery is based on our usual activity authorization: our [policy engine](../policy-management/Policy-overview.md) controls who can and cannot execute recovery-related activities.
* `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY` can be performed by the root user or by any user in an organization if authorized by policy. The activity can target any user in this organization **or any sub-organization user**. The activity will fail if a parent user tries to initiate recovery for a sub-organization which has [opted out of email recovery](#opting-out-of-email-recovery).
Authorization for email recovery is based on our usual activity authorization: our [policy engine](../policy-management/Policy-overview.md) controls who can and cannot execute recovery-related activities.
* `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY` can be performed by the root user or by any user in an organization if authorized by policy. The activity can target **any user** in this organization **or any sub-organization user**. The activity will fail if a parent user tries to initiate recovery for a sub-organization which has [opted out of email recovery](#opting-out-of-email-recovery).
* `ACTIVITY_TYPE_RECOVER_USER` should be signed by the recovery credential sent via email. Even if not explicitly allowed by policy, a user is always able to add credentials to their own user. This includes adding a new authenticator when authenticated with a recovery credential. In other words, no special policy is needed to make this work: users are able to recover out-of-the-box.

<p style={{textAlign: 'center'}}>
<img src="/img/diagrams/email_recovery_authorization.png" width="500" height="200"/>
</p>


Important note: recovery credentials automatically expire after **30 minutes** and are overridden when multiple `INIT_USER_EMAIL_RECOVERY` activities target the same user. Only the most recent recovery credential is valid.

## Email recovery in your sub-organizations
Expand Down
10 changes: 6 additions & 4 deletions docs/policy-management/Policy-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,16 @@ All policies defined within an Organization are evaluated on each request. The i
1. If a quorum of root users takes the action, the final outcome is `OUTCOME_ALLOW`
2. Else if any applicable policy has `EFFECT_DENY`, the final outcome is `OUTCOME_DENY`. This is also referred to as "explicit deny."
3. Else if at least one applicable policy has `EFFECT_ALLOW`, then the final outcome is `OUTCOME_ALLOW`
4. Else the final outcome is `OUTCOME_DENY`. This is also referred to as "implicit deny."
4. Else the final outcome is `OUTCOME_DENY`. This is also referred to as "implicit deny." In cases of conflicts, `EFFECT_DENY` always wins.

Stated differently:

<p style={{textAlign: 'center'}}>
<img src="/img/diagrams/policy_overview.png" alt="policy_overview" width="500px" />
</p>

- Root users bypass any policies
- Otherwise, all actions on Turnkey are implicitly denied by default. They have to be explicitly allowed by a policy.
- In cases of conflicts, `EFFECT_DENY` always wins
Almost all actions on Turnkey are implicitly denied by default. There are a few exceptions, however:
- Root users bypass any policies.
- All users have implicit GET (read) permissions in their own Organization and any associated Sub-Organizations.
- All users have implicit permission to change their own credentials.
- All users have implicit permission to approve an activity if they were included in consensus (i.e., a user specified as part of the consensus required to approve a SIGN_TRANSACTION activity does not need separate, explicit permission to sign transactions).
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified static/img/email_recovery_cryptography.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified static/img/email_recovery_steps.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/xx.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 59a34f9

Please sign in to comment.