Viewpoint is equipped with pluggable security that easily handles integration with LDAP/Active Directory. Configuration for setting up LDAP authentication and authorization requires adding a login module entry into the login modules section in the core.xml file.

There are two factors you should take into consideration when setting up security via LDAP. First, you must have the required information about your LDAP server (in the following examples Active Directory will be used), and you must use that information to populate the necessary fields on your LDAP server.

When you select LDAP at the Security screen during Viewpoint installation, the core.xml file is automatically generated to include the login module, the permissions map, and a default, functional LDAP configuration; however, if you selected a different security method, you can manually configure Viewpoint to use LDAP/Active directory by completing the following steps:

1. Open the core.xml file and specify the fully qualified class name in the <login-module> element (class attribute).
2. Define the necessary options within the <login-module> element. Refer to the Login Module Example for more information.
3. Add the appropriate callback parameters to the <request-handler> element. See the Request Handler Example for more information.
4. Include the required principal type (LdapGroupPrincipal) in the <permissions-map> element. See the Permissions Map Example for more information.
5. Complete the group and role permissions mapping configuration according to your own specific requirements. See Configuring the Authentication Module for more information; specifically note descriptions for the <permissions-map> and <role-definition> elements.

2.3.1 Class Name

The class name to be specified in the <login-module> element is com.cri.security.server.modules.LdapLoginModule.

Options for Defining LdapLoginModule

The following are options for defining the LdapLoginModule:

• initialContextFactory - The fully-qualified name of the initial context factory that will be used. Most likely this is com.sun.jndi.ldap.LdapCtxFactory.
• connectionURL - The connection URL for the LDAP server. Note that the default LDAP port is 389. For example: ldap://localhost:389
• connectionUsername - The distinguished name used by the login module for authentication on the LDAP server. In many cases this will be the administrator, or some other account created specifically for this purpose.
• connectionPassword - The credential (password) of the user set in connectionUsername that is used for the login module to authenticate on the LDAP server.
• authentication - The security level to be used. The value must be none, simple, or strong. If not set, the value is determined by the LDAP server.
• userBase - The distinguished name for the user search.
• userSearchMatching - The criteria in the search for the user object; for example: (cn=Joe User). Additionally, you can pass a parameter instead of the literal value to the search filter. If you want to parameterize the value of the attribute type (as when inserting the username that the user entered), specify (cn = {0}) for the case where you want to insert the username.
• roleBase - The base distinguished name for the search for the groups of which the user is a member.
• roleName - The LDAP attribute type that identifies the group name attribute in the object returned from the group membership query. Note that group membership query is defined by the roleSearchMatching parameter. Often, the group name parameter is cn.
• roleSearchMatching - The criteria to be used to search for the role object. In addition you can pass a parameter instead of the literal value to the search filter; for example: (uniqueMember = {0}). This integer refers to the parameter number. This parameter is the DN of the authenticated user. Note that if role membership for the user is defined in the member-of-like attribute (see userRoleName option) you might not need to search for group membership with the query.
• userRoleName - LDAP attribute type for the user group membership. Different LDAP schemas represent user group membership in different ways. Examples are memberOf, isMemberOf, member, and so forth. For example, if you have: memberOf: cn=admin,ou=groups,dc=foo, specify memberOf as the value for the userRoleName option.
• connectionProtocol - The security protocol to be used. This value can be determined by the LDAP server. An example would be SSL.
• userSearchSubtree - This defines the directory search scope for the user. If set to true, directory search scope is SUBTREE, if set to false, directory search scope is ONE-LEVEL.
• roleSearchSubtree - This defines the directory search scope for the role. If set to true, directory search scope is SUBTREE, if set to false, directory search scope is ONE-LEVEL.

For all searches (userSearchMatching and roleSearchMatching), RFC 2254 filters are allowed.

2.3.2 Login Module Example

The following is an example LdapLoginModule entry for Active Directory in the core.xml file used to get the groups to which a user belongs. By use of groups in this fashion, you can control which permissions a user has (see following examples). In this case, 'admin' is the user that performs the initial connection to the server, and admin password is provided for that purpose. This is a means of granting permissions to Viewpoint users based on what groups they are members of.

<login-module class="com.cri.security.server.modules.LdapLoginModule" flag="required" >
    <option name="initialContextFactory">com.sun.jndi.ldap.LdapCtxFactory</option>
    <option name="connectionURL">ldap://192.168.3.158:389</option>
    <option name="connectionUsername">cn=admin,cn=Users,dc=sge,dc=local</option>
    <option name="connectionPassword">admin_password</option>
    <option name="authentication">simple</option>
    <option name="userBase">cn=Users,dc=sge,dc=local</option>
    <option name="roleBase">cn=Users,dc=sge,dc=local</option>
    <option name="userSearchMatching">(&amp;amp;(sAMAccountName={0})(objectcategory=user))</option>
    <option name="roleName">cn</option>
    <option name="roleSearchMatching">(member={0})</option>
</login-module>

2.3.3 Request Handler Example

When the LdapLoginModule is used, the following <request-handler> parameters must be set as well:

<request-handler>
    <parameter callback="ProxyUserCallback">username</parameter>
    <parameter callback="NameCallback">username</parameter>
    <parameter callback="PasswordCallback">password</parameter>
</request-handler>

2.3.4 Permissions Map Example

To take advantage of the LdapLoginModule to manage authorizations/permissions, the following must be added to the core.xml file under the <permissions-map> element. The name of the LdapGroupPrincipal is the container where the users are stored on the LDAP server. Note also that the <role name="user"> element maps directly to the <definition name="user"> element that follows in the Role Definitions section.

<permissions-map>
    <principal type="LdapGroupPrincipal" name="groupA">
        <role name="user" />
    </principal>
    <principal type="LdapGroupPrincipal" name="groupB">
        <role name="admin" /> 
    </principal>
</permissions-map>

2.3.5 Role Definitions

The element <role name="test" /> maps to a given role definition in the <role-definitions> element:

<role-definitions>
    <definition name="test">
	<permission name="random.permission" />
	<permission name="different.permission" />
    </definition>
</role-definitions>