mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
feat: docs for tls cert auth
This commit is contained in:
=
149
docs/documentation/platform/identities/tls-cert-auth.mdx
Normal file
149
docs/documentation/platform/identities/tls-cert-auth.mdx
Normal file
@@ -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**.
|
||||
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Now create a new TLS Certificate Auth Method.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
### 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>
|
||||
Reference in New Issue
Block a user