Creating Directory Service Providers

To create an implementation that allows for the retrieval of user and group records (principals), implement the DirectoryUserProvider.getPrincipals method. User Management invokes this method repeatedly until all of the specified records are retrieved. The getPrincipals method requires the following parameters:

• config: A com.adobe.idp.um.spi.directoryservices.DirectoryProviderConfig object that contains information about the records to retrieve. Information within this object include the domain and other information specific to the implementation. This object provides access to either a com.adobe.idp.um.spi.directoryservices.UserConfigBO or com.adobe.idp.um.spi.directoryservices.GroupConfigBO object.

• state: An Object that contains the state returned from the previous call to the method, or null for the initial call. You can create an object of any type as long as it is serializable and available to the server. Each time it is updated, you pass it back to LiveCycle using the com.adobe.idp.um.spi.directoryservices.DSPrincipalCollection.setState method.

The getPrincipals method returns a com.adobe.idp.um.spi.directoryservices.DSPrincipalCollection object that contains either the retrieved user records and state, or null if records were not returned.

Within your implementation of the getPrincipals method, you can create application logic that retrieves user records from the use repository. For example, you can create application logic that retrieves records from the spi.users database. The directory service provider uses classes located in the java.sql.* package to retrieve records from the spi.users database.

To successfully retrieve records from a user repository, create a DSPrincipalRecord instance for each user that you retrieve. A DSPrincipalRecord object represents a user (or group) that becomes a LiveCycle user (or group). Using methods that belong to the DSPrincipalRecord object, you can set user information such as the user’s common name, email, identifier value, and so on. For example, to set the user’s email value, invoke the DSPrincipalRecord instance’s setEmail method. You can retrieve values to pass from the result set from the database query. Add each DSPrincipalRecord instance to the DSPrincipalCollection object by invoking its addDSPrincipalRecord method.

The following application logic shows a database query. The results are passed as parameters when invoking methods that belong to the DSPrincipalRecord instance.

//Prepare the return collection 
DSPrincipalCollection collection = new DSPrincipalCollection(); 
 
//Create connection to mySQL server 
Class.forName("com.mysql.jdbc.Driver"); 
Connection con = DriverManager.getConnection("jdbc:mysql://hsmithk-380:3306/spi", "root", "password"); 
Statement statement = con.createStatement(); 
 
//Branch to the correct type of principal for the sync 
if(principalType.equals(UMConstants.PrincipalTypes.PRINCIPALTYPE_USER)){ 
 
//Select all users from the Users table 
ResultSet res = statement.executeQuery("SELECT * FROM users"); 
while(res.next()){ 
 
//Create a record and set general properties 
DSPrincipalRecord record = new DSPrincipalRecord(); 
record.setDomainName(domainName); 
record.setPrincipalType(principalType); 
record.setDisabled(false); 
record.setVisibility(2); 
 
//Retrieve data from the SQL query 
String userid = res.getString("userid"); 
String firstName = res.getString("firstName"); 
String lastName = res.getString("lastName"); 
String email = res.getString("email"); 
 
//Mandatory field for the record 
record.setCanonicalName(firstName + " " + lastName); 
 
//Set other info pulled from the database 
record.setCommonName(firstName + " " + lastName); 
record.setUserid(userid); 
record.setGivenName(firstName); 
record.setFamilyName(lastName); 
record.setEmail(email); 
                     
//Add the record to the return collection 
collection.addDSPrincipalRecord(record); 
} 
}

Your implementation of the DirectoryGroupProvider interface must include a getGroupMembers method that is used to retrieve associations between users and groups. The getGroupMembers method requires the following parameters:

• config: A com.adobe.idp.um.spi.directoryservices.DirectoryProviderConfig object that contains information about the records to retrieve. This object also contains the GroupConfigBO object as configured by User Management.

• group: A com.adobe.idp.um.spi.directoryservices.DSPrincipalIdRecord that identifies the group whose members are retrieved. This object contains the domain name and canonical name of the group.

The getGroupMembers method returns a com.adobe.idp.um.spi.directoryservices.DSGroupContainmentRecord object that contains the retrieved user records of the group.

To successfully retrieve group records, create a DSPrincipalRecord instance for each group record that you retrieve. Create a DSPrincipalRecord object that represents the group. Using methods that belong to the DSPrincipalRecord object, you can set group information such as the group name, description, and email. For example, to set the group’s email value, invoke the DSPrincipalRecord instance’s setEmail method. You can retrieve values to pass from the result set from the database query. Add each DSPrincipalRecord instance to the DSPrincipalCollection object by invoking its addDSPrincipalRecord method.

The sample directory service provider consists of two classes:

• SampleDirectoryManager: Handles the requests from LiveCycle to retrieve user and group data. This class implements the implements DirectoryUserProvider and DirectoryGroupProvider classes. This class must contain the following methods: getPrincipals, getGroupMembers, and testConfiguration.

