Merge pull request #4533 from Infisical/add-lockout-docs

feat: lockout docs for UA

docs/documentation/platform/identities/machine-identities.mdx

@@ -38,6 +38,16 @@ To interact with various resources in Infisical, Machine Identities can authenti
 - [GCP Auth](/documentation/platform/identities/gcp-auth): A GCP-native authentication method for GCP resources (e.g. Compute Engine, App Engine, Cloud Run, Google Kubernetes Engine, IAM service accounts, etc.).
 - [OIDC Auth](/documentation/platform/identities/oidc-auth): A platform-agnostic, JWT-based authentication method for workloads using an OpenID Connect identity provider.
 
+## Identity Lockout
+
+Lockout is a feature that prevents brute-force attacks on identity login endpoints. Auth methods that support lockout include: [Universal Auth](/documentation/platform/identities/universal-auth).
+
+Supported auth methods have lockout enabled by default. If triggered, lockout temporarily disables the login endpoint for 5 minutes after 3 consecutive failed login attempts within a 30-second window. Lockout can be configured and disabled in the identity auth method settings.
+
+<Warning>
+    When Lockout is enabled, a rate limit of approximately 10 requests per second is enforced on relevant authentication endpoints. This security measure employs a protective lock to mitigate parallel login attacks. If this rate limitation interferes with your operational requirements, you may consider disabling Lockout.
+</Warning>
+
 ## FAQ
 
 <AccordionGroup>
@@ -51,15 +61,15 @@ You can learn more about how to do this in the CLI quickstart [here](/cli/usage)
 
 <Accordion title="What is the difference between an identity and service token?">
   A service token is a project-level authentication method that is being deprecated in favor of identities. The service token method will be removed in the future in accordance with the deprecation notice and timeline stated [here](https://infisical.com/blog/deprecating-api-keys).
-  
+
   Amongst many differences, identities provide broader access over the Infisical API, utilizes the same
   permission system as user identities, and come with a significantly larger number of configurable authentication and security features.
-  
+
   If you're looking for a simple authentication method, similar to service tokens, that can be bound onto an identity, we recommend checking out [Token Auth](/documentation/platform/identities/token-auth).
 </Accordion>
 <Accordion title="Why can I not create, read, update, or delete an identity?">
   There are a few reasons for why this might happen:
-  
+
   - You have insufficient organization permissions to create, read, update, delete identities.
   - The identity you are trying to read, update, or delete is more privileged than yourself.
   - The role you are trying to create an identity for or update an identity to is more privileged than yours.

docs/documentation/platform/identities/universal-auth.mdx

@@ -4,7 +4,7 @@ description: "Learn how to authenticate to Infisical from any platform or enviro
 ---
 
 **Universal Auth** is a platform-agnostic authentication method that can be configured for a [machine identity](/documentation/platform/identities/machine-identities) to authenticate from any platform/environment using a Client ID and Client Secret.
-This authentication method supports setting token periods, which can help [overcome secret zero](#solving-secret-zero-with-periodic-tokens). 
+This authentication method supports setting token periods, which can help [overcome secret zero](#solving-secret-zero-with-periodic-tokens).
 
 ## Diagram
 
@@ -65,17 +65,32 @@ using the Universal Auth authentication method.
     By default, the identity has been configured with Universal Auth. If you wish, you can edit the Universal Auth configuration
     details by pressing to edit the **Authentication** section.
 
+    Here's some guidance on each field:
+
+    **Configuration Tab**
+
     ![identities organization create universal auth method 1](/images/platform/identities/identities-org-create-universal-auth-method-1.png)
+
+    - Access Token TTL (default is `2592000` equivalent to 30 days): The lifetime for an access token in seconds. This value will be referenced at renewal time.
+    - Access Token Max TTL (default is `2592000`  equivalent to 30 days): The maximum lifetime for an access token in seconds. This value will be referenced at renewal time.
+    - Access Token Max Number of Uses (default is `0`): The maximum number of times that an access token can be used; a value of `0` implies infinite number of uses.
+    - Access Token Period (optional, default is `0`): If set, the access token becomes a renewable, non-expiring token for the specified period (in seconds). TTL and Max TTL are ignored when this is set. This is ideal for "secret zero" scenarios, where a workload needs to bootstrap itself securely without hard-coded static secrets.
+
+    **Lockout Tab**
+
     ![identities organization create universal auth method 2](/images/platform/identities/identities-org-create-universal-auth-method-2.png)
 
-    Here's some more guidance on each field:
+    - Lockout (enabled by default): The lockout feature will temporarily block login attempts after X consecutive login failures.
+    - Lockout Threshold (default is `3`): The amount of times login must fail before locking the identity auth method.
+    - Lockout Duration (default is `5 minutes`): How long an identity auth method lockout lasts.
+    - Lockout Counter Reset (default is `30 seconds`): How long to wait from the most recent failed login until resetting the lockout counter.
+
+    **Advanced Tab**
+
+    ![identities organization create universal auth method 3](/images/platform/identities/identities-org-create-universal-auth-method-3.png)
 
-    - Access Token TTL (default is `2592000` equivalent to 30 days): The lifetime for an acccess token in seconds. This value will be referenced at renewal time.
-    - Access Token Max TTL (default is `2592000`  equivalent to 30 days): The maximum lifetime for an acccess token in seconds. This value will be referenced at renewal time.
-    - Access Token Max Number of Uses (default is `0`): The maximum number of times that an access token can be used; a value of `0` implies infinite number of uses.
     - Client Secret Trusted IPs: The IPs or CIDR ranges that the **Client Secret** can be used from together with the **Client ID** to get back an access token. By default, **Client Secrets** are given the `0.0.0.0/0`, allowing usage from any network address.
     - Access Token Trusted IPs: The IPs or CIDR ranges that access tokens can be used from. By default, each token is given the `0.0.0.0/0`, allowing usage from any network address.
-    - Access Token Period (optional, default is `0`): If set, the access token becomes a renewable, non-expiring token for the specified period (in seconds). TTL and Max TTL are ignored when this is set. This is ideal for "secret zero" scenarios, where a workload needs to bootstrap itself securely without hard-coded static secrets.
 
     <Warning>
     Restricting **Client Secret** and access token usage to specific trusted IPs is a paid feature.
@@ -202,6 +217,10 @@ This approach allows your workload to securely bootstrap and maintain access to
 
     A token can be renewed any number of times where each call to renew it can extend the token's lifetime by increments of the access token's TTL.
     Regardless of how frequently an access token is renewed, its lifespan remains bound to the maximum TTL determined at its creation.
+  </Accordion>
+  <Accordion title="How do I reset a lockout?">
+      You can reset (remove) all lockouts for an identity auth method by clicking into the auth method and pressing **Reset All Lockouts**.
 
+      ![ua reset lockouts](/images/platform/identities/ua-reset-lockouts.png)
   </Accordion>
 </AccordionGroup>