diff --git a/docs/api-reference/endpoints/tls-cert-auth/attach.mdx b/docs/api-reference/endpoints/tls-cert-auth/attach.mdx new file mode 100644 index 000000000..35c3b87e9 --- /dev/null +++ b/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}" +--- diff --git a/docs/api-reference/endpoints/tls-cert-auth/login.mdx b/docs/api-reference/endpoints/tls-cert-auth/login.mdx new file mode 100644 index 000000000..0069ef1b7 --- /dev/null +++ b/docs/api-reference/endpoints/tls-cert-auth/login.mdx @@ -0,0 +1,4 @@ +--- +title: "Login" +openapi: "POST /api/v1/auth/tls-cert-auth/login" +--- diff --git a/docs/api-reference/endpoints/tls-cert-auth/retrieve.mdx b/docs/api-reference/endpoints/tls-cert-auth/retrieve.mdx new file mode 100644 index 000000000..d59b31d11 --- /dev/null +++ b/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}" +--- diff --git a/docs/api-reference/endpoints/tls-cert-auth/revoke.mdx b/docs/api-reference/endpoints/tls-cert-auth/revoke.mdx new file mode 100644 index 000000000..0d3ccda65 --- /dev/null +++ b/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}" +--- diff --git a/docs/api-reference/endpoints/tls-cert-auth/update.mdx b/docs/api-reference/endpoints/tls-cert-auth/update.mdx new file mode 100644 index 000000000..3bb8892ea --- /dev/null +++ b/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}" +--- diff --git a/docs/docs.json b/docs/docs.json index 2d0417778..967329b17 100644 --- a/docs/docs.json +++ b/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": [ diff --git a/docs/documentation/platform/identities/tls-cert-auth.mdx b/docs/documentation/platform/identities/tls-cert-auth.mdx new file mode 100644 index 000000000..be309bf41 --- /dev/null +++ b/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. + + + 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). + + +## 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 = ""; + + // 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); +} +``` + + + 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. + + diff --git a/docs/images/platform/identities/identities-tls-cert-auth-create-auth.png b/docs/images/platform/identities/identities-tls-cert-auth-create-auth.png new file mode 100644 index 000000000..2e66633e7 Binary files /dev/null and b/docs/images/platform/identities/identities-tls-cert-auth-create-auth.png differ diff --git a/docs/self-hosting/configuration/envars.mdx b/docs/self-hosting/configuration/envars.mdx index efce4d912..44e5c8f47 100644 --- a/docs/self-hosting/configuration/envars.mdx +++ b/docs/self-hosting/configuration/envars.mdx @@ -32,7 +32,7 @@ Used to configure platform-specific security and operational settings 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":""}] ### Redis + Redis is used for caching and background tasks. You can use either a standalone Redis instance or a Redis Sentinel setup. @@ -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. - - 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. + + 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. @@ -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` + @@ -577,6 +588,7 @@ You can configure third-party app connections for re-use across Infisical Projec The webhook secret configured for payload verification in the GitHub Radar App + @@ -760,3 +772,14 @@ If export type is set to `otlp`, you will have to configure a value for `OTEL_EX The password for authenticating with the telemetry collector. + +## Identity Auth Method + + + The TLS header used to propagate the client certificate from the load balancer + to the server. +