• DirectoryController: Retrieves user and group data from the MySQL database. This class retrieves data from the MySQL database by using classes located in the java.sql.* package.

The following application logic represents the SampleDirectoryManager class.

package com.adobe.livecycle.samples.directory.provider; 
 
import com.adobe.idp.common.errors.exception.IDPException; 
import com.adobe.idp.um.api.UMConstants; 
import com.adobe.idp.um.spi.directoryservices.DSGroupContainmentRecord; 
import com.adobe.idp.um.spi.directoryservices.DSPrincipalCollection; 
import com.adobe.idp.um.spi.directoryservices.DSPrincipalIdRecord; 
import com.adobe.idp.um.spi.directoryservices.DirectoryGroupProvider; 
import com.adobe.idp.um.spi.directoryservices.DirectoryProviderConfig; 
import com.adobe.idp.um.spi.directoryservices.DirectoryUserProvider; 
import com.adobe.livecycle.samples.directory.provider.DirectoryController; 
 
/** 
    * This class provides a sample implementation of User and Group provider SPIs.      
    */ 
 
public class SampleDirectoryManager implements DirectoryUserProvider, 
        DirectoryGroupProvider { 
 
    /* This method is used to obtain all the Users and Groups from any directory. The config object passed to this  
     * method would determine whether to return Users or groups. If config.getUserConfig() is not null then users would 
     * be returned and if config.getGroupConfig() is not null then groups would be returned. 
     */ 
     
    public DSPrincipalCollection getPrincipals(DirectoryProviderConfig config, 
            Object state) throws IDPException { 
         
        if (config.getUserConfig() == null && config.getGroupConfig() == null)  { 
            return null; 
        } 
         
        String principalType = UMConstants.PrincipalTypes.PRINCIPALTYPE_USER; 
 
        if (config.getGroupConfig()  != null) { 
            principalType = UMConstants.PrincipalTypes.PRINCIPALTYPE_GROUP; 
        } 
         
        /* Because the getPrincipals method is continuously called by the sync application 
         * we must tell it to stop after the first pass. 
         * In DirectoryController we set the state event to "Done" so that the next time  
         * this method is called, it will return null, meaning the end of the sync. 
         */ 
        if (state != null) { 
            return null; 
        }  
         
        DirectoryController directoryController = new DirectoryController(principalType, config.getDomain()); 
        return directoryController.getPrincipalsBatch(); 
    } 
 
    /* 
     * Once all the users & groups have been retrieved by calling getPrincipals, LiveCycle will call this method  
     * to obtain user-group associations. Here it just need to pass all those users which belong to the group  
     * being sent here. 
     */ 
    public DSGroupContainmentRecord getGroupMembers( 
            DirectoryProviderConfig config, DSPrincipalIdRecord group) 
            throws IDPException { 
 
        System.out.println("Sending Members of Group : " + group.getCanonicalName()); 
        DSGroupContainmentRecord dsGroupContainmentRecord = DirectoryController.getGroupMembers(group); 
        return dsGroupContainmentRecord; 
    } 
 
    /* 
     * This is a utility method that could be used to validate the settings of 
     * the custom directory whether it's running as expected or not. 
     */ 
 
    public boolean testConfiguration(DirectoryProviderConfig config) { 
        return DirectoryController.testConfiguration(config); 
 
    } 
 
} 

The following application logic represents the DirectoryController class.

package com.adobe.livecycle.samples.directory.provider; 
 
import java.sql.Connection; 
import java.sql.DriverManager; 
import java.sql.ResultSet; 
import java.sql.Statement; 
import java.util.Arrays; 
 
import com.adobe.idp.common.errors.exception.IDPException; 
import com.adobe.idp.um.api.UMConstants; 
import com.adobe.idp.um.spi.directoryservices.DSGroupContainmentRecord; 
import com.adobe.idp.um.spi.directoryservices.DSPrincipalCollection; 
import com.adobe.idp.um.spi.directoryservices.DSPrincipalIdRecord; 
import com.adobe.idp.um.spi.directoryservices.DSPrincipalRecord; 
import com.adobe.idp.um.spi.directoryservices.DirectoryProviderConfig; 
 
/** 
    * This class is an intermediary module which will talk to user repository  
    * to retrieve users and groups in a domain. Hence, it will act as a Controller 
    * interacting with custom directories. 
    */ 
 
public class DirectoryController { 
 
    private String principalType; 
    private String domainName; 
 
    public DirectoryController( String principalType, String domainName) { 
        super(); 
        this.principalType = principalType; 
        this.domainName = domainName; 
    } 
 
