feat: docs for tls cert auth

docs/api-reference/endpoints/tls-cert-auth/attach.mdx

@@ -0,0 +1,4 @@
+---
+title: "Attach"
+openapi: "POST /api/v1/auth/tls-cert-auth/identities/{identityId}"
+---

docs/api-reference/endpoints/tls-cert-auth/login.mdx

@@ -0,0 +1,4 @@
+---
+title: "Login"
+openapi: "POST /api/v1/auth/tls-cert-auth/login"
+---

docs/api-reference/endpoints/tls-cert-auth/retrieve.mdx

@@ -0,0 +1,4 @@
+---
+title: "Retrieve"
+openapi: "GET /api/v1/auth/tls-cert-auth/identities/{identityId}"
+---

docs/api-reference/endpoints/tls-cert-auth/revoke.mdx

@@ -0,0 +1,4 @@
+---
+title: "Revoke"
+openapi: "DELETE /api/v1/auth/tls-cert-auth/identities/{identityId}"
+---

docs/api-reference/endpoints/tls-cert-auth/update.mdx

@@ -0,0 +1,4 @@
+---
+title: "Update"
+openapi: "PATCH /api/v1/auth/tls-cert-auth/identities/{identityId}"
+---

docs/docs.json

@@ -280,7 +280,6 @@
               {
                 "group": "Machine Identities",
                 "pages": [
-                  "documentation/platform/identities/alicloud-auth",
                   "documentation/platform/identities/aws-auth",
                   "documentation/platform/identities/azure-auth",
                   "documentation/platform/identities/gcp-auth",
@@ -289,6 +288,8 @@
                   "documentation/platform/identities/oci-auth",
                   "documentation/platform/identities/token-auth",
                   "documentation/platform/identities/universal-auth",
+                  "documentation/platform/identities/alicloud-auth",
+                  "documentation/platform/identities/tls-cert-auth",
                   {
                     "group": "OIDC Auth",
                     "pages": [
@@ -748,6 +749,16 @@
                   "api-reference/endpoints/alicloud-auth/revoke"
                 ]
               },
+              {
+                "group": "TLS Certificate Auth",
+                "pages": [
+                  "api-reference/endpoints/tls-cert-auth/login",
+                  "api-reference/endpoints/tls-cert-auth/attach",
+                  "api-reference/endpoints/tls-cert-auth/retrieve",
+                  "api-reference/endpoints/tls-cert-auth/update",
+                  "api-reference/endpoints/tls-cert-auth/revoke"
+                ]
+              },
               {
                 "group": "AWS Auth",
                 "pages": [

docs/documentation/platform/identities/tls-cert-auth.mdx

@@ -0,0 +1,149 @@
+---
+title: TLS Certificate Auth
+description: "Learn how to authenticate with Infisical using TLS Certificate."
+---
+
+**TLS Certificate Auth** is an authentication method that verifies a user's TLS Client certificate using the provided CA Certificate, allowing secure access to Infisical resources.
+
+## Diagram
+
+The following sequence diagram illustrates the TLS Certificate Auth workflow for authenticating users with Infisical.
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Infisical
+
+  Note over Client,Client: Step 1: Setup your TLS request with the client certificate
+
+  Note over Client,Infisical: Step 2: Login Operation
+  Client->>Infisical: Send request to /api/v1/auth/tls-cert-auth/login
+
+  Note over Infisical: Step 3: Request verification using CA Certificate
+
+  Infisical->>Client: Return short-lived access token
+
+  Note over Client,Infisical: Step 5: Access Infisical API with token
+  Client->>Infisical: Make authenticated requests using the short-lived access token
+```
+
+## Concept
+
+At a high level, Infisical authenticates the client's TLS Certificate by verifying its identity and checking that it meets specific requirements (e.g., it is bound to the allowed common names) at the `/api/v1/auth/tls-cert-auth/login` endpoint. If successful, Infisical returns a short-lived access token that can be used to make authenticated requests to the Infisical API.
+
+To be more specific:
+
+1. The client sends a TLS request with the client certificate to Infisical at the `/api/v1/auth/tls-cert-auth/login endpoint.`
+2. Infisical verifies the incoming request using the provided CA certificate.
+3. Infisical checks the user's properties against set criteria such as Allowed Common Names.
+4. If all checks pass, Infisical returns a short-lived access token that the client can use to make authenticated requests to the Infisical API.
+
+<Accordion title="TLS with Load Balancer/Proxy">
+  Most of the time, the Infisical server will be behind a load balancer or
+  proxy. To propagate the TLS certificate from the load balancer to the
+  instance, you can configure the TLS to send the client certificate as a header
+  that is set as an [environment
+  variable](/self-hosting/configuration/envars#param-identity-tls-cert-auth-client-certificate-header-key).
+</Accordion>
+
+## Guide
+
+In the following steps, we explore how to create and use identities for your workloads and applications on TLS Certificate to
+access the Infisical API using request signing.
+
+### Creating an identity
+
+To create an identity, head to your Organization Settings > Access Control > [Identities](https://app.infisical.com/organization/access-management?selectedTab=identities) and press **Create identity**.
+
+![identities organization](/images/platform/identities/identities-org.png)
+
+When creating an identity, you specify an organization-level [role](/documentation/platform/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > [Organization Roles](https://app.infisical.com/organization/access-management?selectedTab=roles).
+
+![identities organization create](/images/platform/identities/identities-org-create.png)
+
+Input some details for your new identity:
+
+- **Name (required):** A friendly name for the identity.
+- **Role (required):** A role from the [**Organization Roles**](https://app.infisical.com/organization/access-management?selectedTab=roles) tab for the identity to assume. The organization role assigned will determine what organization-level resources this identity can have access to.
+
+Once you've created an identity, you'll be redirected to a page where you can manage the identity.
+
+![identities page](/images/platform/identities/identities-page.png)
+
+Since the identity has been configured with [Universal Auth](https://infisical.com/docs/documentation/platform/identities/universal-auth) by default, you should reconfigure it to use TLS Certificate Auth instead. To do this, click the cog next to **Universal Auth** and then select **Delete** in the options dropdown.
+
+![identities press cog](/images/platform/identities/identities-press-cog.png)
+
+![identities page remove default auth](/images/platform/identities/identities-page-remove-default-auth.png)
+
+Now create a new TLS Certificate Auth Method.
+
+![identities create tls cert auth method](/images/platform/identities/identities-tls-cert-auth-create-auth.png)
+
+Here's some information about each field:
+
+- **CA Certificate:** A PEM encoded CA Certificate used to validate incoming TLS request client certificate.
+- **Allowed Common Names:** A Comma seperated list of client certificate common names allowed.
+- **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 an infinite number of uses.
+- **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.
+
+### Adding an identity to a project
+
+In order to allow an identity to access project-level resources such as secrets, you must add it to the relevant projects.
+
+To do this, head over to the project you want to add the identity to and navigate to Project Settings > Access Control > Machine Identities and press **Add Identity**.
+
+![identities project](/images/platform/identities/identities-project.png)
+
+Select the identity you want to add to the project and the project-level role you want it to assume. The project role given to the identity will determine what project-level resources this identity can access.
+
+![identities project create](/images/platform/identities/identities-project-create.png)
+
+### Accessing the Infisical API with the identity
+
+To access the Infisical API as the identity, you need to send a TLS request to `/api/v1/auth/tls-cert-auth/login` endpoint.
+
+Below is an example of how you can authenticate with Infisical using NodeJS.
+
+```javascript
+const fs = require("fs");
+const https = require("https");
+const axios = require("axios");
+
+try {
+  const clientCertificate = fs.readFileSync("client-cert.pem", "utf8");
+  const clientKeyCertificate = fs.readFileSync("client-key.pem", "utf8");
+
+  const infisicalUrl = "https://app.infisical.com"; // or your self-hosted Infisical URL
+  const identityId = "<your-identity-id>";
+
+  // Create HTTPS agent with client certificate and key
+  const httpsAgent = new https.Agent({
+    cert: clientCertificate,
+    key: clientKeyCertificate,
+  });
+
+  const { data } = await axios.post(
+    `{infisicalUrl}/api/v1/auth/tls-cert-auth/login`,
+    {
+      identityId,
+    },
+    {
+      httpsAgent: httpsAgent, // Pass the HTTPS agent with client cert
+    },
+  );
+
+  console.log("result data: ", data); // access token here
+} catch (err) {
+  console.error(err);
+}
+```
+
+<Note>
+    Each identity access token has a time-to-live (TTL) which you can infer from the response of the login operation; the default TTL is `7200` seconds, which can be adjusted.
+
+    If an identity access token expires, it can no longer access the Infisical API. A new access token should be obtained by performing another login operation.
+
+</Note>

docs/self-hosting/configuration/envars.mdx

@@ -32,7 +32,7 @@ Used to configure platform-specific security and operational settings
 <ParamField query="HOST" type="string" default="localhost" optional>
   Specifies the network interface Infisical will bind to when accepting incoming connections.
 
-  By default, Infisical binds to `localhost`, which restricts access to connections from the same machine.
+By default, Infisical binds to `localhost`, which restricts access to connections from the same machine.
 
 To make the application accessible externally (e.g., for self-hosted deployments), set this to `0.0.0.0`, which tells the server to listen on all network interfaces.
 
@@ -122,6 +122,7 @@ DB_READ_REPLICAS=[{"DB_CONNECTION_URI":""}]
 </ParamField>
 
 ### Redis
+
 Redis is used for caching and background tasks. You can use either a standalone Redis instance or a Redis Sentinel setup.
 
 <Tabs>
@@ -199,8 +200,17 @@ Without email configuration, Infisical's core functions like sign-up/login and s
   connection can not be encrypted then message is not sent.
 </ParamField>
 
-<ParamField query="SMTP_TLS_REJECT_UNAUTHORIZED" type="bool" default="true" optional>
+<ParamField
-  If this is `true`, Infisical will validate the server's SSL/TLS certificate and reject the connection if the certificate is invalid or not trusted. If set to `false`, the client will accept the server's certificate regardless of its validity, which can be useful in development or testing environments but is not recommended for production use.
+  query="SMTP_TLS_REJECT_UNAUTHORIZED"
+  type="bool"
+  default="true"
+  optional
+>
+  If this is `true`, Infisical will validate the server's SSL/TLS certificate
+  and reject the connection if the certificate is invalid or not trusted. If set
+  to `false`, the client will accept the server's certificate regardless of its
+  validity, which can be useful in development or testing environments but is
+  not recommended for production use.
 </ParamField>
 
 <ParamField query="SMTP_CUSTOM_CA_CERT" type="string" default="none" optional>
@@ -211,6 +221,7 @@ Without email configuration, Infisical's core functions like sign-up/login and s
     Infisical highly encourages the following variables be used alongside this one for maximum security:
     - `SMTP_REQUIRE_TLS=true`
     - `SMTP_TLS_REJECT_UNAUTHORIZED=true`
+
 </ParamField>
 </Accordion>
 
@@ -577,6 +588,7 @@ You can configure third-party app connections for re-use across Infisical Projec
     <ParamField query="INF_APP_CONNECTION_GITHUB_RADAR_APP_WEBHOOK_SECRET" type="string" default="none" optional>
         The webhook secret configured for payload verification in the GitHub Radar App
     </ParamField>
+
 </Accordion>
 
 <Accordion title="GitHub OAuth Connection">
@@ -760,3 +772,14 @@ If export type is set to `otlp`, you will have to configure a value for `OTEL_EX
 <ParamField query="OTEL_COLLECTOR_BASIC_AUTH_PASSWORD" type="string">
   The password for authenticating with the telemetry collector.
 </ParamField>
+
+## Identity Auth Method
+
+<ParamField
+  query="IDENTITY_TLS_CERT_AUTH_CLIENT_CERTIFICATE_HEADER_KEY"
+  type="string"
+  default="x-identity-tls-cert-auth-client-cert"
+>
+  The TLS header used to propagate the client certificate from the load balancer
+  to the server.
+</ParamField>