diff --git a/docs/getting-started/email-recovery.md b/docs/getting-started/email-recovery.md index cdd90a24..b9182cda 100644 --- a/docs/getting-started/email-recovery.md +++ b/docs/getting-started/email-recovery.md @@ -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. +

+ +

+ + 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 diff --git a/docs/policy-management/Policy-overview.md b/docs/policy-management/Policy-overview.md index c7d3bad7..14941bff 100644 --- a/docs/policy-management/Policy-overview.md +++ b/docs/policy-management/Policy-overview.md @@ -30,7 +30,7 @@ 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: @@ -38,6 +38,8 @@ Stated differently: policy_overview

-- 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). diff --git a/static/img/diagrams/email_recovery_authorization.png b/static/img/diagrams/email_recovery_authorization.png new file mode 100644 index 00000000..9105e271 Binary files /dev/null and b/static/img/diagrams/email_recovery_authorization.png differ diff --git a/static/img/email_recovery_cryptography.png b/static/img/email_recovery_cryptography.png index 3f6bedbf..ea57ba01 100644 Binary files a/static/img/email_recovery_cryptography.png and b/static/img/email_recovery_cryptography.png differ diff --git a/static/img/email_recovery_steps.png b/static/img/email_recovery_steps.png index 8eea4a4d..4dfa26b1 100644 Binary files a/static/img/email_recovery_steps.png and b/static/img/email_recovery_steps.png differ