From f85945d3aa1525c3f3403fd2d050c651e11e4f06 Mon Sep 17 00:00:00 2001 From: Loann Le <84412881+taoism4504@users.noreply.github.com> Date: Mon, 7 Feb 2022 09:05:10 -0800 Subject: [PATCH] Vault documentation: updated What is a Client section (#13816) * updated client doc * fixed heading --- .../docs/concepts/client-count/index.mdx | 92 ++++++++++++------- 1 file changed, 57 insertions(+), 35 deletions(-) diff --git a/website/content/docs/concepts/client-count/index.mdx b/website/content/docs/concepts/client-count/index.mdx index 4cd37d7d1..49a3dc231 100644 --- a/website/content/docs/concepts/client-count/index.mdx +++ b/website/content/docs/concepts/client-count/index.mdx @@ -3,6 +3,7 @@ layout: docs page_title: Client Count description: Counting the number of clients accessing Vault. --- + # What is a Client? Before we dive into understanding the approach used to [count the number of clients](#client-count) accessing Vault, we need to first understand what clients represent. @@ -54,7 +55,29 @@ Using the identity system allows for Vault to make sure that entities aren’t c ### Non-entity Tokens -If you chose to use the [Token Auth Method](/docs/auth/token) without an identity to avoid driving up client count, always assign each token to a role and entity alias. HashiCorp recommends creating a [Token Role](/api-docs/auth/token#create-update-token-role) first, with allowable entity aliases and issuing your token with the appropriate [role and entity alias name](/api-docs/auth/token#create-token). This is the name that will uniquely identify the client, no matter how many tokens are issued. See more on entity alias below. +If you chose to use the [Token Auth Method](/docs/auth/token) without an identity, always assign each token to a role and entity alias. HashiCorp recommends creating a [Token Role](/api-docs/auth/token#create-update-token-role) first, with allowable entity aliases and issuing your token with the appropriate [role and entity alias name](/api-docs/auth/token#create-token). This is the name that will uniquely identify the client, no matter how many tokens are issued. See more on entity alias below. + +### Differences between a direct entity and a non-entity token + +While the definition of clients appears to be simple on the surface, there are many nuances involved in the computation of clients. As mentioned, clients are unique applications, services, and/or users that authenticate to a Vault cluster. When anything authenticates to Vault, it is associated with a unique identity entity within the [Vault Identity system](/docs/secrets/identity). The name reported to the identity systems by the different types of authentication methods varies, and each entity is created or verified during authorization. + +One thing to note is that Vault clients are a combination of active identities as well as non-entity tokens. Identity entities are unique users, and when identities authenticate to Vault, corresponding tokens are generated. However, there are some situations in which tokens are generated without corresponding identities (e.g., when using the token auth method to create a token for someone else whose identity is unknown). As such, these non-entity tokens also represent users, and are counted towards the overall client aggregates. Here are some situations in which non-entity tokens get created within Vault. + +- Tokens within Vault are the core method for authentication. You can use Tokens to authenticate directly, or use the [auth methods](/docs/concepts/auth) to dynamically generate tokens based on external identities. +- There are scenarios where tokens are created outside of the identity system without an associated entity. For this reason, unique identity entities alone cannot always add up to the total unique authentications made to Vault over a stipulated time period. +- In a scenario where tokens are created outside of the identity system, these tokens are considered clients. Note that it should be rare for production usage to have any tokens created outside any identity systems. +- There are a few ways of creating tokens without entities: _Token Roles_, _Token Create APIs_, _Wrapping Tokens_, and _Control Groups_. For more information, refer to the [What is a Client?](/docs/concepts/client-count/#what-is-a-client) documentation. + +## Considerations for Namespaces + +Since namespaces represent logical isolations within a single Vault cluster for administrative purposes, consideration must be made on how Vault clients are determined in this context. + +1. If a client authenticates to Vault in a parent or root namespaces, it is considered the same client in all child namespaces. This is obvious as it is within the same logical isolation. +2. However if a client authenticates to Vault in two separate namespaces, because of logical isolation they are not considered as the same client. As an example, `/namespaceA/ldap/auth/login/bob` is not related to `/namespaceB/ldap/auth/login/bob`. If the intent is that “Bob” is the same client, authenticate into two namespaces: + 1. Move the auth to the parent workspace and any auth to child namespaces would be considered as the same client + 2. Place that auth in the root namespace to be considered as 1 client in all namespaces. + +See also the guide [Secure Multi-Tenancy with Namespaces | Vault](https://learn.hashicorp.com/tutorials/vault/namespaces). ## Authentication Methods and how they’re counted in Vault @@ -64,27 +87,26 @@ Each authentication method has a unique identifier to determine unique identity, How does this relate to Vault clients? As outlined above, and as an example, if you chose to identify a microservice by AppRole auth method, then assign a role id for that microservice. A role id is the microservice’s username and identity. You should not have different microservices use the same role id. Different microservices should use different role ids. However if microservices (or multiple VMs, or containers), are exact copies using the same role id, they will all have the same identity. This is the appropriate security posture to mitigate any risk, and an operator can easily approve or deny access to secrets for that one role id, without affecting other services. It is important as you choose an identity for each human, app, service, platform, server and pipeline, that you pay attention to the name below that makes each method unique and be given an identity. -| **Auth method** | **Name reported by auth method** | -| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | -| **[AliCloud](https://www.vaultproject.io/docs/auth/alicloud)** | Principal ID | -| **[AppRole](https://www.vaultproject.io/api-docs/auth/approle#create-update-approle)** | Role ID | -| **[AWS IAM](https://www.vaultproject.io/docs/auth/aws#iam-auth-method)** | Configurable via iam_alias to one of: Role ID (default), IAM unique ID, Full ARN | -| **[AWS EC2](https://www.vaultproject.io/docs/auth/aws#ec2-auth-method)** | Configurable via ec2_alias to one of: Role ID (default), EC2 instance ID, AMI ID | -| **[Azure](https://www.vaultproject.io/api-docs/auth/azure#create-role)** | Subject (from JWT claim) | -| **[Cloud Foundry](https://www.vaultproject.io/docs/auth/cf)** | App ID | -| **[GitHub](https://www.vaultproject.io/docs/auth/github)** | User login name associated with token | -| **[Google Cloud](https://www.vaultproject.io/api-docs/auth/gcp#create-role)** | Configurable via iam_alias to one of: Role ID (default), Service account unique ID | -| **[JWT/OIDC](https://www.vaultproject.io/api-docs/auth/jwt#create-role)** | Configurable via user_claim to one of the presented claims (no default value) | -| **[Kerberos](https://www.vaultproject.io/docs/auth/kerberos)** | Username | -| **[Kubernetes](https://www.vaultproject.io/api-docs/auth/kubernetes#create-role)** | Service account UID | -| **[LDAP](https://www.vaultproject.io/docs/auth/ldap)** | Username | -| **[OCI](https://www.vaultproject.io/api-docs/auth/oci#create-role)** | Rolename | -| **[Okta](https://www.vaultproject.io/api-docs/auth/okta#register-user)** | Username | -| **[RADIUS](https://www.vaultproject.io/docs/auth/radius)** | Username | -| **[TLS Certificate](https://www.vaultproject.io/api-docs/auth/cert#create-ca-certificate-role)** | Subject CommonName | -| **[Token](https://www.vaultproject.io/docs/auth/token)** | entity_alias, if provided (Note: please ensure that entity_alias is always used) | -| **[Username/Password](https://www.vaultproject.io/api-docs/auth/userpass#create-update-user)** | Username | - +| **Auth method** | **Name reported by auth method** | +| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| **[AliCloud](https://www.vaultproject.io/docs/auth/alicloud)** | Principal ID | +| **[AppRole](https://www.vaultproject.io/api-docs/auth/approle#create-update-approle)** | Role ID | +| **[AWS IAM](https://www.vaultproject.io/docs/auth/aws#iam-auth-method)** | Configurable via iam_alias to one of: Role ID (default), IAM unique ID, Full ARN | +| **[AWS EC2](https://www.vaultproject.io/docs/auth/aws#ec2-auth-method)** | Configurable via ec2_alias to one of: Role ID (default), EC2 instance ID, AMI ID | +| **[Azure](https://www.vaultproject.io/api-docs/auth/azure#create-role)** | Subject (from JWT claim) | +| **[Cloud Foundry](https://www.vaultproject.io/docs/auth/cf)** | App ID | +| **[GitHub](https://www.vaultproject.io/docs/auth/github)** | User login name associated with token | +| **[Google Cloud](https://www.vaultproject.io/api-docs/auth/gcp#create-role)** | Configurable via iam_alias to one of: Role ID (default), Service account unique ID | +| **[JWT/OIDC](https://www.vaultproject.io/api-docs/auth/jwt#create-role)** | Configurable via user_claim to one of the presented claims (no default value) | +| **[Kerberos](https://www.vaultproject.io/docs/auth/kerberos)** | Username | +| **[Kubernetes](https://www.vaultproject.io/api-docs/auth/kubernetes#create-role)** | Service account UID | +| **[LDAP](https://www.vaultproject.io/docs/auth/ldap)** | Username | +| **[OCI](https://www.vaultproject.io/api-docs/auth/oci#create-role)** | Rolename | +| **[Okta](https://www.vaultproject.io/api-docs/auth/okta#register-user)** | Username | +| **[RADIUS](https://www.vaultproject.io/docs/auth/radius)** | Username | +| **[TLS Certificate](https://www.vaultproject.io/api-docs/auth/cert#create-ca-certificate-role)** | Subject CommonName | +| **[Token](https://www.vaultproject.io/docs/auth/token)** | entity_alias, if provided (Note: please ensure that entity_alias is always used) | +| **[Username/Password](https://www.vaultproject.io/api-docs/auth/userpass#create-update-user)** | Username | ## Considerations with CI/CD @@ -108,14 +130,14 @@ The number of active clients using a Vault cluster is the total of: - active entities: identity entities that create a token via a login - active non-entity tokens: clients associated with tokens created via a method -that is not associated with an entity + that is not associated with an entity Prior to Vault 1.6, this metric could only be measured from the audit log, using the [`vault-auditor`](https://learn.hashicorp.com/tutorials/vault/usage-metrics#vault-auditor-tool) tool. Starting with Vault 1.6, the number of clients per month, or for a contiguous sequence of months, can be measured by Vault itself. As of Vault 1.9, the total client count should always be measured using Vault itself. The -metrics shown by the Vault UI are the source of truth for this data. +metrics shown by the Vault UI are the source of truth for this data. Please refer to [Vault Usage Metrics](https://learn.hashicorp.com/tutorials/vault/usage-metrics) for a step-by-step tutorial and description of how to use the UI. @@ -126,7 +148,7 @@ Each time a token is used, Vault checks to see whether it belongs to an identity that has already been active in the current month. New entities are added to a log in Vault storage periodically. Tokens without entities are tracked separately and added to the "non_entity_tokens" count. Please see the 'Tracking non-entity tokens' subsection below for a detailed explanation of how such -tokens are tracked by Vault. +tokens are tracked by Vault. At the end of each month, Vault creates precomputed reports listing the number of active entities, per namespace, in each time period within a configurable retention period. This process deduplicates @@ -196,26 +218,26 @@ To reduce the number of non-entity tokens in use, consider switching to an authe ### Tracking non-entity tokens As of Vault 1.9, non-entity tokens are tracked as unique clients based on the policies the token -has access to and the namespace in which it was created. Non-entity tokens that are assigned -the same set of policies and are created in the same namespace will be tracked as the same client. +has access to and the namespace in which it was created. Non-entity tokens that are assigned +the same set of policies and are created in the same namespace will be tracked as the same client. Conversely, if two non-entity tokens have a different policy set or are created in different namespaces, -they will be tracked as two separate clients. +they will be tracked as two separate clients. -Please note that before the release of Vault 1.9, non-entity tokens were each tracked separately. That is +Please note that before the release of Vault 1.9, non-entity tokens were each tracked separately. That is to say, two non-entity tokens would always be counted as two separate clients. ## Auditing clients As of Vault 1.9, the Vault Audit Log contains a `client_id` field in the request. The `client_id` field -contains an Entity ID for requests that are made with tokens with entities, or a unique client ID for -non-entity tokens. +contains an Entity ID for requests that are made with tokens with entities, or a unique client ID for +non-entity tokens. Consumers of the audit log will be able to distinguish between these two types of client IDs by comparing -the value in the `client_id` with the value of the `entity_id` in the `Auth` section of the response. If -the two values are the same, then the `client_id` is an `entity_id`. If not, then the `client_id` was -generated from the use of a non-entity token. +the value in the `client_id` with the value of the `entity_id` in the `Auth` section of the response. If +the two values are the same, then the `client_id` is an `entity_id`. If not, then the `client_id` was +generated from the use of a non-entity token. -An empty `client_id` field in a request means that Vault did not track a client for that +An empty `client_id` field in a request means that Vault did not track a client for that request; this can happen if the request is unauthenticated, or made with a root token or wrapped token. ## API and Permissions