docs(identities): ldap auth

2026-09-22 13:39:35 +00:00 · 2025-05-09 03:44:15 +04:00
parent c21873ac4b
commit 6addde2650
14 changed files with 294 additions and 50 deletions
--- a/docs/api-reference/endpoints/ldap-auth/attach.mdx
+++ b/docs/api-reference/endpoints/ldap-auth/attach.mdx
@@ -0,0 +1,4 @@
+---
+title: "Attach"
+openapi: "POST /api/v1/auth/ldap-auth/identities/{identityId}"
+---
--- a/docs/api-reference/endpoints/ldap-auth/login.mdx
+++ b/docs/api-reference/endpoints/ldap-auth/login.mdx
@@ -0,0 +1,4 @@
+---
+title: "Login"
+openapi: "POST /api/v1/auth/ldap-auth/login"
+---
--- a/docs/api-reference/endpoints/ldap-auth/retrieve.mdx
+++ b/docs/api-reference/endpoints/ldap-auth/retrieve.mdx
@@ -0,0 +1,4 @@
+---
+title: "Retrieve"
+openapi: "GET /api/v1/auth/ldap-auth/identities/{identityId}"
+---
--- a/docs/api-reference/endpoints/ldap-auth/revoke.mdx
+++ b/docs/api-reference/endpoints/ldap-auth/revoke.mdx
@@ -0,0 +1,4 @@
+---
+title: "Revoke"
+openapi: "DELETE /api/v1/auth/ldap-auth/identities/{identityId}"
+---
--- a/docs/api-reference/endpoints/ldap-auth/update.mdx
+++ b/docs/api-reference/endpoints/ldap-auth/update.mdx
@@ -0,0 +1,4 @@
+---
+title: "Update"
+openapi: "PATCH /api/v1/auth/ldap-auth/identities/{identityId}"
+---
--- a/docs/documentation/platform/identities/ldap-auth/general.mdx
+++ b/docs/documentation/platform/identities/ldap-auth/general.mdx
@@ -0,0 +1,92 @@
+---
+title: General
+description: "Learn how to authenticate with Infisical using LDAP."
+---
+
+
+<Note>
+  LDAP is a paid feature. If you're using Infisical Cloud, then it is available under the Enterprise Tier. If you're self-hosting Infisical, then you should contact sales@infisical.com to purchase an enterprise license to use it.
+</Note>
+
+**LDAP Auth** is an LDAP based authentication method that allows you to authenticate with Infisical using a machine identity configured with an [LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) directory.
+
+### Guide
+<Steps>
+  <Step title="Creating an identity">
+    To create an identity, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**.
+
+    ![Create identity](/images/platform/identities/ldap/identities-org-create-identity.png)
+
+    When creating an identity, you specify an organization level role for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles.
+
+    ![Create identity modal](/images/platform/identities/ldap/identities-org-create-identity-modal.png)
+
+    Now input a few details for your new identity. Here's some guidance for each field:
+
+    - Name (required): A friendly name for the identity.
+    - Role (required): A role from the Organization 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.
+  </Step>
+
+  <Step title="Configuring LDAP auth for your identity">
+    To configure LDAP auth for your identity, press the **Add Auth Method** button on the identity's page.
+
+    ![Add auth method](/images/platform/identities/ldap/identities-org-add-auth-method.png)
+    
+    Now select **LDAP Auth** from the list of available auth methods for the identity.
+
+    ![Select LDAP auth](/images/platform/identities/ldap/identities-org-add-auth-method-modal.png)
+    
+    
+    After selecting **LDAP Auth**, you'll see the form you need to fill out to configure LDAP auth for your identity. The following fields are available:
+
+    - `URL`: The LDAP server to connect to such as `ldap://ldap.your-org.com`, `ldaps://ldap.myorg.com:636` _(for connection over SSL/TLS)_, etc.
+    - `Bind DN`: The DN to bind to the LDAP server with.
+    - `Bind Pass`: The password to bind to the LDAP server with.
+    - `Search Base / DN`: Base DN under which to perform user search such as `ou=Users,dc=acme,dc=com`.
+    - `User Search Filter`: Template used to construct the LDAP user search filter such as `(uid={{username}})`; use literal `{{username}}` to have the given username used in the search. The default is `(uid={{username}})` which is compatible with several common directory schemas.
+    - `Required Attributes`: A key/value pair of attributes that must be present in the LDAP user entry for them to be authenticated. As an example, if you set key `uid` to value `user1,user2,user3`, then only users with `uid` of `user1`, `user2`, or `user3` will be able to login with this identity. Each value is a comma separated list of attributes.
+    - `CA Certificate`: The CA certificate to use when verifying the LDAP server certificate. This field is optional but recommended.
+    - `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 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.
+
+    Once you've filled out the form, press **Add** to save your changes.
+
+    ![Configure LDAP auth](/images/platform/identities/ldap/identities-org-configure-ldap.png)
+
+    <Step title="Authenticating with the identity">
+      After configuring LDAP auth for your identity, you can authenticate with the identity and obtain an access token, using your LDAP credentials.
+
+      ```bash
+        curl --request POST \
+          --url https://app.infisical.com/api/v1/auth/ldap-auth/login \
+          --header 'Content-Type: application/json' \
+          --data '{
+          "identityId": "<string>",
+          "username": "<string>",
+          "password": "<string>"
+        }'
+      ```
+
+      <Note>
+        For EU Cloud and Self-Hosted users, make sure to replace `https://app.infisical.com` with `https://eu.infisical.com` or your self-hosted instance's URL in the request URL.
+      </Note>
+
+      If successful, you'll receive an access token in the response body.
+
+      ```json
+      {
+        "accessToken": "your-access-token",
+        "expiresIn": 2592000,
+        "accessTokenMaxTTL": 2592000,
+        "tokenType": "Bearer"
+      }
+      ```
+
+      You can read more about the login API endpoint [here](/api-reference/endpoints/ldap-auth/login).
+    </Step>
+  </Step>
+</Steps>
--- a/docs/documentation/platform/identities/ldap-auth/jumpcloud.mdx
+++ b/docs/documentation/platform/identities/ldap-auth/jumpcloud.mdx
@@ -0,0 +1,102 @@
+---
+title: JumpCloud
+description: "Learn how to authenticate with Infisical using LDAP with JumpCloud."
+---
+
+
+<Note>
+  LDAP is a paid feature. If you're using Infisical Cloud, then it is available under the Enterprise Tier. If you're self-hosting Infisical, then you should contact sales@infisical.com to purchase an enterprise license to use it.
+</Note>
+
+**LDAP Auth** is an LDAP based authentication method that allows you to authenticate with Infisical using a machine identity configured with an [LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) directory.
+
+### Guide
+<Steps>
+
+  <Step title="Prepare LDAP in JumpCloud">
+    In JumpCloud, head to USER MANAGEMENT > Users and create a new user via the Manual user entry option.
+    This user will be used as a privileged service account to facilitate Infisical's ability to bind/search the LDAP directory.
+
+    Next after creating the user, under User Security Settings and Permissions > Permission Settings, check the box next to Enable as LDAP Bind DN.
+
+    ![User management](/images/platform/identities/ldap/jumpcloud-users-management.png)
+  </Step>
+
+  <Step title="Creating an identity">
+    To create an identity, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**.
+
+    ![Create identity](/images/platform/identities/ldap/identities-org-create-identity.png)
+
+    When creating an identity, you specify an organization level role for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles.
+
+    ![Create identity modal](/images/platform/identities/ldap/identities-org-create-identity-modal.png)
+
+    Now input a few details for your new identity. Here's some guidance for each field:
+
+    - Name (required): A friendly name for the identity.
+    - Role (required): A role from the Organization 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.
+  </Step>
+
+  <Step title="Configuring LDAP auth for your identity">
+    To configure LDAP auth for your identity, press the **Add Auth Method** button on the identity's page.
+
+    ![Add auth method](/images/platform/identities/ldap/identities-org-add-auth-method.png)
+    
+    Now select **LDAP Auth** from the list of available auth methods for the identity.
+
+    ![Select LDAP auth](/images/platform/identities/ldap/identities-org-add-auth-method-modal.png)
+    
+    
+    After selecting **LDAP Auth**, you'll see the form you need to fill out to configure LDAP auth for your identity. The following fields are available:
+
+    - `URL`: The LDAP server to connect to (`ldaps://ldap.jumpcloud.com:636`).
+    - `Bind DN`: The distinguished name of object to bind when performing the user search (`uid=<ldap-user-username>,ou=Users,o=<your-org-id>,dc=jumpcloud,dc=com`).
+    - `Bind Pass`: The password to use along with Bind DN when performing the user search. This is the password for the user created in the previous step.
+    - `Search Base / DN`: Base DN under which to perform user search (`ou=Users,o=<your-org-id>,dc=jumpcloud,dc=com`).
+    - `User Search Filter`: Template used to construct the LDAP user search filter (`(uid={{username}})`).
+    - `Required Attributes`: A key/value pair of attributes that must be present in the LDAP user entry for them to be authenticated. As an example, if you set key `uid` to value `user1,user2,user3`, then only users with `uid` of `user1`, `user2`, or `user3` will be able to login with this identity. Each value is a comma separated list of attributes.
+    - `CA Certificate`: The CA certificate to use when verifying the LDAP server certificate (instructions to obtain the certificate for JumpCloud [here](https://jumpcloud.com/support/connect-to-ldap-with-tls-ssl)).
+    - `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 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.
+
+    Once you've filled out the form, press **Add** to save your changes.
+
+    ![Configure LDAP auth](/images/platform/identities/ldap/identities-org-configure-ldap.png)
+
+    <Step title="Authenticating with the identity">
+      After configuring LDAP auth for your identity, you can authenticate with the identity and obtain an access token, using your LDAP credentials.
+
+      ```bash
+        curl --request POST \
+          --url https://app.infisical.com/api/v1/auth/ldap-auth/login \
+          --header 'Content-Type: application/json' \
+          --data '{
+          "identityId": "<string>",
+          "username": "<string>",
+          "password": "<string>"
+        }'
+      ```
+
+      <Note>
+        For EU Cloud and Self-Hosted users, make sure to replace `https://app.infisical.com` with `https://eu.infisical.com` or your self-hosted instance's URL in the request URL.
+      </Note>
+
+      If successful, you'll receive an access token in the response body.
+
+      ```json
+      {
+        "accessToken": "your-access-token",
+        "expiresIn": 2592000,
+        "accessTokenMaxTTL": 2592000,
+        "tokenType": "Bearer"
+      }
+      ```
+
+      You can read more about the login API endpoint [here](/api-reference/endpoints/ldap-auth/login).
+    </Step>
+  </Step>
+</Steps>
--- a/docs/images/platform/identities/ldap/identities-org-add-auth-method-modal.png
+++ b/docs/images/platform/identities/ldap/identities-org-add-auth-method-modal.png
--- a/docs/images/platform/identities/ldap/identities-org-add-auth-method.png
+++ b/docs/images/platform/identities/ldap/identities-org-add-auth-method.png
--- a/docs/images/platform/identities/ldap/identities-org-configure-ldap.png
+++ b/docs/images/platform/identities/ldap/identities-org-configure-ldap.png
--- a/docs/images/platform/identities/ldap/identities-org-create-identity-modal.png
+++ b/docs/images/platform/identities/ldap/identities-org-create-identity-modal.png
--- a/docs/images/platform/identities/ldap/identities-org-create-identity.png
+++ b/docs/images/platform/identities/ldap/identities-org-create-identity.png
--- a/docs/images/platform/identities/ldap/jumpcloud-users-management.png
+++ b/docs/images/platform/identities/ldap/jumpcloud-users-management.png
--- a/docs/mint.json
+++ b/docs/mint.json
@@ -247,68 +247,88 @@
    {
      "group": "Authentication Methods",
      "pages": [
-        "documentation/platform/auth-methods/email-password",
-        "documentation/platform/token",
-        "documentation/platform/identities/token-auth",
-        "documentation/platform/identities/universal-auth",
-        "documentation/platform/identities/kubernetes-auth",
-        "documentation/platform/identities/gcp-auth",
-        "documentation/platform/identities/azure-auth",
-        "documentation/platform/identities/aws-auth",
-        "documentation/platform/identities/jwt-auth",
        {
-          "group": "OIDC Auth",
+          "group": "User Authentication",
          "pages": [
-            "documentation/platform/identities/oidc-auth/general",
-            "documentation/platform/identities/oidc-auth/github",
-            "documentation/platform/identities/oidc-auth/circleci",
-            "documentation/platform/identities/oidc-auth/gitlab",
-            "documentation/platform/identities/oidc-auth/terraform-cloud"
-          ]
-        },
-        "documentation/platform/mfa",
-        {
-          "group": "SSO",
-          "pages": [
-            "documentation/platform/sso/overview",
-            "documentation/platform/sso/google",
-            "documentation/platform/sso/github",
-            "documentation/platform/sso/gitlab",
-            "documentation/platform/sso/okta",
-            "documentation/platform/sso/azure",
-            "documentation/platform/sso/jumpcloud",
-            "documentation/platform/sso/keycloak-saml",
-            "documentation/platform/sso/google-saml",
-            "documentation/platform/sso/auth0-saml",
+            "documentation/platform/auth-methods/email-password",
            {
-              "group": "Keycloak OIDC",
+              "group": "SSO",
              "pages": [
-                "documentation/platform/sso/keycloak-oidc/overview",
-                "documentation/platform/sso/keycloak-oidc/group-membership-mapping"
+                "documentation/platform/sso/overview",
+                "documentation/platform/sso/google",
+                "documentation/platform/sso/github",
+                "documentation/platform/sso/gitlab",
+                "documentation/platform/sso/okta",
+                "documentation/platform/sso/azure",
+                "documentation/platform/sso/jumpcloud",
+                "documentation/platform/sso/keycloak-saml",
+                "documentation/platform/sso/google-saml",
+                "documentation/platform/sso/auth0-saml",
+                {
+                  "group": "Keycloak OIDC",
+                  "pages": [
+                    "documentation/platform/sso/keycloak-oidc/overview",
+                    "documentation/platform/sso/keycloak-oidc/group-membership-mapping"
+                  ]
+                },
+                "documentation/platform/sso/auth0-oidc",
+                "documentation/platform/sso/general-oidc"
              ]
            },
-            "documentation/platform/sso/auth0-oidc",
-            "documentation/platform/sso/general-oidc"
+            {
+              "group": "LDAP",
+              "pages": [
+                "documentation/platform/ldap/overview",
+                "documentation/platform/ldap/jumpcloud",
+                "documentation/platform/ldap/general"
+              ]
+            },
+            {
+              "group": "SCIM",
+              "pages": [
+                "documentation/platform/scim/overview",
+                "documentation/platform/scim/okta",
+                "documentation/platform/scim/azure",
+                "documentation/platform/scim/jumpcloud",
+                "documentation/platform/scim/group-mappings"
+              ]
+            }
          ]
        },
+
        {
-          "group": "LDAP",
+          "group": "Machine Identities",
          "pages": [
-            "documentation/platform/ldap/overview",
-            "documentation/platform/ldap/jumpcloud",
-            "documentation/platform/ldap/general"
-          ]
-        },
-        {
-          "group": "SCIM",
-          "pages": [
-            "documentation/platform/scim/overview",
-            "documentation/platform/scim/okta",
-            "documentation/platform/scim/azure",
-            "documentation/platform/scim/jumpcloud",
-            "documentation/platform/scim/group-mappings"
+            "documentation/platform/identities/token-auth",
+            "documentation/platform/identities/universal-auth",
+            "documentation/platform/identities/kubernetes-auth",
+            "documentation/platform/identities/gcp-auth",
+            "documentation/platform/identities/azure-auth",
+            "documentation/platform/identities/aws-auth",
+            "documentation/platform/identities/jwt-auth",
+
+            {
+              "group": "OIDC Auth",
+              "pages": [
+                "documentation/platform/identities/oidc-auth/general",
+                "documentation/platform/identities/oidc-auth/github",
+                "documentation/platform/identities/oidc-auth/circleci",
+                "documentation/platform/identities/oidc-auth/gitlab",
+                "documentation/platform/identities/oidc-auth/terraform-cloud"
+              ]
+            },
+
+            {
+              "group": "LDAP Auth",
+              "pages": [
+                "documentation/platform/identities/ldap-auth/general",
+                "documentation/platform/identities/ldap-auth/jumpcloud"
+              ]
+            }
          ]
        },
+        "documentation/platform/token",        
+        "documentation/platform/mfa",
        "documentation/platform/github-org-sync"
      ]
    },
@@ -715,6 +735,16 @@
            "api-reference/endpoints/jwt-auth/revoke"
          ]
        },
+        {
+          "group": "LDAP Auth",
+          "pages": [
+            "api-reference/endpoints/ldap-auth/login",
+            "api-reference/endpoints/ldap-auth/attach",
+            "api-reference/endpoints/ldap-auth/retrieve",
+            "api-reference/endpoints/ldap-auth/update",
+            "api-reference/endpoints/ldap-auth/revoke"
+          ]
+        },
        {
          "group": "Groups",
          "pages": [