backport of commit d91ba9dce0a356814af49fb176ae474d57cac5f0

website/content/docs/auth/github.mdx

@@ -12,14 +12,14 @@ operators or developers using Vault directly via the CLI.
 
 ~> **IMPORTANT NOTE:** Vault does not support an OAuth workflow to generate
 GitHub tokens, so does not act as a GitHub application. As a result, this method
-uses personal access tokens. An important consequence is that any valid GitHub
-access token with the `read:org` scope for any user belonging to the Vault-configured
-organization can be used for authentication. If such a
+uses personal access tokens. If the risks below are unacceptable to you, consider
+using a different authentication method.
+
+~> Any valid GitHub access token with the `read:org` scope for any user belonging
+to the Vault-configured organization can be used for authentication. If such a
 token is stolen from a third party service, and the attacker is able to make
 network calls to Vault, they will be able to log in as the user that generated
-the access token. When using this method it is a good idea to ensure that access
-to Vault is restricted at a network level rather than public. If these risks are
-unacceptable to you, you should use a different method.
+the access token.
 
 ## Authentication
 

website/content/docs/auth/index.mdx

@@ -7,7 +7,11 @@ description: Auth methods are mountable methods that perform authentication for
 # Auth Methods
 
 Auth methods are the components in Vault that perform authentication and are
-responsible for assigning identity and a set of policies to a user.
+responsible for assigning identity and a set of policies to a user. In all cases,
+Vault will enforce authentication as part of the request processing. In most cases,
+Vault will delegate the authentication administration and decision to the relevant configured
+external auth method (e.g., Amazon Web Services, GitHub, Google Cloud Platform, Kubernetes, Microsoft
+Azure, Okta ...).
 
 Having multiple auth methods enables you to use an auth method that makes the
 most sense for your use case of Vault and your organization.
@@ -42,3 +46,11 @@ $ vault auth enable -path=my-login userpass
 
 When an auth method is disabled, all users authenticated via that method are
 automatically logged out.
+
+## External Auth Method Considerations
+
+When using an external auth method (e.g., GitHub), Vault will call the external service
+at the time of authentication and for any subsequent token renewals. This means that issued tokens
+are valid for their entire duration, and are not invalidated until a renewal or user re-authentication
+occurs. Operators should ensure appropriate [token TTLs](/docs/concepts/tokens#the-general-case)
+are set when using these auth methods.
\ No newline at end of file

website/content/docs/internals/security.mdx

@@ -60,6 +60,16 @@ The following are not parts of the Vault threat model:
   to inspect the memory state of a running Vault instance then the confidentiality
   of data may be compromised.
 
+- Protecting against flaws in external systems or services used by Vault.
+  Some authentication methods or secrets engines delegate sensitive operations to
+  systems external to Vault. If an attacker can compromise credentials or otherwise
+  exploit a vulnerability in these external systems, then the confidentiality or
+  integrity of data may be compromised.
+
+- Protecting against malicious plugins or code execution on the underlying host.
+  If an attacker can gain code execution or write privileges to the underlying host,
+  then the confidentiality or the integrity of data may be compromised.
+
 # External Threat Overview
 
 Given the architecture of Vault, there are 3 distinct systems we are concerned
@@ -128,8 +138,8 @@ notion of "sudo" privilege. As part of a policy, users may be granted "sudo"
 privileges to certain paths, so that they can still perform security sensitive
 operations without being granted global root access to Vault.
 
-Lastly, Vault supports using a [Two-man
-rule](https://en.wikipedia.org/wiki/Two-man_rule) for unsealing using [Shamir's
+Lastly, Vault supports using a [Two-person
+rule](https://en.wikipedia.org/wiki/Two-person_rule) for unsealing using [Shamir's
 Secret Sharing
 technique](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing). When Vault
 is started, it starts in a _sealed_ state. This means that the encryption key