    /** 
     * This method returns a batch of principals (users or groups) from the directory.  
     */ 
    public DSPrincipalCollection getPrincipalsBatch() { 
         
        //Prepare the return collection 
        DSPrincipalCollection collection = new DSPrincipalCollection(); 
         
        try{ 
            //Create connection to mySQL server 
            Class.forName("com.mysql.jdbc.Driver"); 
            Connection con = DriverManager.getConnection("jdbc:mysql://hsmithk-380:3306/spi", "root", "password"); 
            Statement statement = con.createStatement(); 
 
            //Branch to the correct type of principal for the sync 
            if(principalType.equals(UMConstants.PrincipalTypes.PRINCIPALTYPE_USER)){ 
                 
                //Select all users from the Users table 
                ResultSet res = statement.executeQuery("SELECT * FROM users"); 
                while(res.next()){ 
 
                    //Create a record and set general properties 
                    DSPrincipalRecord record = new DSPrincipalRecord(); 
                    record.setDomainName(domainName); 
                    record.setPrincipalType(principalType); 
                    record.setDisabled(false); 
                    record.setVisibility(2); 
                     
                    //Retrieve data from the SQL query 
                    String userid = res.getString("userid"); 
                    String firstName = res.getString("firstName"); 
                    String lastName = res.getString("lastName"); 
                    String email = res.getString("email"); 
 
                    //Mandatory field for the record 
                    record.setCanonicalName(firstName + " " + lastName); 
 
                    //Set other info pulled from the database 
                    record.setCommonName(firstName + " " + lastName); 
                    record.setUserid(userid); 
                    record.setGivenName(firstName); 
                    record.setFamilyName(lastName); 
                    record.setEmail(email); 
                     
                    //Add the record to the return collection 
                    collection.addDSPrincipalRecord(record); 
                } 
            }else{ 
                 
                //Select all groups from the Groups table 
                ResultSet res = statement.executeQuery("SELECT * FROM groups "); 
                while(res.next()){ 
 
                    //Create a record and set general properties 
                    DSPrincipalRecord record = new DSPrincipalRecord(); 
                    record.setDomainName(domainName); 
                    record.setPrincipalType(principalType); 
                    record.setDisabled(false); 
                    record.setVisibility(2); 
 
                    //Retrieve data from the SQL query 
                    String name = res.getString("name"); 
                    String desc = res.getString("desc"); 
                    String email = res.getString("email"); 
                    String aliases = res.getString("aliases"); 
 
                    //Mandatory field for the record 
                    record.setCanonicalName(name); 
 
                    //Set other info pulled from the database 
                    record.setCommonName(name); 
                    record.setDescription(desc); 
                    record.setEmail(email); 
                     
                    //The setEmailAliases requires a list as parameter, so we split the string 
                    //containing the comma-seperated email addresses. 
                    record.setEmailAliases(Arrays.asList(aliases.split(","))); 
 
                    //Add the record to the return collection 
                    collection.addDSPrincipalRecord(record); 
                } 
            } 
        }catch(Exception e){ 
            e.printStackTrace(); 
        } 
         
        //Set state to done so that we won't iterate through the list again. 
        collection.setState("DONE"); 
        return collection; 
    } 
 
    /** 
     * This method will return all the users which belong to a particular group. The group members are  
     * formed by randomly selecting users. 
     */ 
    public static DSGroupContainmentRecord getGroupMembers(DSPrincipalIdRecord group) 
    throws IDPException { 
         
        //Create the record and set the group properties 
        DSGroupContainmentRecord record = new DSGroupContainmentRecord(); 
        record.setDomainName(group.getDomainName()); 
        record.setCanonicalName(group.getCanonicalName()); 
         
        try{ 
             
            //Create a connection to the database 
            Class.forName("com.mysql.jdbc.Driver"); 
            Connection con = DriverManager.getConnection("jdbc:mysql://hsmithk-380:3306/spi", "root", "password"); 
            Statement statement = con.createStatement(); 
 
            //Query the membership, to get the users who are in the group 
            ResultSet res = statement.executeQuery("SELECT * FROM users where userid IN (select userid from membership where groupName='"+group.getCanonicalName()+"')"); 
            while(res.next()){ 
                 
                //Retrieve data form resultSet 
                String firstName = res.getString("firstName"); 
                String lastName = res.getString("lastName"); 
                 
                //Create a new DSPrincipalIdRecord member and match the info from the database 
                DSPrincipalIdRecord member = new DSPrincipalIdRecord(); 
                member.setDomainName(group.getDomainName()); 
                member.setCanonicalName(firstName + " "+ lastName); 
                 
                //Add the user to the list of members 
                record.addPrincipalMember(member); 
            } 
        }catch(Exception e){ 
            e.printStackTrace(); 
        } 
         
        //return the list of members 
        return record; 
 
    } 
 
    /** 
     * This method can be used to validate the settings of the custom directory 
     * whether it's running as expected or not 
     *  
     */ 
    public static boolean testConfiguration(DirectoryProviderConfig config) { 
        System.out.println("Testing configuration unimplemented"); 
        return true; 
    } 
 
}