.. _kafka_ldap_authorizer_config: Configuring the |ldap-auth| =========================== Configuration Overview ---------------------- The broker configuration (in the ``server.properties`` file) must set ``authorizer.class.name`` to ``io.confluent.kafka.security.ldap.authorizer.LdapAuthorizer`` to enable LDAP group-based authorization. .. sourcecode:: bash authorizer.class.name=io.confluent.kafka.security.ldap.authorizer.LdapAuthorizer ``authorizer.class.name`` Fully qualified class name of the |ak-tm| broker authorizer implementation class that implements the ``kafka.security.auth.Authorizer`` interface. * Type: class * Default: "" * Importance: low The following configuration options of ``SimpleAclAuthorizer`` are also processed by the |ldap-auth|. ``super.users`` Semicolon-separated list of principals of super users or super groups who are allowed access to all of the resources for all of the actions for all of the hosts. If a resource has no ACLs associated with it, then only super users can access the resource. For an example of how to set this, see :ref:`Configure Brokers`. * Type: string * Default: "" * Importance: medium ``allow.everyone.if.no.acl.found`` Boolean flag that indicates if everyone is allowed access to a resource if no ACL is found for the user principal or any of the groups that the user belongs to. * Type: boolean * Default: false * Importance: medium .. note:: To enable the |ldap-auth| to obtain the user principal to group mappings from your LDAP server, configure these options to match the settings on your LDAP server. In 5.3.0 and later, when using the |ldap-auth|, you can use either the ``ldap.`` or ``ldap.authorizer.`` prefix (``ldap.authorizer.`` is supported for backward compatibility). Configuring LDAP Context ^^^^^^^^^^^^^^^^^^^^^^^^ All standard Java LDAP configurations are supported. Broker configurations starting with ``ldap.java.naming`` and ``ldap.com.sun.jndi`` are stripped of their ``ldap.`` prefix and these standard Java LDAP configurations are used to make connections to the LDAP server. You can also use the prefix ``ldap.authorizer.``. You must configure ``ldap.java.naming.provider.url`` with the URL of your LDAP server. For example: .. sourcecode:: bash ldap.java.naming.provider.url=ldap://somehost:389 For a complete list of standard Java configurations for the LDAP naming service provider and Java Naming and Directory Interface (JNDI), see `LDAP Naming Service Provider for the Java Naming and Directory Interface (JNDI) `_. Configuring SSL for LDAP ^^^^^^^^^^^^^^^^^^^^^^^^ Enable SSL for the connections from the |ldap-auth| to your LDAP server by setting ``ldap.java.naming.security.protocol=SSL``. LDAP provider URL must use the protocol ``ldaps`` if SSL is enabled. All the SSL configuration options of |ak| clients are supported and must be prefixed with ``ldap.`` or ``ldap.authorizer.``. For example: .. sourcecode:: bash # Configure provider URL with `ldaps` as protocol ldap.java.naming.provider.url=ldaps://somehost:389 # Enable SSL for connections to LDAP server ldap.java.naming.security.protocol=SSL # Path of truststore for connections to LDAP ldap.ssl.truststore.location=/path/to/truststore.jks # Password of LDAP truststore ldap.ssl.truststore.password=truststore-secret For a list of supported SSL configurations, see :ref:`Encryption and Authentication with SSL`. .. note:: In Java 8 update 181 and later, host name verification is enabled by default on LDAPS connections. You can disable this verification by setting ``KAFKA_OPTS=-Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true``, but you should avoid using this option in production systems. Prior to Java 8 update 181, host name verification was disabled by default for LDAPS connections. For improved security, consider upgrading to Java 8 181 or later. Configuring GSSAPI for LDAP ^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can use GSSAPI to authenticate the |ldap-auth| with your LDAP server if Kerberos is enabled on your LDAP server. The JAAS configuration for GSSAPI may be configured using the config option ``ldap.sasl.jaas.config``. Authentication protocol and security principal must also be configured using standard Java LDAP configs prefixed with ``ldap.`` or ``ldap.authorizer.``. For example: .. sourcecode:: bash # Configure SASL/GSSAPI as the authentication protocol for LDAP context. ldap.java.naming.security.authentication=GSSAPI # Security principal for LDAP context ldap.java.naming.security.principal=ldap@EXAMPLE.COM # JAAS configuration for Kerberos authentication with LDAP server ldap.sasl.jaas.config=com.sun.security.auth.module.Krb5LoginModule required \ keyTab="/tmp/keytabs/ldap.keytab" \ principal="ldap@EXAMPLE.COM" \ storeKey="true" \ useKeyTab="true"; If ``ldap.sasl.jaas.config`` is not configured, the default JAAS configuration of the broker will be used. The default JAAS configuration (e.g configured using the system property ``java.security.auth.login.config``) is loaded from the login context ``KafkaServer`` that is used as broker's login context using a single shared login. This should be used for LDAP only if the principal in this context can be used to search LDAP. Configuring Password Credentials for LDAP ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If password authentication is enabled on your LDAP server, then you can configure the user principal and password so that brokers can authenticate with the LDAP server using simple authentication. Use standard Java configurations prefixed with ``ldap.`` or ``ldap.authorizer.`` to configure LDAP credentials for the broker. For example: .. sourcecode:: bash # Configure simple LDAP binding for authentication ldap.java.naming.security.authentication=SIMPLE # Security principal is the distinguished name of the LDAP user that performs LDAP search ldap.java.naming.security.principal=CN=Kafka Broker,OU=Users,DC=EXAMPLE,DC=COM # Security credential is the password of the user that performs LDAP search ldap.java.naming.security.credentials=broker-secret Configuring LDAP Search ^^^^^^^^^^^^^^^^^^^^^^^ To perform group-based authorization, brokers require a mapping of the user principal. This mapping is determined during authentication to group principals that define access rules. You can configure broker search parameters so that your LDAP server derives group principals for every user that connects to |cp|. The mapping can be derived from either user entries or group entries in LDAP by configuring the search mode to use either ``USERS`` or ``GROUPS``. You must configure the search mode based on which entry contains both user and group principals in the format used for authentication and authorization. You can configure the LDAP attributes containing user and group principals in your LDAP server entries, and regular expression patterns to extract the principal from these attributes. .. _group-based-search-config: Sample Configuration for Group-Based Search """"""""""""""""""""""""""""""""""""""""""" By default, brokers read group entries from LDAP using group-based mode. If the LDAP group entries in your LDAP server contain the user principal of members in the format used to authenticate the principal by Kafka brokers, then you can use the default group search. For example, consider an LDAP server with a group entry that contains the following attributes: .. sourcecode:: bash dn: CN=Kafka Developers,OU=Groups,DC=EXAMPLE,DC=COM cn: kafkadev objectClass: groupOfNames member: UID=alice,OU=Users,DC=EXAMPLE,DC=COM member: UID=bob,OU=Users,DC=EXAMPLE,DC=COM If the user principals used by Kafka are ``User:alice`` and ``User:bob``, then you can configure the group-based search to map ``User:alice`` and ``User:bob`` to the group principal ``Group:kafkadev`` using the following configuration: .. sourcecode:: bash ldap.search.mode=GROUPS ldap.group.search.base=DC=EXAMPLE,DC=COM ldap.group.object.class=groupOfNames ldap.group.name.attribute=cn ldap.group.member.attribute=member ldap.group.member.attribute.pattern=UID=(.*),OU=Users,DC=EXAMPLE,DC=COM In some environments, the distinguished name (DN) of the user in the member entry may not contain the principal generated by Kafka brokers during authentication. In these cases, you can configure user-based search as described in :ref:`Sample Configuration for User-Based Search`. .. _user-based-search-config: Sample Configuration for User-Based Search """""""""""""""""""""""""""""""""""""""""" The user principal used for authorization by brokers is the principal generated during authentication. For example, with Kerberos authentication using GSSAPI, the default principal is the short name from the Kerberos principal. In some LDAP environments, this principal may not appear in the ``member`` attribute of group entries. In such cases, you can search in user mode to extract the principal and group principals from LDAP user entries. This search mode provides the flexibility required for most LDAP environments because group principals are easily adapted to the format used in the user entry of your LDAP server. For example, consider an LDAP server with a user entry containing the following attributes: .. sourcecode:: bash objectClass: user distinguishedName: CN=Joe Bloggs,CN=Users,DC=EXAMPLE,DC=COM sAMAccountName: joe memberOf: CN=Kafka Developers,CN=Users,DC=EXAMPLE,DC=COM If the user principal used by Kafka is ``User:joe`` , then you can configure group-based search to map ``User:joe`` to the group ``Group:Kafka Developers`` using the following configuration: .. sourcecode:: bash ldap.search.mode=USERS ldap.user.search.base=DC=EXAMPLE,DC=COM ldap.user.object.class=user ldap.user.name.attribute=sAMAccountName ldap.user.memberof..attribute=memberOf ldap.user.memberof.attribute.pattern=CN=(.*),CN=Users,.* For LDAP servers with a large number of users where only a small subset access |ak|, you can configure filters to limit the size of search results as described in :ref:`Configuring LDAP Filters to Limit Search Results`. .. _ldap-filters-to-limit-search: Configuring LDAP Filters to Limit Search Results ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you have a large number of users in the LDAP server, it is likely that only a subset require access to |cp|. In such instances, you can configure filters to reduce the size of search results because brokers only require group mapping for the small subset of users who connect to the |cp|. LDAP filters are particularly useful for user mode searches where you wish to avoid having brokers process every user defined in the LDAP server. You can configure a simple filter by adding all users accessing |cp| to a group. For example, the following configuration filters out users belonging to the |ak| group: .. sourcecode:: bash ldap.user.search.filter=(memberOf=CN=Kafka,CN=Users,DC=EXAMPLE,DC=COM) You can also configure a simple filter that processes users belonging to a set of groups when the users of the |cp| already belong to a small set of groups. For example, the following filter processes users belonging to the groups ``Administrators`` and ``Kafka Developers``: .. sourcecode:: bash ldap.user.search.filter=(|(memberOf=CN=Administrators,CN=Users,DC=EXAMPLE,DC=COM)(memberOf=CN=Kafka Developers,CN=Users,DC=example,DC=com)) If your LDAP server already has other attributes that match users or groups connecting to |cp|, you can filter based on those. You can use any valid LDAP search filter to limit search results in both user and group search modes. Using Persistent LDAP Search ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, the mapping of users to groups obtained from LDAP is refreshed periodically with a refresh interval that you can configure using ``ldap.refresh.interval.ms``. If your LDAP server supports persistent search, you can set the refresh interval to zero to initiate a persistent LDAP search in the |ldap-auth|. LDAP updates are processed as soon as notifications are received, enabling any changes to be used for authorization immediately. Note that persistent search requires a connection to be kept open between each broker and the LDAP server and may add load to your LDAP server. .. sourcecode:: bash ldap.refresh.interval.ms=0 |ldap-auth| Configuration Options --------------------------------- Confluent License ^^^^^^^^^^^^^^^^^ ``ldap.authorizer.license`` Confluent issues a license key to each subscriber. The license key is a short snippet of text that you can copy and paste. Without the license key, you can use Confluent security plugins for a 30-day trial period. If you are a subscriber and don't have a license key, contact Confluent Support at support@confluent.io. * Type: string * Default: "" * Importance: high LDAP Search Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^ ``ldap.refresh.interval.ms`` (``ldap.authorizer.refresh.interval.ms``) LDAP group cache refresh interval in milliseconds. If set to zero, then persistent LDAP search is used. * Type: int * Default: 60000 * Importance: medium ``ldap.search.page.size`` (``ldap.authorizer.search.page.size``) Page size for LDAP search if persistent search is disabled (in other words, when the refresh interval is greater than zero). Paging is disabled by default. * Type: int * Default: 0 * Importance: medium ``ldap.search.mode`` (``ldap.authorizer.search.mode``) LDAP search mode that indicates if the user-to-group mapping is retrieved by searching for group or user entries. Valid values are USERS and GROUPS. * Type: string * Default: GROUPS * Valid Values: [GROUPS, USERS] * Importance: medium LDAP search by groups ^^^^^^^^^^^^^^^^^^^^^ ``ldap.group.search.base`` (``ldap.authorizer.group.search.base``) LDAP search base for group-based search. * Type: string * Default: ou=groups * Importance: high ``ldap.group.search.filter`` (``ldap.authorizer.group.search.filter``) LDAP search filter for group-based search. * Type: string * Default: "" * Importance: medium ``ldap.group.search.scope`` (``ldap.authorizer.group.search.scope``) LDAP search scope for group-based search. Valid values are 0 (OBJECT), 1 (ONELEVEL) and 2 (SUBTREE). * Type: int * Default: 1 * Importance: medium ``ldap.group.object.class`` (``ldap.authorizer.group.object.class``) LDAP object class for groups. * Type: string * Default: groupOfNames * Importance: medium ``ldap.group.name.attribute`` (``ldap.authorizer.group.name.attribute``) Name of attribute that contains the name of the group in a group entry obtained using an LDAP search. A regex pattern may be specified to extract the group name used in ACLs from this attribute by configuring ``ldap.group.name.attribute.pattern``. * Type: string * Default: cn * Importance: high ``ldap.group.name.attribute.pattern`` (``ldap.authorizer.group.name.attribute.pattern``) A Java regular expression pattern that extracts the group name used in ACLs from the name of the group obtained from the LDAP attribute specified using ``ldap.group.name.attribute``. By default the full value of the attribute is used. * Type: string * Default: "" * Importance: low ``ldap.group.member.attribute`` (``ldap.authorizer.group.member.attribute``) The name of the attribute that contains the members of the group in a group entry obtained using an LDAP search. A regex pattern may be specified to extract the user principals from this attribute by configuring ``ldap.group.member.attribute.pattern``. * Type: string * Default: member * Importance: high ``ldap.group.member.attribute.pattern`` (``ldap.authorizer.group.member.attribute.pattern``) A Java regular expression pattern that extracts the user principals of group members from group member entries obtained from the LDAP attribute specified using ``ldap.group.member.attribute``. By default the full value of the attribute is used. * Type: string * Default: "" * Importance: medium ``ldap.group.dn.name.pattern`` (``ldap.authorizer.group.dn.name.pattern``) A Java regular expression pattern that extracts the group name from the distinguished name (DN) of the group when a group is renamed. This is used only when persistent search is enabled. By default the ``ldap.group.name.attribute`` is extracted from the DN. * Type: string * Default: "" * Importance: low ``ldap.user.dn.name.pattern`` (``ldap.authorizer.user.dn.name.pattern``) A Java regular expression pattern used to extract user name from the distinguished name (DN) of the user when user is renamed. This is used only when persistent search is enabled. By default ``ldap.user.name.attribute`` is extracted from the DN. * Type: string * Default: "" * Importance: low LDAP search by users ^^^^^^^^^^^^^^^^^^^^ ``ldap.user.search.base`` (``ldap.authorizer.user.search.base``) The LDAP search base for a user-based search. * Type: string * Default: ou=users * Importance: medium ``ldap.user.search.filter`` (``ldap.authorizer.user.search.filter``) The LDAP search filter for a user-based search. * Type: string * Default: "" * Importance: medium ``ldap.user.search.scope`` (``ldap.authorizer.user.search.scope``) The LDAP search scope for a user-based search. Valid values are 0 (OBJECT), 1 (ONELEVEL), and 2 (SUBTREE). * Type: int * Default: 1 * Importance: medium ``ldap.user.object.class`` (``ldap.authorizer.user.object.class``) The LDAP object class for users. * Type: string * Default: person * Importance: medium ``ldap.user.name.attribute`` (``ldap.authorizer.user.name.attribute``) Name of attribute that contains the user principal in a user entry obtained using an LDAP search. A regex pattern may be specified to extract the user principal from this attribute by configuring ``ldap.user.name.attribute.pattern``. * Type: string * Default: uid * Importance: medium ``ldap.user.name.attribute.pattern`` (``ldap.authorizer.user.name.attribute.pattern``) A Java regular expression pattern used to extract the user principal from the name of the user obtained from the LDAP attribute specified using ``ldap.user.name.attribute``. By default the full value of the attribute is used. * Type: string * Default: "" * Importance: medium ``ldap.user.memberof.attribute`` (``ldap.authorizer.user.memberof.attribute``) The name of the attribute that contains the groups in a user entry obtained using an LDAP search. A regex pattern may be specified to extract the group names used in ACLs from this attribute by configuring ``ldap.user.memberof.attribute.pattern``. * Type: string * Default: memberof * Importance: medium ``ldap.user.memberof.attribute.pattern`` (``ldap.authorizer.user.memberof.attribute.pattern``) A Java regular expression pattern used to extract the names of groups from user entries obtained from the LDAP attribute specified using ``ldap.user.memberof.attribute``. By default the full value of the attribute is used. * Type: string * Default: "" * Importance: medium Error Handling Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``ldap.retry.backoff.ms`` (``ldap.authorizer.retry.backoff.ms``) Initial retry backoff in milliseconds. Exponential backoff is used if ``ldap.retry.backoff.max.ms`` is set to a higher value. * Type: int * Default: 100 * Importance: medium ``ldap.retry.backoff.max.ms`` (``ldap.authorizer.retry.backoff.max.ms``) Maximum retry backoff in milliseconds. Exponential backoff is used if ``ldap.retry.backoff.ms`` is set to a lower value. * Type: int * Default: 1000 * Importance: medium ``ldap.retry.timeout.ms`` (``ldap.authorizer.retry.timeout.ms``) Timeout for LDAP search retries after which the |ldap-auth| is marked as failed. All requests are denied access if a successful cache refresh cannot be performed within this time. * Type: long * Default: 3600000 * Importance: medium SSL Configuration for LDAP connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``ldap.ssl.protocol`` (``ldap.authorizer.ssl.protocol``) The SSL protocol used to generate the SSLContext. The default setting is TLS, which is fine for most cases. Allowed values in recent JVMs are TLS, TLSv1.1, and TLSv1.2. SSL, SSLv2, and SSLv3 may be supported in older JVMs, but their usage is discouraged due to known security vulnerabilities. * Type: string * Default: TLS * Importance: medium ``ldap.ssl.provider`` (``ldap.authorizer.ssl.provider``) The name of the security provider used for SSL connections. The default value is the default security provider of the JVM. * Type: string * Default: null * Importance: medium ``ldap.ssl.enabled.protocols`` (``ldap.authorizer.ssl.enabled.protocols``) The list of protocols enabled for SSL connections. * Type: list * Default: TLSv1.2,TLSv1.1,TLSv1 * Importance: medium ``ldap.ssl.keystore.type`` (``ldap.authorizer.ssl.keystore.type``) The file format of the key store file. This attribute is optional for the client. * Type: string * Default: JKS * Importance: medium ``ldap.ssl.truststore.type`` (``ldap.authorizer.ssl.truststore.type``) The file format of the trust store file. * Type: string * Default: JKS * Importance: medium ``ldap.ssl.key.password`` (``ldap.authorizer.ssl.key.password``) The password of the private key in the key store file. This attribute is optional for client. * Type: password * Default: null * Importance: high ``ldap.ssl.keystore.location`` (``ldap.authorizer.ssl.keystore.location``) The location of the key store file. This attribute is optional for the client and can be used for two-way authentication for client. * Type: string * Default: null * Importance: high ``ldap.ssl.keystore.password`` (``ldap.authorizer.ssl.keystore.password``) The store password for the key store file. This attribute is optional for the client and is only needed if ``ssl.keystore.location`` is configured. * Type: password * Default: null * Importance: high ``ldap.ssl.truststore.location`` (``ldap.authorizer.ssl.truststore.location``) The location of the trust store file. * Type: string * Default: null * Importance: high ``ldap.ssl.truststore.password`` (``ldap.authorizer.ssl.truststore.password``) The password for the trust store file. If a password is not set, then access to the truststore is still available, but integrity checking is disabled. * Type: password * Default: null * Importance: high ``ldap.ssl.cipher.suites`` (``ldap.authorizer.ssl.cipher.suites``) A list of cipher suites. This is a named combination of authentication, encryption, MAC and key exchange algorithm used to negotiate the security settings for a network connection using TLS or SSL network protocol. By default all the available cipher suites are supported. * Type: list * Default: null * Importance: low ``ldap.ssl.keymanager.algorithm`` (``ldap.authorizer.ssl.keymanager.algorithm``) The algorithm used by the key manager factory for SSL connections. The default value is the key manager factory algorithm configured for the Java Virtual Machine. * Type: string * Default: SunX509 * Importance: low ``ldap.ssl.secure.random.implementation`` (``ldap.authorizer.ssl.secure.random.implementation``) The SecureRandom PRNG implementation to use for SSL cryptography operations. * Type: string * Default: null * Importance: low ``ldap.ssl.trustmanager.algorithm`` (``ldap.authorizer.ssl.trustmanager.algorithm``) The algorithm used by trust manager factory for SSL connections. The default value is the trust manager factory algorithm configured for the Java Virtual Machine. * Type: string * Default: PKIX * Importance: low SASL Configuration for LDAP connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``ldap.sasl.jaas.config`` (``ldap.authorizer.sasl.jaas.config``) JAAS login context parameters for SASL connections in the format used by JAAS configuration files. JAAS configuration file format is described in the `JAAS Login Configuration File documentation `_. The format for the value is: ``loginModuleClass controlFlag (optionName=optionValue)*;``. * Type: password * Default: null * Importance: medium ``ldap.sasl.login.callback.handler.class`` (``ldap.authorizer.sasl.login.callback.handler.class``) The fully qualified name of a SASL login callback handler class that implements the AuthenticateCallbackHandler interface. * Type: class * Default: null * Importance: medium ``ldap.sasl.login.class`` (``ldap.authorizer.sasl.login.class``) The fully qualified name of a class that implements the Login interface. * Type: class * Default: null * Importance: medium ``ldap.sasl.kerberos.kinit.cmd`` (``ldap.authorizer.sasl.kerberos.kinit.cmd``) The Kerberos kinit command path. * Type: string * Default: /usr/bin/kinit * Importance: low ``ldap.sasl.kerberos.min.time.before.relogin`` (``ldap.authorizer.sasl.kerberos.min.time.before.relogin``) The login thread sleep time between refresh attempts. * Type: long * Default: 60000 * Importance: low ``ldap.sasl.kerberos.ticket.renew.jitter`` (``ldap.authorizer.sasl.kerberos.ticket.renew.jitter``) Percentage of random jitter added to the renewal time. * Type: double * Default: 0.05 * Importance: low ``ldap.sasl.kerberos.ticket.renew.window.factor`` (``ldap.authorizer.sasl.kerberos.ticket.renew.window.factor``) The duration that the login thread will sleep until the specified window factor of time from last refresh to ticket's expiry has been reached, at which time it will try to renew the ticket. * Type: double * Default: 0.8 * Importance: low