.. _controlcenter_security_ldap: Configuring |c3-short| with LDAP authentication =============================================== |c3-short| provides HTTP Basic Authentication through `JAAS `__. The following tutorial describes the steps necessary to enable HTTP Basic Authentication backed by LDAP. This includes but is not limited to the Active Directory (AD) LDAP implementation. .. _c3_LDAP_escape_chars: Escaping special characters --------------------------- .. important:: `Escape `_ any restricted LDAP characters. For best results, avoid characters that require escaping. Follow `Best Practices for LDAP Naming Attributes `_. +------------+--------------+ | Character | Description | +============+==============+ | ``,`` | Comma [1]_ | +------------+--------------+ | ``\`` | Backslash | +------------+--------------+ | ``#`` | Pound (hash) | +------------+--------------+ | ``+`` | Plus sign | +------------+--------------+ | ``=`` | Equals sign | +------------+--------------+ | ``<`` | Less than | +------------+--------------+ | ``>`` | Greater than | +------------+--------------+ | ``;`` | Semi-colon | +------------+--------------+ | ``''`` | Double quote | +------------+--------------+ | | Spaces [2]_ | +------------+--------------+ .. [1] Requires escaping with a double backslash or ``\5c``. See `RFC 2254 `_. .. [2] Leading or trailing spaces must be escaped. Embedded spaces are not escaped. .. _config_c3_JAAS: Configure |c3-short| JAAS ------------------------- #. Create a JAAS configuration file with the following content and save as ``control-center-jaas.conf``. .. note:: Do not enter any commented lines within the JAAS configuration file. The ``#`` character is not allowed. Comments in the JAAS file interfere with parsing the configuration parameters when running |c3-short|. :: c3 { org.eclipse.jetty.jaas.spi.LdapLoginModule required useLdaps="false" contextFactory="com.sun.jndi.ldap.LdapCtxFactory" hostname="ad.confluent.io" port="389" bindDn="cn=admin,dc=confluent,dc=io" bindPassword="password" authenticationMethod="simple" forceBindingLogin="true" userBaseDn="ou=People,dc=confluent,dc=io" userRdnAttribute="sAMAccountName" userIdAttribute="sAMAccountName" userPasswordAttribute="userPassword" userObjectClass="user" roleBaseDn="ou=Groups,DC=confluent,DC=org" roleNameAttribute="cn" roleMemberAttribute="member" roleObjectClass="group"; }; .. important:: If the ``bindDn``, ``userBaseDn``, or ``roleBaseDn`` contains special characters, escape them with a backslash. The comma character is designated by the LDAP filter specification as a reserved separator character for ``CN`` and ``OU``. Any ``CN`` or ``OU`` that contains a comma ``,`` character needs to be escaped with a double backslash in the LDAP JAAS configuration file. For example, ``"CN=adminstrator, firstclass,`` is escaped as follows: ``"CN=administrator\\, firstclass,OU=users,DC=confluent,DC=io"``. For further discussion about LDAP filtering and escaping, refer to this `Stack Overflow article `_. #. Add these configuration options to the |c3-short| configuration file (``control-center.properties``). .. code-block:: RST :linenos: :emphasize-lines: 5,6 # The name of the configuration block in the JAAS configuration confluent.controlcenter.rest.authentication.realm=c3 # HTTP authentication type confluent.controlcenter.rest.authentication.method=BASIC # To enabled restricted access, add this line confluent.controlcenter.auth.restricted.roles=RestrictedGroupName # Add roles defined in the JAAS config file here confluent.controlcenter.rest.authentication.roles=c3users,RestrictedGroupName Be aware that |c3-short| allows restricted access as shown above in lines 5 and 6; no editing or creating is allowed using the UI. For more information about |c3-short| configuration, see :ref:`controlcenter_configuration`. .. note:: Enabling restricted roles also prevents users from :ref:`inspecting topics ` and :ref:`running KSQL queries `. For more fine-grained access control, consider configuring :ref:`RBAC `. Start |c3-short| ---------------- You must pass a few system flags to the JVM at |c3-short| start up. To do so, export the ``CONTROL_CENTER_OPTS`` flag as shown below. .. note:: Replace ``/path/to`` with the actual filepath. :: CONTROL_CENTER_OPTS="-Djava.security.auth.login.config=/path/to/propertyfile.jaas" \ control-center-start /path/to/control-center.properties`` For more information about |c3-short| properties files, see :ref:`c3_properties_files`. Configure LdapLoginModule ------------------------- Configure the LdapLoginModule. debug Indicate whether to turn on debug output. contextFactory Specify the LDAP context factory class; for example, ``com.sun.jndi.ldap.LdapCtxFactory``. hostname Specify the hostname of the LDAP server. port Specify the port on which the LDAP server should listen. Default port is 389 for non-SSL LDAP and AD; 636 for SSL LDAP and AD. bindDn Optional. If not using binding authentication, set this to the root DN that should bind; for example, ``cn=administrator,dc=confluent,dc=io``. See :ref:`c3_LDAP_escape_chars`. bindPassword Specify the password for bindDn. See :ref:`c3_LDAP_escape_chars`. authenticationMethod Specify the `authentication method `__; for example ``simple``. forceBindingLogin Indicate whether to bind as the user that is authenticating (true), otherwise bind as the manager and perform a search to verify user password (false). userBaseDn Specify the base DN to search for users; for example: ``ou=People,dc=cops,dc=confluent,dc=io``. See :ref:`c3_LDAP_escape_chars`. userRdnAttribute Specify the attribute name for username, used when searching for user role membership by DN, default ``uid``. userIdAttribute Specify the attribute name to identify user by username. The default value is ``acn``. userPasswordAttribute Specify the attribute name for user password. The default value is ``userPassword``. userObjectClass Specify the attribute name for user object class. The default value is ``inetOrgPerson``. roleBaseDn Specify the base DN for role membership search; for example, ``ou=Groups,dc=cops,dc=confluent,dc=io``. See :ref:`c3_LDAP_escape_chars`. roleNameAttribute Specify the attribute name for role name. The default value is ``roleName``. roleMemberAttribute Specify the attribute name for a role that would contain a user’s DN. The default value is ``uniqueMember``. roleUsernameMemberAttribute Specify the attribute name for a role that would contain a user’s username. If set, this overrides the roleMemberAttribute behavior. roleObjectClass Specify the object class for role. The default value is ``groupOfUniqueNames``. rolePrefix Specify the prefix string to remove from role names before returning to the application, for example, ``confluent\_``.