どうも、イオンスマートテクノロジー株式会社（社内ではASTと略します）CTO室SREチームのあおしょんです。
今回はHCP (HashiCorp Cloud Platform) VaultのPoCの過程でVaultのTokenの理解を深めるために纏めた内容を記事として投稿します。
社内のConfluenceに纏めた内容をほぼそのまま転記しているため説明調であることご容赦ください🙇
目的
本記事執筆者がよわよわでVaultのTokenの理解が十分に出来ていないので下記ドキュメントを読みながら、かつ手を動かしながら完全に（？）理解したことを纏める。
上段がドキュメントで下段がチュートリアルである。
なお、以降の文章では「トークン」と「Token」の表記を下記の通り使い分けて記載する。
- トークン：一般的な用語
- Token：Vaultが生成するトークン
VaultのToken is ナニ？
クライアントがVaultへリクエストする際に必要なトークンである。
クライアントはまずAuth MethodでVaultと認証を行い、認証が成功するとVaultがTokenを生成してクライアントに払い出す。クライアントはそのTokenでVaultとの認証を行う。
上記は公式ドキュメント内の画像を抜粋
Tokenは主に２種類ある
Service tokenとBatch tokenの２種類がある。
例えば、vault loginするときのTokenはService tokenで見分け方としては接頭辞にhvs.が付いていること。ちなみに左記で払い出されるTokenはRoot tokenと呼ばれる。
$ vault login
Token (will be hidden):
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token hvs.XXXXXX # Root token
token_accessor 1JGSebeYfCTuXo8MDeroGs6R.3wtUO
token_duration 5h56m44s
token_renewable false
token_policies ["default" "hcp-root"]
identity_policies []
policies ["default" "hcp-root"]
ちなみにBatch tokenの接頭辞はhvb.らしい。
まずはService tokenの理解を深めたいのでその該当機能について纏める。Batch tokenは使うことがあれば別途纏めるかも。
Recovery tokenというのもあるらしいが直近利用しないので必要となることがあれば思い出すことにする。
Service tokenのライフサイクルとOrphan token
全てのTokenにはTTL (time-to-live)がある。
Tokenはトークン所有者の元トークンの子トークンとして作成される。（語彙力がないため文章がややこしくてmm）親トークンがTTL切れなどで無効になると子トークンも孫トークンも無効になる。
下記の公式ドキュメントで詳しく説明されている。
実際に親トークンを持つTokenを利用するとTTLの管理がカオスになるので親を持たないトークンOrphan tokenを作成するらしい。
Token TTLのイロハ
TokenのTTLを設定する上で大きく分けて２パターンある。
ASTではAuth MethodはJWTを多用する（はず）ので下記ドキュメントのパラメータと関連付けて記す。
通常のtoken
有効期限のあるトークンである。（ナニをいってるかは後述のPeriodic tokenを知ればわかる。）
関連する設定項目としては下記2パラメータがある。
-
token_ttl：パラメータ名の通りTokenのTTLである。ここで設定したttlが切れるとtokenは無効になる。但し、token_max_ttlで設定した期間まで更新し続けることが出来る。 -
token_max_ttl：tokenの実際の最大TTLである。Token作成してからこの期間を過ぎるとtoken_ttlは更新出来ず、完全にtokenは無効となる。
token_ttlとtoken_max_ttlのデフォルトは両方とも32日となっている。
Periodic token
有効期限（token_ttl）を無制限に更新できるトークンである。
token_periodを設定することで通常のtokenではなくPeriodic tokenとなる。
関連する設定項目としては下記2パラメータがある。
-
token_period：ttlをリセットする周期- 上記の周期を過ぎる前にクライアントが
vault token renewを実行すればtoken_ttlがリセットされる。例えばtoken_periodが5分だとtoken_ttlも5分であり、5分を過ぎる前にクライアントがvault token renewを実行すればtoken_ttlが5分に戻る。 -
token_periodの設定時間が一度過ぎると二度とvault token renewで更新できなくなる。 - クライアントがVault AgentやSecrets Operatorを利用している場合は自動で
vault token renewを実行してくれるためユーザーがtoken_ttlのリセットを意識する必要はない。また、システム障害などでvault token renewを実行出来ずにtoken_periodの設定時間が過ぎてしまった場合は再度Auth Methodの認証から実行される。
- 上記の周期を過ぎる前にクライアントが
-
token_explicit_max_ttl：Periodic tokenでも有効期限を無制限にしたくない場合に設定する最大TTLである。token_ttl,token_max_ttlが本パラメータより長い有効期限だとしても優先される。
設計のポイント
最低限下記の２点を抑えておけば良い。
- CLI, APIでTokenを生成する場合はOrphan Tokenを指定すること。でないと親トークンのTTL切れに引きずられて想定外にトークンが無効となるかも。
- Long-livedなシステムの場合はPeriodic tokenとするために
token_periodを設定すること。（当然と言えば当然だが）これを設定しないと通常のtokenになる。
最後に
自身の理解度を上げることにもなるのでこれからもショートな纏め記事を書いて定期的に投稿していこうと思います。
HashiCorp Vault関連の記事は他にも投稿しているのでご興味あれば一読頂けると幸いです。（随時追加します。）
Discussion