From d91ba9dce0a356814af49fb176ae474d57cac5f0 Mon Sep 17 00:00:00 2001 From: mickael e Date: Wed, 5 Jan 2022 10:29:01 -0500 Subject: [PATCH] docs: update GitHub auth method docs and security model Provide changes based on recent audit feedback: describe risks of third party authentication systems and plugins. --- website/content/docs/auth/github.mdx | 12 ++++++------ website/content/docs/auth/index.mdx | 14 +++++++++++++- website/content/docs/internals/security.mdx | 14 ++++++++++++-- 3 files changed, 31 insertions(+), 9 deletions(-) diff --git a/website/content/docs/auth/github.mdx b/website/content/docs/auth/github.mdx index b42b9e696b1e..6254997b255c 100644 --- a/website/content/docs/auth/github.mdx +++ b/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 diff --git a/website/content/docs/auth/index.mdx b/website/content/docs/auth/index.mdx index 285fd550c3c3..35163c5db481 100644 --- a/website/content/docs/auth/index.mdx +++ b/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 diff --git a/website/content/docs/internals/security.mdx b/website/content/docs/internals/security.mdx index 2785337aba86..5c4747eeca4e 100644 --- a/website/content/docs/internals/security.mdx +++ b/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