All Products
Search

This Product

    E-MapReduce:Configure and enable LDAP authentication for Kyuubi Gateway

    Document Center

    E-MapReduce:Configure and enable LDAP authentication for Kyuubi Gateway

    Last Updated:Mar 26, 2026

    LDAP authentication ensures that only users with valid credentials can connect to Kyuubi Server, start a Spark session, and run SQL queries. This topic describes how to configure LDAP authentication for Kyuubi Gateway.

    Prerequisites

    Before you begin, ensure that you have:

    • A Kyuubi Gateway and Token. For more information, see Manage Kyuubi Gateway

    • One of the following engine versions:

      • esr-4.x: esr-4.3.0 or later

      • esr-3.x: esr-3.3.0 or later

      • esr-2.x: esr-2.7.0 or later

    • (Optional) If you want to use the OpenLDAP service of an EMR on ECS cluster: an EMR on ECS cluster with OpenLDAP enabled and users added. For more information, see Create a cluster and OpenLDAP user management

    Step 1: Check network connectivity

    Kyuubi Gateway must be able to reach your LDAP service over the network. Verify network connectivity between EMR Serverless Spark and your Virtual Private Cloud (VPC) before proceeding. For more information, see Network connectivity between EMR Serverless Spark and other VPCs.

    Important

    If Kyuubi Gateway cannot reach the LDAP service, authentication fails at connection time even if all parameters are correctly configured. Resolve any network issues before moving to Step 2.

    Step 2: Configure Kyuubi Gateway

    1. Stop the active session on your Kyuubi Gateway.

    2. Open the Kyuubi Gateway editor and select your network connection from the Network Connectivity dropdown.

    3. Add the following parameters to Kyuubi Configuration:

      kyuubi.authentication                       LDAP
kyuubi.authentication.ldap.url              ldap://<ldap_url>:<ldap_port>/
kyuubi.authentication.ldap.baseDN           <ldap_base_dn>
kyuubi.authentication.ldap.userDNPattern    <ldap_user_pattern>
kyuubi.authentication.ldap.binddn           <ldap_bind_dn>
kyuubi.authentication.ldap.bindpw           <ldap_bind_pwd>

    4. Restart the Kyuubi Gateway for the changes to take effect.

    Parameter reference

    Replace the placeholder values based on your LDAP service. The examples below use an OpenLDAP setup.

    ParameterDescriptionExample (OpenLDAP)
    kyuubi.authenticationAuthentication type. Set to LDAP to enable LDAP authentication.LDAP
    kyuubi.authentication.ldap.urlConnection address of the LDAP service. Format: ldap://<host>:<port>/. Default port for OpenLDAP is 10389.ldap://master-1-1.c-xxxxxxxxxx.cn-hangzhou.emr.aliyuncs.com:10389/
    kyuubi.authentication.ldap.baseDNBase DN for LDAP searches.o=emr
    kyuubi.authentication.ldap.userDNPatternPattern used to convert a login username to a full DN. Use %s as a placeholder for the username. When user test logs in, this resolves to uid=test,ou=people,o=emr.uid=%s,ou=people,o=emr
    kyuubi.authentication.ldap.binddnDN used to bind to the LDAP service for lookups.uid=admin,o=emr
    kyuubi.authentication.ldap.bindpwPassword for the bind DN. For OpenLDAP on EMR on ECS, find the admin_pwd value in the OpenLDAP service configuration.—

    Step 3: Connect with LDAP credentials

    Before connecting, collect the following values from the Kyuubi Gateway management page:

    PlaceholderWhere to find itNotes
    <endpoint>Overview tab — Endpoint (public) or Endpoint (internal)The internal endpoint only works within the same VPC
    <port>—443 for public endpoint; 80 for internal endpoint
    <token>Token Management tab—
    <username> and <password>Your LDAP service credentialsFor OpenLDAP on EMR on ECS: credentials from the User Management page

    Option 1: kyuubi-beeline

    Inline credentials — include the username and password directly in the command:

    kyuubi-beeline -u 'jdbc:hive2://<endpoint>:<port>/;transportMode=http;httpPath=cliservice/token/<token>' \
  -n <username> -p <password>

    Interactive prompt — omit the password to enter it interactively (characters are not displayed):

    kyuubi-beeline -u 'jdbc:hive2://<endpoint>:<port>/;transportMode=http;httpPath=cliservice/token/<token>' \
  -n <username> -p

    Use the interactive prompt method to avoid exposing the password in shell history or logs.

    Option 2: JDBC URL

    For Java applications or any client that accepts a JDBC connection string:

    jdbc:hive2://<endpoint>:<port>/;transportMode=http;httpPath=cliservice/token/<token>;user=<username>;password=<password>

    Troubleshooting

    Connection fails immediately after configuration

    Check the following:

    1. Network: Confirm Kyuubi Gateway can reach the LDAP host and port. Run a connectivity test from within the same VPC if possible.

    2. LDAP URL format: Verify that the URL is in the correct format: ldap://<host>:<port>/.

    3. Bind DN and password: Verify that kyuubi.authentication.ldap.binddn and kyuubi.authentication.ldap.bindpw match a valid LDAP account.

    Authentication fails with correct credentials

    1. userDNPattern mismatch: The resolved DN must match the exact format used in your LDAP directory. For OpenLDAP, confirm the pattern against an actual user entry using an LDAP browser tool.

    2. baseDN scope: If the user entry is outside the configured baseDN, the lookup will not find the user. Adjust baseDN to a higher-level entry if needed.

    Token or endpoint errors

    If the connection URL is rejected, verify that:

    • The token has not expired or been revoked (Token Management tab).

    • The port matches the endpoint type: 443 for public, 80 for internal.

    What's next