Configuring |c3-short| with LDAP authentication
===================================================

|c3| provides HTTP Basic Authentication via
`JAAS <https://docs.oracle.com/javase/8/docs/technotes/guides/security/jaas/JAASRefGuide.html>`__.

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 LDAP implementation.

Configure |c3-short|
--------------------

#.  Create a JAAS configure file with the following content and save as ``control-center-jaas.conf``.

    ::

        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";
        };

#.  Add these configuration options to the |c3-short| configuration file (``control-center.properties``).

    ::

        # 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


Note that |c3-short| allows restricted access, no editing or creating is allowed via the UI. For more information about
|c3-short| configuration, see :ref:`controlcenter_configuration`.

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: ``/path/to`` should be replaced with actual values.

::

    CONTROL_CENTER_OPTS="-Djava.security.auth.login.config=/path/to/propertyfile.jaas" \
    control-center-start /path/to/control-center.properties``

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``.

providerUrl
    Specify the LDAP URL for the server, for example,  ``ldap://server:389, ldaps://server:636``.

bindDn
    Optional. If not using “binding” authentication, set this to
    the root DN that should bind, for example,  ``cn=administrator,dc=confluent,dc=io``.

bindPassword
    Specify the password for bind DN. Note: The bindDn and
    bindPassword must escape any special characters with  character. Special
    characters include backslash (``\``) and the exclamation point (``!``).

authenticationMethod
    Specify the `authentication
    method <http://docs.oracle.com/cd/E19253-01/816-4556/ldapsecure-75/index.html>`__,
    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).

forceBindingLoginUseRootContextForRoles
    Indicate whether role membership searches will be
    performed in the root context. If set to true and
    forceBindingLogin is true, then role membership searches will be
    performed in the root context, rather than in the bound user context.

userBaseDn
    Specify the base DN to search for users, example:
    ``ou=People,dc=cops,dc=confluent,dc=io``.

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``.

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\_``.

cacheDurationMillis
    Specify the duration that authorization should be cached,
    in milliseconds. The default value is ``0``. A value of ``0`` indicates no caching should
    be used.

reportStatistics
    Indicate whether to send output cache statistics to the log.