From bed9f4e89698553247d03c840d1d9ae2e45b8616 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Mon, 11 Feb 2019 11:10:24 +0100 Subject: [PATCH] Improve documentation on Token authentication, renewal and SessionManager use. Closes gh-369. --- .../LifecycleAwareSessionManagerSupport.java | 2 +- src/main/asciidoc/reference/authentication.adoc | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/spring-vault-core/src/main/java/org/springframework/vault/authentication/LifecycleAwareSessionManagerSupport.java b/spring-vault-core/src/main/java/org/springframework/vault/authentication/LifecycleAwareSessionManagerSupport.java index e1420237..36dfdb6c 100644 --- a/spring-vault-core/src/main/java/org/springframework/vault/authentication/LifecycleAwareSessionManagerSupport.java +++ b/spring-vault-core/src/main/java/org/springframework/vault/authentication/LifecycleAwareSessionManagerSupport.java @@ -71,7 +71,7 @@ public abstract class LifecycleAwareSessionManagerSupport { * {@code auth/token/lookup-self} for {@link VaultToken}s obtained from a * {@link ClientAuthentication}. Self-lookup determines whether a token is renewable * and its TTL. Self lookup is skipped for {@link LoginToken}. Self-lookup requests - * decrement token usage count by one. Skipped for {@link LoginToken}. + * decrement token usage count by one. */ private boolean tokenSelfLookupEnabled = true; diff --git a/src/main/asciidoc/reference/authentication.adoc b/src/main/asciidoc/reference/authentication.adoc index 756782e2..304c50ad 100644 --- a/src/main/asciidoc/reference/authentication.adoc +++ b/src/main/asciidoc/reference/authentication.adoc @@ -52,6 +52,11 @@ NOTE: Token authentication is the default authentication method. If a token is disclosed an unintended party, it gains access to Vault and can access secrets for the intended client. +Typically, Token authentication is used in scenarios in which the token is created and renewed +externally (such as https://github.com/hashicorp/vault-service-broker[HashiCorp Vault service broker]). +Depending on the actual setup, you may or may not want token renewal and revocation. +See <> for details about TTL and token revocation. + ==== [source,java] ---- @@ -793,6 +798,7 @@ VaultToken token = executor.login(); ---- ==== +[[vault.authentication.session]] == Token Lifecycle Vault's tokens can be associated with a time to live. Tokens obtained by an authentication method @@ -806,5 +812,6 @@ Depending on the authentication method, a login can create two kinds of tokens: * {self-docs-root}api/org/springframework/vault/support/LoginToken.html[`LoginToken`]: Token associated with renewability/TTL. Authentication methods such as {self-docs-root}api/org/springframework/vault/authentication/TokenAuthentication.html[`TokenAuthentication`] just create a `VaultToken` which does not carry any renewability/TTL details. `LifecycleAwareSessionManager` will run a self-lookup on the token to retrieve renewability and TTL from Vault. +`VaultToken` are renewed periodically if self-lookup is enabled. Note that `VaultToken` are never revoked, only `LoginToken` are revoked. Authentication methods creating `LoginToken` directly (all login-based authentication methods) already provide all necessary details to setup token renewal. Tokens obtained from a login are revoked by `LifecycleAwareSessionManager` if the session manager is shut down.