Quick Links
Directory Configuration
    ScrumWorks Authentication
      Simple Configuration Alternate Configuration Directory Synchronization
        Removing Directory Configuration
          Documentation Home

          Directory Configuration

          ScrumWorks Pro supports LDAP-based protocols such as Active Directory and OpenLDAP. This allows you to use your existing centralized user management system to give people access to ScrumWorks Pro.

          This guide is intended to be used by your organization's directory administrator and assumes a working knowledge of directory configuration.

          ScrumWorks Authentication

          Enabling Directory-based authentication does not disable ScrumWorks' built in authentication scheme. It is still possible to have users that are allowed to access ScrumWorks but do not exist in the directory.

          Note that the ScrumWorks "administrator" user is a local-only user and can not be assigned to a directory user.

          Simple Configuration

          This configuration is the simplest to get working. It requires that your username be in the DN field and concatenates the principalDNPrefix and principalDNSuffix. The group the user must belong to is specified in the rolesCtxDN.

          Simple configuration does not work with Active Directory. Please use the alternate configuration if you would like to integrate with Active Directory.

          Default Configuration

          ScrumWorks Pro will search a particular group for users who should have access to ScrumWorks Pro. The DN used in the default configuration is:

          cn=ScrumWorks,ou=Group,dc=scrumworks,dc=dev

          The objectClass it belongs to is called groupOfNames. The main attribute of this class is member. Each member entry is the DN of a user in your directory. Only members of this group will be allowed to use ScrumWorks Pro.

          Users in the default configuration are part of the 'People' OU. An example DN for this user is:

          uid=swuser,ou=People,dc=scrumworks,dc=dev

          This user should be an inetOrgPerson with the userPassword and cn attributes.

          » top

          Customizing the Configuration

          To integrate your ScrumWorks Pro installation with your directory, you will need to edit the file

          <SW Installation Directory>/server/scrumworks/conf/login-config.xml

          There is a section of the XML that is commented out (see the example below). You will need to uncomment it and change the organization-specific parameters.

          module-option value
          java.naming.provider.url URL to the LDAP server. The format should be 'ldap://<servername>/'. LDAP over SSL (ldaps protocol) is also supported.
          java.naming.security.authentication Type of authentication to use. ScrumWorks Pro only supports 'simple' at this time.
          principalDNPrefix The first part of the user's DN. In the default configuration, it is 'uid='. The user's login name is appended to this string. For example: if the login name is swuser, the string will be 'uid=swuser'.
          bindDN When anonymous LDAP queries are not allowed, this is the user who can query the LDAP server. The full DN should be specified. If anonymous queries are allowed, this line should be removed.
          bindCredential When anonymous LDAP queries are not allowed, this is the password for the bindDN user listed above. If anonymous queries are allowed, this line should be removed.
          principalDNSuffix The last part of the user's DN (after the login name). This is appended to the login name. For example: if the login name is swuser, the string used for authentication will be: 'uid=swuser,ou=People,dc=scrumworks,dc=dev'.
          rolesCtxDN This is the group the user must be a member of to log into ScrumWorks Pro. The full DN to the group should be specified.
          uidAttributeID This is the attribute of the rolesCtxDN group that ScrumWorks Pro will query to find users.
          matchOnUserDN This is a boolean (true/false) field. If true, the uidAttributeID values are the full DNs of the users.
          roleAttributeId This field is the first part of the rolesCtxDN: in the example it is 'cn'.
          scrumWorksSyncInterval The time, in minutes, between LDAP synchronizations. The default is 10 minutes.
          allowEmptyPasswords On some directory servers, users are authenticated even if no password is supplied. This must be set to false for ScrumWorks to work properly. Users logging into the desktop client are correctly denied access with an empty password. All web client users are denied access until this flag is set to false.
          scrumWorksSyncEnabled This is used to turn on ScrumWorks synchronization with LDAP servers. This will be defaulted to true. ScrumWorks runs LDAP sync at configured 'scrumWorksSyncInterval' interval timings. When this is turned off, ScrumWorks will not run sync and will ignore 'scrumWorksSyncInterval' attribute. Synchronization can be done manually by invoking syncLdapUsers() API in ScrumWorksAPI. As a best practice,please set this flag as false, when syncLdapUsers() is invoked via API else results of LDAP sync will be unknown or erroneous.
          Once the values match those for your organization, you will need to restart your ScrumWorks Pro server.

          » top

          Sample Configuration

          This is a sample configuration that is known to work in with a typical Directory schema with anonymous LDAP queries enabled. 

                      <login-module code="org.jboss.security.auth.spi.LdapLoginModule" flag="required">
               <module-option name="password-stacking">useFirstPass</module-option>
               <module-option name="java.naming.factory.initial">
                  com.sun.jndi.ldap.LdapCtxFactory
               </module-option>
               <module-option name="java.naming.provider.url">
                  ldap://tom.o/
               </module-option>
               <module-option name="java.naming.security.authentication">
                  simple
               </module-option>
               <module-option name="principalDNPrefix">uid=</module-option>
               <module-option name="principalDNSuffix">,ou=People,dc=scrumworks,dc=dev</module-option>
               <module-option name="rolesCtxDN">cn=ScrumWorks,ou=Group,dc=scrumworks,dc=dev</module-option>
               <module-option name="uidAttributeID">member</module-option>
               <module-option name="matchOnUserDN">true</module-option>
               <!-- Change scrumWorksSyncInterval to the desired interval in minutes. -->
               <module-option name="scrumWorksSyncInterval">10</module-option>
               <module-option name="allowEmptyPasswords">false</module-option>
            </login-module>
            <login-module code="org.jboss.security.auth.spi.IdentityLoginModule" flag="required">
               <module-option name="password-stacking">useFirstPass</module-option>
               <module-option name="roles">Team Member</module-option>
               <module-option name="unauthenticatedIdentity">nobody</module-option>
            </login-module>

          » top

          LDIF Example

          This LDIF is the one used for the above sample configuration.

          User record: 

                         dn: uid=swuser,ou=TestPeople,dc=scrumworks,dc=dev
               objectClass: inetOrgPerson
               cn: Example User
               sn: User
               uid: swuser
               userPassword:: e1NIQX12RkdvUHVvSmhHM0FKQWZkQ1htV2lSS2lCNms9

          Group record: 

                         dn: cn=ScrumWorks,ou=Group,dc=scrumworks,dc=dev
               objectClass: groupOfNames
               objectClass: top
               cn: ScrumWorks
               member: uid=swuser,ou=TestPeople,dc=scrumworks,dc=dev
               description: Sample

          » top

          Alternate Configuration

          This configuration is a little more difficult to get working, but is more configurable than the 'Simple Configuration'. Users are looked up using the baseFilter and baseCtxDN. The DN found is then used to authenticate the user.

          This configuration works with Active Directory or directly with LDAP.

          Default Configuration

          ScrumWorks Pro will search a particular group for users who should have access. The DN used in the default configuration is:

          cn=ScrumWorks,ou=Group,o=Danube

          The objectClass it belongs to is called groupOfUniqueNames. The main attribute of this class is uniqueMember. Each uniqueMember entry is the DN of a user in your directory. Only members of this group will be allowed to use ScrumWorks Pro.

          Users in the default configuration are part of the 'People' OU. An example DN for this user is:

          employeeNumber=12345,ou=Ext,ou=People,o=Danube

          This user should be an inetOrgPerson with the userPassword and cn attributes.

          » top

          Customizing the Configuration

          To integrate your ScrumWorks Pro installation with your directory, you will need to edit the file

          <SW Installation Directory>/server/scrumworks/conf/login-config.xml

          There is a section of the XML that is commented out (see the example below). You will need to uncomment it and change the organization-specific parameters.

          module-option value
          java.naming.provider.url URL to the LDAP server. The format should be 'ldap://<servername>/'. LDAP over SSL (ldaps protocol) is also supported.
          java.naming.security.authentication Type of authentication to use. ScrumWorks Pro only supports 'simple' at this time.
          bindDN When anonymous LDAP queries are not allowed, this is the user who can query the LDAP server. The full DN should be specified. If anonymous queries are allowed, this line should be removed.
          bindCredential When anonymous LDAP queries are not allowed, this is the password for the bindDN user listed above. If anonymous queries are allowed, this line should be removed.
          baseCtxDN The fixed DN of the context to start the user search from.
          baseFilter A search filter used to locate the user to authenticate.
          rolesCtxDN The fixed DN of the context to search for user roles. Unlike the 'Simple Configuration' above, this is not the full DN of the group users belong to.
          roleFilter The filter that will be used to match users in the group. This should be either 'member' if the group's objectClass is 'groupOfNames' or it should be 'uniqueMember' if the group's objectClass is 'groupOfUniqueNames'.
          roleAttributeID The attribute containing the group's name.
          roleRecursion How deep the group search will go. This should be left as 0. Nested groups are not implemented.
          searchScope The scope that will be used when searching for groups. This should usually be left as OBJECT_SCOPE.
          scrumWorksGroup The name of the group ScrumWorks will search when looking for users who have access to ScrumWorks.
          scrumWorksSyncInterval The time, in minutes, between LDAP synchronizations. The default is 10 minutes.
          allowEmptyPasswords On some directory servers, users are authenticated even if no password is supplied. This must be set to false for ScrumWorks to work properly. Users logging into the desktop client are correctly denied access with an empty password. All web client users are denied access until this flag is set to false.

          You can read more about the options at the JBoss Wiki page. The defaults listed here are what have been implemented and tested.

          Once the values match those for your organization, you will need to restart your ScrumWorks Pro server.

          » top

          Sample Configuration
          This is a sample configuration that is known to work with the schema in the LDIF Example below. 
                      <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="required">
               <module-option name="password-stacking">useFirstPass</module-option>
               <module-option name="java.naming.factory.initial">
                  com.sun.jndi.ldap.LdapCtxFactory
               </module-option>
               <module-option name="java.naming.security.authentication">
                  simple
               </module-option>
               <module-option name="java.naming.provider.url">ldap://manticore:389</module-option>
               <module-option name="bindDN">cn=ScrumWorks,ou=SystemUsers,o=Danube</module-option>
               <module-option name="bindCredential">secret</module-option>
               <module-option name="baseCtxDN">ou=people,o=Danube</module-option>
               <module-option name="baseFilter">(uid={0})</module-option>
               <module-option name="rolesCtxDN">ou=Groups,o=Danube</module-option>
               <module-option name="roleFilter">(uniqueMember={1})</module-option>
               <module-option name="roleAttributeID">cn</module-option>
               <module-option name="roleRecursion">0</module-option>
               <module-option name="searchScope">OBJECT_SCOPE</module-option>
               <module-option name="scrumWorksGroup">ScrumWorks</module-option>
               <!-- Change scrumWorksSyncInterval to the desired interval in minutes. -->
               <module-option name="scrumWorksSyncInterval">10</module-option>
               <module-option name="allowEmptyPasswords">false</module-option>
            </login-module>
            <login-module code="org.jboss.security.auth.spi.IdentityLoginModule" flag="required">
               <module-option name="password-stacking">useFirstPass</module-option>
               <module-option name="roles">Team Member</module-option>
               <module-option name="unauthenticatedIdentity">nobody</module-option>
            </login-module>

          » top

          LDIF Example

          This LDIF is the one used for the above sample configuration.

          User record: 

                         dn: employeeNumber=12345,ou=Ext,ou=People,o=Danube
               objectClass: inetOrgPerson
               objectClass: organizationalPerson
               objectClass: person
               objectClass: posixAccount
               objectClass: top
               cn: TestUser1
               gidNumber: 1
               homeDirectory: /dev/null
               sn: User
               uid: testuser1
               uidNumber: 12345
               employeeNumber: 12345
               userPassword:: e1NIQX12RkdvUHVvSmhHM0FKQWZkQ1htV2lSS2lCNms9
          Group record: 
                         dn: cn=ScrumWorks,ou=Groups,o=Danube
               objectClass: groupOfUniqueNames
               objectClass: top
               cn: ScrumWorks
               uniqueMember: employeeNumber=12345,ou=Ext,ou=People,o=Danube

          » top

          Active Directory Example Configuration
          This example has been tested and is known to work with Windows Server 2003 and Windows Server 2008. 
                      <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="required">
               <module-option name="password-stacking">useFirstPass</module-option>
               <module-option name="java.naming.factory.initial">
                  com.sun.jndi.ldap.LdapCtxFactory
               </module-option>
               <module-option name="java.naming.security.authentication">
                  simple
               </module-option>
               <module-option name="java.naming.provider.url">ldap://dc-test:389</module-option>
               <module-option name="bindDN">CN=User Name,CN=Users,DC=swp-test,DC=danube,DC=com</module-option>
               <module-option name="bindCredential">password</module-option>
               <module-option name="baseCtxDN">DC=swp-test,DC=danube,DC=com</module-option>
               <module-option name="baseFilter">(sAMAccountName={0})</module-option>
               <module-option name="rolesCtxDN">OU=Group,DC=swp-test,DC=danube,DC=com</module-option>
               <module-option name="roleFilter">(member={1})</module-option>
               <module-option name="roleAttributeID">CN</module-option>
               <module-option name="roleRecursion">0</module-option>
               <module-option name="searchScope">OBJECT_SCOPE</module-option>
               <module-option name="scrumWorksGroup">ScrumWorks</module-option>
               <!-- Change scrumWorksSyncInterval to the desired interval in minutes. -->
               <module-option name="scrumWorksSyncInterval">10</module-option>
               <module-option name="allowEmptyPasswords">false</module-option>
            </login-module>
            <login-module code="org.jboss.security.auth.spi.IdentityLoginModule" flag="required">
               <module-option name="password-stacking">useFirstPass</module-option>
               <module-option name="roles">Team Member</module-option>
               <module-option name="unauthenticatedIdentity">nobody</module-option>
            </login-module>

          » top

          Directory Synchronization

          ScrumWorks Pro synchronizes with your Directory server at a configurable interval. Even though users will be added to ScrumWorks Pro, you will still need to log in to the ScrumWorks Pro Desktop Client to give them access to Products and assign the appropriate roles.

          Removing Directory Configuration

          If an existing ScrumWorks Pro directory configuration is removed or modified such that it breaks, ScrumWorks Pro will preserve directory users in the system. Directory users that are no longer supported by a directory configuration need to be converted to "ScrumWorks Authentication". Manual intervention is required because a password will need to be set for each user.
          Documentation Home | Web Client User Guide | Support and Training | ScrumWorks Desktop Client
          Copyright © 2013 CollabNet, Inc. All rights reserved.