.. _controlcenter_security_ldap: Configure |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) [2]_ | +------------+--------------------+ | ``+`` | Plus sign | +------------+--------------------+ | ``=`` | Equals sign | +------------+--------------------+ | ``<`` | Less than | +------------+--------------------+ | ``>`` | Greater than | +------------+--------------------+ | ``;`` | Semi-colon | +------------+--------------------+ | ``''`` | Double quote | +------------+--------------------+ | | Spaces [3]_ | +------------+--------------------+ .. [1] Requires escaping with a double backslash or ``\5c``. See `RFC 2254 `_. .. [2] You only need to escape pound (hash) ``#`` if it occurs at the beginning of a string. .. [3] 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 configuration 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:: * A user with membership in multiple groups is granted only the most restrictive permissions. For example, if a user is a member of two groups, ``admin`` and ``readonly``, and ``readonly`` is a restricted role, then the user is granted only the rights for the ``readonly`` group. * Enabling restricted roles also prevents users from :ref:`inspecting topics ` and :ref:`running ksqlDB queries `. * For fine-grained access control, consider configuring :ref:`role-based access control (RBAC) `. * Messages cannot be viewed if LDAP Basic Auth is implemented and the user is a member of a restricted group. If users need to view messages, consider using RBAC instead of LDAP Basic Auth. 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`` When a user accesses |c3-short|, they are shown a dialog similar to the one that follows, which prompts them for sign-in credentials. .. figure:: /images/c3-auth-sign-in.png :width: 200 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-TLS/SSL LDAP and AD; 636 for TLS/SSL LDAP and AD. bindDn Required. 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 Use ``authenticationMethod=simple``. This is the only LDAP authentication method currently supported by |c3-short|. 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). useLdaps Indicate whether to use Secure LDAP (LDAPS), required when TLS/SSL is enabled. Set to ``true`` to use LDAPS. The default value is ``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\_``.