Skip to content

Commit

Permalink
docs: update GitHub auth method docs and security model
Browse files Browse the repository at this point in the history
Provide changes based on recent audit feedback: describe risks of third party authentication systems and plugins.
  • Loading branch information
mickael-hc committed Jan 5, 2022
1 parent 61b00c2 commit d91ba9d
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 9 deletions.
12 changes: 6 additions & 6 deletions website/content/docs/auth/github.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
14 changes: 13 additions & 1 deletion website/content/docs/auth/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
14 changes: 12 additions & 2 deletions website/content/docs/internals/security.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit d91ba9d

Please sign in to comment.