Files
doc-exports/docs/css/umn/css_01_0393.html
zhengxiu 2125539080 css umn 25.1.0 version
Reviewed-by: Pruthi, Vineet <vineet.pruthi@t-systems.com>
Co-authored-by: zhengxiu <zhengxiu@huawei.com>
Co-committed-by: zhengxiu <zhengxiu@huawei.com>
2025-07-04 09:10:17 +00:00

150 lines
23 KiB
HTML

<a name="css_01_0393"></a><a name="css_01_0393"></a>
<h1 class="topictitle1">Accessing an Elasticsearch Cluster Using LDAP</h1>
<div id="body8662426"><p id="css_01_0393__p165411423172414">The Light Directory Access Protocol (LDAP) is a lightweight version of the directory access protocol based on the X.500 standard. An LDAP service provides user authentication and authorization. Using the Security plugin for Open Distro for Elasticsearch, CSS adds Active Directory as an authentication backend for clusters, connecting them seamlessly to the LDAP service. This topic describes the steps needed to connect a CSS cluster to an LDAP service.</p>
<p id="css_01_0393__p177949162181">It also describes how to enable LDAP authentication for a CSS cluster to allow access by LDAP users of specific roles.</p>
<div class="section" id="css_01_0393__section5200846924"><h4 class="sectiontitle">Constraints</h4><p id="css_01_0393__p91303111539">Only Elasticsearch 7.10.2 security-mode clusters can be accessed through LDAP.</p>
</div>
<div class="section" id="css_01_0393__en-us_topic_0000001934179690_section1492122914118"><h4 class="sectiontitle">Preparations</h4><ul id="css_01_0393__en-us_topic_0000001934179690_ul115524012184"><li id="css_01_0393__en-us_topic_0000001934179690_li181191829144220">A security-mode Elasticsearch cluster has been created in CSS and its status is available.</li><li id="css_01_0393__li174051125172815">The LDAP service that is in the same VPC as the Elasticsearch cluster and the necessary user data have been prepared. For details, see <a href="https://www.openldap.org/doc/admin24/quickstart.html" target="_blank" rel="noopener noreferrer">the OpenLDAP document: A Quick-Start Guide</a>.</li></ul>
</div>
<div class="section" id="css_01_0393__en-us_topic_0000001934179690_section04055477115"><h4 class="sectiontitle">Accessing a Cluster</h4><ol id="css_01_0393__ol3820537123018"><li id="css_01_0393__li8820037193015"><span>Install an LDAP service on an ECS. If the LDAP service and user data have already been prepared, skip this step.</span><p><ol type="a" id="css_01_0393__ol52981356193310"><li id="css_01_0393__li18792558794">Create an ECS. The ECS must run a Windows OS and must be in the same VPC and security group as the security-mode Elasticsearch cluster of CSS. The Windows Server running on the ECS provides the built-in Active Directory service that supports the LDAP protocol.<p id="css_01_0393__p255733074219"><a name="css_01_0393__li18792558794"></a><a name="li18792558794"></a>For how to create an ECS, see .</p>
</li><li id="css_01_0393__li5731185614343">Log in to the ECS, and enable the Active Directory service. Create a domain, administrator, users, and user groups.</li></ol>
</p></li><li id="css_01_0393__li6735482334"><span>Modify the parameter settings of the security-mode Elasticsearch cluster on CSS. Configure a static parameter in <span class="filepath" id="css_01_0393__filepath669732110112"><b>elasticsearch.yml</b></span> to connect the cluster to the LDAP service.</span><p><ol type="a" id="css_01_0393__ol159291592501"><li id="css_01_0393__en-us_topic_0000001268594501_li1142971461017">Log in to the CSS management console.</li><li id="css_01_0393__li106203711104">In the navigation pane on the left, choose <span class="uicontrol" id="css_01_0393__uicontrol1832453633613"><b>Clusters &gt; Elasticsearch</b></span> to go to the cluster list.</li><li id="css_01_0393__en-us_topic_0000001268594501_li174291147108">Choose <strong id="css_01_0393__b7440357756132">Clusters</strong> in the navigation pane. On the <span class="wintitle" id="css_01_0393__wintitle2403102426132"><b>Clusters</b></span> page, click the name of the target cluster. The cluster information page is displayed.</li><li id="css_01_0393__en-us_topic_0000001268594501_li1277611425215">In the navigation pane on the left, choose <strong id="css_01_0393__b186607114010">Parameter Configurations</strong>. Click <strong id="css_01_0393__b19386256143916">Edit</strong>, and add the following to the <strong id="css_01_0393__b527018143407">Custom</strong> module:<ul id="css_01_0393__ul16651001734"><li id="css_01_0393__li5665606311"><strong id="css_01_0393__b26089449420">Parameter</strong>: opendistro_security.unsupported.restapi.allow_securityconfig_modification</li><li id="css_01_0393__li66656011317"><strong id="css_01_0393__b77035374215">Value</strong>: true</li></ul>
</li><li id="css_01_0393__en-us_topic_0000001268594501_li12682102113577">Click <strong id="css_01_0393__b386529314335">Submit</strong> above. In the displayed <strong id="css_01_0393__b16253300134335">Submit Configuration</strong> dialog box, select the box that says "I understand that the modification will take effect after the cluster is restarted." and click <strong id="css_01_0393__b12341862124335">Yes</strong>.<p id="css_01_0393__en-us_topic_0000001268594501_p0505822115818">If <strong id="css_01_0393__b1326184264110">Status</strong> is <strong id="css_01_0393__b332614264119">Succeeded</strong> in the parameter change list, the change has been saved. Up to 20 change records can be displayed.</p>
</li><li id="css_01_0393__en-us_topic_0000001268594501_li195461759181418">Return to the cluster list and choose <strong id="css_01_0393__b481561916422">More</strong> &gt; <strong id="css_01_0393__b1181551994210">Restart</strong> in the <strong id="css_01_0393__b12816111919425">Operation</strong> column to restart the cluster and make the change take effect.<ul id="css_01_0393__en-us_topic_0000001268594501_ul772201251714"><li id="css_01_0393__en-us_topic_0000001268594501_li97281231719">Until the cluster is restarted, <strong id="css_01_0393__b6685137976132">Configuration not updated</strong> will be displayed in the <strong id="css_01_0393__b7631685486132">Task Status</strong> column on the <strong id="css_01_0393__b15958754786132">Clusters</strong> page.</li><li id="css_01_0393__en-us_topic_0000001268594501_li77261231712">If the cluster is restarted after the change, and <strong id="css_01_0393__b16141437446132">Task Status</strong> still shows <strong id="css_01_0393__b12677587816132">Configuration error</strong>, the parameter configuration file has failed to be modified.</li></ul>
</li></ol>
</p></li><li id="css_01_0393__li102711655125018"><span>Configure a custom route for the cluster on the CSS console to connect the cluster to the LDAP service.</span><p><div class="notice" id="css_01_0393__note189571328413"><span class="noticetitle"><img src="public_sys-resources/notice_3.0-en-us.png"> </span><div class="noticebody"><p id="css_01_0393__p19957220415">The permission to configure custom routes for clusters is controlled using a whitelist. If you need this permission, submit a service ticket to apply for it.</p>
</div></div>
<ol type="a" id="css_01_0393__ol1799124310910"><li id="css_01_0393__li719675151220">Log in to the CSS management console.</li><li id="css_01_0393__li1319605114128">In the navigation pane on the left, choose <span class="uicontrol" id="css_01_0393__uicontrol823102319485"><b>Clusters</b></span>, and click a cluster type to go to the cluster list (Elasticsearch in this example).</li><li id="css_01_0393__li11196851201217">Choose <strong id="css_01_0393__b20895155514485">Clusters</strong> in the navigation pane. On the <span class="wintitle" id="css_01_0393__wintitle88955554481"><b>Clusters</b></span> page, click the name of the target cluster. The cluster information page is displayed.</li><li id="css_01_0393__li9955659121211">On the Cluster Information page, locate <strong id="css_01_0393__b17374152413616">Cluster Routing</strong>, and click <strong id="css_01_0393__b1840132354913">Modify</strong>.<ul id="css_01_0393__ul1313514256156"><li id="css_01_0393__li14135425131514"><strong id="css_01_0393__b1940834310495">IP Address</strong>: Enter the IP address of the LDAP server. If the LDAP service on the ECS is used, enter the IP address of the ECS. <strong id="css_01_0393__b1528812273515">Subnet Mask</strong>: Enter the subnet mask of the LDAP server. If the LDAP service on the ECS is used, enter the subnet mask of the ECS.</li><li id="css_01_0393__li54694111614"><strong id="css_01_0393__b1354403196132">Modification Type</strong>: Select <strong id="css_01_0393__b13639078596132">Add</strong>.</li></ul>
</li><li id="css_01_0393__li53441144151320">Click <strong id="css_01_0393__b4260328806132">OK</strong>.</li></ol>
</p></li><li id="css_01_0393__li56310371195"><span>Configure LDAP authentication for a security-mode Elasticsearch cluster.</span><p><ol type="a" id="css_01_0393__ol124574417618"><li id="css_01_0393__en-us_topic_0000001223594408_li1274916552817">Log in to the CSS management console.</li><li id="css_01_0393__li4300134432417">In the navigation pane on the left, choose <span class="uicontrol" id="css_01_0393__uicontrol195566334813"><b>Clusters &gt; Elasticsearch</b></span> to go to the cluster list.</li><li id="css_01_0393__li13300184442415">In the cluster list, locate the target cluster, and click <strong id="css_01_0393__b19329155318813">Kibana</strong> in the <strong id="css_01_0393__b1569418561081">Operation</strong> column.</li><li id="css_01_0393__en-us_topic_0000001223594408_li927171291011">On the Kibana console, click <strong id="css_01_0393__b10806857506132">Dev Tools</strong> in the navigation tree on the left.</li><li id="css_01_0393__li14711134142520">Run the following commands to configure LDAP authentication.<div class="note" id="css_01_0393__note884613445342"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><ul id="css_01_0393__en-us_topic_0000001934179690_ul132691950164211"><li id="css_01_0393__li1344814304355">Concepts used in an X.500 directory access protocol (including LDAP):<ul id="css_01_0393__ul2365133313513"><li id="css_01_0393__en-us_topic_0000001934179690_li162696507428">CN = Common Name</li><li id="css_01_0393__en-us_topic_0000001934179690_li1126995044215">OU = Organizational Unit</li><li id="css_01_0393__en-us_topic_0000001934179690_li1726917504420">DC = Domain Component</li><li id="css_01_0393__li1657511354554">DN = Distinguished Name</li></ul>
<p id="css_01_0393__p182607365355">The CN, OU, and DC must be provided in the correct order. Otherwise, authentication will fail.</p>
</li><li id="css_01_0393__li1565012471357">The configuration file consists of two parts: <span class="parmname" id="css_01_0393__parmname16848553123515"><b>authc</b></span> and <span class="parmname" id="css_01_0393__parmname1563615614354"><b>authz</b></span>.<ul id="css_01_0393__ul4259160369"><li id="css_01_0393__li108116318362"><strong id="css_01_0393__b178491657130">authc</strong> (authentication): verifies whether a user is truly who they claim they are (password verification).</li><li id="css_01_0393__li08126315366"><strong id="css_01_0393__b1015211341">authz</strong> (authorization): verifies what the current user has access to.</li></ul>
</li></ul>
</div></div>
<pre class="screen" id="css_01_0393__en-us_topic_0000001934179690_screen1763319230389">PUT _opendistro/_security/api/securityconfig/config
{
"dynamic": {
"authc": {
"basic_internal_auth_domain": {
"description": "Authenticate via HTTP Basic against internal users database",
"http_enabled": true,
"transport_enabled": true,
"order": 1,
"http_authenticator": {
"type": "basic",
"challenge": true
},
"authentication_backend": {
"type": "intern"
}
},
"ldap": {
"description": "Authenticate via LDAP or Active Directory",
"http_enabled": true,
"transport_enabled": true,
"order": 2,
"http_authenticator": {
"type": "basic",
"challenge": false
},
"authentication_backend": {
"type": "ldap",
"config": {
"enable_ssl": false,
"enable_start_tls": false,
"enable_ssl_client_auth": false,
"verify_hostnames": true,
<strong id="css_01_0393__b862465712614">"hosts": ["10.0.XXX.XXX:389"],</strong>
<strong id="css_01_0393__b93870152717">"bind_dn": "CN=adminAD,DC=test,DC=ldap,DC=com",</strong>
<strong id="css_01_0393__b52121952270">"password": "&lt;password&gt;",</strong>
<strong id="css_01_0393__b650931012710">"userbase": "OU=ITDepartment,DC=test,DC=ldap,DC=com",</strong>
"usersearch": "(sAMAccountName={0})",
"username_attribute": "uid"
}
}
}
},
"authz": {
"roles_from_myldap": {
"description": "Authorize via LDAP or Active Directory",
"http_enabled": true,
"transport_enabled": true,
"authorization_backend": {
"type": "ldap",
"config": {
"enable_ssl": false,
"enable_start_tls": false,
"enable_ssl_client_auth": false,
"verify_hostnames": true,
<strong id="css_01_0393__b128232051112711">"hosts": ["10.0.XXX.XXX:389"],</strong>
<strong id="css_01_0393__b15792154192717">"bind_dn": "CN=adminAD,DC=test,DC=ldap,DC=com",</strong>
<strong id="css_01_0393__b3366155811275">"password": "&lt;password&gt;",</strong>
<strong id="css_01_0393__b1998915300276">"rolebase": "OU=groups,DC=test,DC=ldap,DC=com",</strong>
"rolesearch": "(member={0})",
"userroleattribute": null,
"userrolename": "disabled",
"rolename": "CN",
"resolve_nested_roles": true,
<strong id="css_01_0393__b1292011112288">"userbase": "OU=ITDepartment,DC=test,DC=ldap,DC=com",</strong>
"usersearch": "(uid={0})"
}
}
}
}
}
}</pre>
<p id="css_01_0393__p168786396285">The parameters in <a href="#css_01_0393__en-us_topic_0000001934179690_table111741414338">Table 1</a> need to be modified based on the actual environment.</p>
<div class="tablenoborder"><a name="css_01_0393__en-us_topic_0000001934179690_table111741414338"></a><a name="en-us_topic_0000001934179690_table111741414338"></a><table cellpadding="4" cellspacing="0" summary="" id="css_01_0393__en-us_topic_0000001934179690_table111741414338" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Parameter description</caption><thead align="left"><tr id="css_01_0393__en-us_topic_0000001934179690_row91731411337"><th align="left" class="cellrowborder" valign="top" width="30%" id="mcps1.3.5.2.4.2.1.5.4.2.3.1.1"><p id="css_01_0393__en-us_topic_0000001934179690_p417131412333">Parameter</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="70%" id="mcps1.3.5.2.4.2.1.5.4.2.3.1.2"><p id="css_01_0393__en-us_topic_0000001934179690_p1263718492465">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="css_01_0393__en-us_topic_0000001934179690_row192601805113"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.1 "><p id="css_01_0393__en-us_topic_0000001934179690_p42611819514">hosts</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.2 "><p id="css_01_0393__en-us_topic_0000001934179690_p19866933485">Address of the LDAP service. The port number is 389. If the LDAP service on the ECS is used, enter the IP address of the ECS.</p>
</td>
</tr>
<tr id="css_01_0393__en-us_topic_0000001934179690_row73721818175113"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.1 "><p id="css_01_0393__en-us_topic_0000001934179690_p16372318165118">bind_dn</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.2 "><p id="css_01_0393__en-us_topic_0000001934179690_p2226185484720">It is similar to the LDAP user name (CN - OU - DC) and is used to access the LDAP server. Select a user name from the user data of the LDAP service.</p>
</td>
</tr>
<tr id="css_01_0393__en-us_topic_0000001934179690_row131711473319"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.1 "><p id="css_01_0393__en-us_topic_0000001934179690_p111791417336">password</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.2 "><p id="css_01_0393__en-us_topic_0000001934179690_p1965182024815">Password of the LDAP user configured using <span class="parmname" id="css_01_0393__parmname10910162783016"><b>bind_dn</b></span>.</p>
</td>
</tr>
<tr id="css_01_0393__en-us_topic_0000001934179690_row161711420338"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.1 "><p id="css_01_0393__en-us_topic_0000001934179690_p11713147339">userbase</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.2 "><p id="css_01_0393__en-us_topic_0000001934179690_p152562403482">After the LDAP service is connected, the DN that the user belongs to is obtained. In this example, all user information in the <span class="parmvalue" id="css_01_0393__parmvalue193384385751920"><b>ITDepartment</b></span> directory is synchronized.</p>
</td>
</tr>
<tr id="css_01_0393__en-us_topic_0000001934179690_row77231225134911"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.1 "><p id="css_01_0393__en-us_topic_0000001934179690_p98881546115115">rolebase</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.5.2.4.2.1.5.4.2.3.1.2 "><p id="css_01_0393__en-us_topic_0000001934179690_p2453105825015">The collection of permissions that can be configured for the <span class="parmname" id="css_01_0393__parmname133892043123217"><b>userbase</b></span> user group of the LDAP service.</p>
</td>
</tr>
</tbody>
</table>
</div>
</li></ol>
</p></li><li id="css_01_0393__li20757162262412"><span>Configure the mapping between LDAP user permissions and Elasticsearch permissions in the Elasticsearch security-mode cluster to enable fine-grained access control.</span><p><p id="css_01_0393__p10988121516394">The rolebase permissions group of the LDAP server must be mapped to the roles in the Elasticsearch cluster. <a href="#css_01_0393__fig196302320392">Figure 1</a> illustrates the mapping. For details about the configuration, see <a href="css_01_0417.html">Creating Users for an Elasticsearch Cluster and Granting Cluster Access</a>.</p>
<div class="fignone" id="css_01_0393__fig196302320392"><a name="css_01_0393__fig196302320392"></a><a name="fig196302320392"></a><span class="figcap"><b>Figure 1 </b>Permissions mapping</span><br><span><img id="css_01_0393__en-us_topic_0000001934179690_image02822048175411" src="en-us_image_0000002039717881.png"></span></div>
<ol type="a" id="css_01_0393__ol86081414119"><li id="css_01_0393__li432219824116">Log in to the CSS management console.</li><li id="css_01_0393__li93224812418">In the navigation pane on the left, choose <span class="uicontrol" id="css_01_0393__uicontrol132671637151213"><b>Clusters &gt; Elasticsearch</b></span> to go to the cluster list.</li><li id="css_01_0393__li83220884112">In the cluster list, locate the target cluster, and click <strong id="css_01_0393__b1386131618132">Kibana</strong> in the <strong id="css_01_0393__b17884720161310">Operation</strong> column. Log in to the Kibana console as user admin.</li><li id="css_01_0393__li932238114110">Choose <span class="uicontrol" id="css_01_0393__uicontrol1432210811417"><b>Security</b></span> in the navigation tree on the left. The <span class="uicontrol" id="css_01_0393__uicontrol1948414017149"><b>Security</b></span> page is displayed.</li><li id="css_01_0393__li12898131717474"><a name="css_01_0393__li12898131717474"></a><a name="li12898131717474"></a>Click <strong id="css_01_0393__b159351682145">Roles</strong> to go to the Open Distro Security Roles page. Click <span class="uicontrol" id="css_01_0393__uicontrol121651208494"><b>Create Role</b></span>, set <strong id="css_01_0393__b18151280495">Name</strong>, <strong id="css_01_0393__b168155283498">Cluster Permissions</strong>, <strong id="css_01_0393__b492063481520">Index Permissions</strong>, and <strong id="css_01_0393__b0373174311519">Tenant Permissions</strong>. Then click <strong id="css_01_0393__b8159105191611">Save Role Definition</strong> to save the role settings. The parameters are as follows:<ul id="css_01_0393__ul131906224139"><li id="css_01_0393__li722115417133">Name (name of the role)</li><li id="css_01_0393__li1048916410147">Cluster permissions</li><li id="css_01_0393__li172781023161411">Index permissions</li><li id="css_01_0393__li71911522191312">Tenant permissions</li></ul>
</li><li id="css_01_0393__li165251846104819">Click the newly created role, select <span class="uicontrol" id="css_01_0393__uicontrol66696159518"><b>Mapped users</b></span>, enter a permissions group of the LDAP service in <span class="parmname" id="css_01_0393__parmname53181440185113"><b>Backend roles</b></span>, and click <strong id="css_01_0393__b1393812219192">Map</strong>.</li><li id="css_01_0393__li1408144916524"><a name="css_01_0393__li1408144916524"></a><a name="li1408144916524"></a>Check the configuration result.<div class="fignone" id="css_01_0393__fig897723218524"><span class="figcap"><b>Figure 2 </b>Permissions mapping</span><br><span><img id="css_01_0393__en-us_topic_0000001934179690_image1868416179479" src="en-us_image_0000002003597932.png"></span></div>
</li><li id="css_01_0393__li089153085417">Repeat <a href="#css_01_0393__li12898131717474">5.e</a> to <a href="#css_01_0393__li1408144916524">5.g</a> to map other permissions groups.</li></ol>
</p></li><li id="css_01_0393__li143972029397"><span>Verify the result.</span><p><ol type="a" id="css_01_0393__ol11135275717"><li id="css_01_0393__li13908191555712">Log in to the CSS management console.</li><li id="css_01_0393__li59081915125720">In the navigation pane on the left, choose <span class="uicontrol" id="css_01_0393__uicontrol20453268236132"><b>Clusters &gt; Elasticsearch</b></span> to go to the cluster list.</li><li id="css_01_0393__li690871513577">In the cluster list, locate the target cluster, and click <strong id="css_01_0393__b16548526142016">Kibana</strong> in the <strong id="css_01_0393__b25488266209">Operation</strong> column. Use an LDAP user to log in to the Kibana console.<ul id="css_01_0393__ul8514124265716"><li id="css_01_0393__li1551424218574">If the login is successful, the configuration is successful, and users can access the Elasticsearch cluster through LDAP. The specific permissions authorized are controlled by role permissions configured in Elasticsearch.</li><li id="css_01_0393__li121413589596">If the login fails, contact technical support.</li></ul>
</li></ol>
</p></li></ol>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="css_01_0210.html">Accessing Elasticsearch Clusters</a></div>
</div>
</div>