luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Vault documentation: updated What is a Client section (#13816) 

* updated client doc

* fixed heading
This commit is contained in:
Loann Le 2022-02-07 09:05:10 -08:00 committed by GitHub
parent 7145fe49ff
commit f85945d3aa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 57 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
website/content/docs/concepts/client-count/index.mdx
View File

@ -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