The ISyncProvider interface provides methods used by the portal to synchronize users and groups with a back-end repository. The methods of ISyncProvider are typically called in this order:

1. ISyncProvider.Initialize()
2. ISyncProvider.GetGroups()
3. ISyncProvider.Initialize()
4. ISyncProvider.GetUsers()
5. ISyncProvider.Initialize()
6. ISyncProvider.AttachToGroup()

Because the portal may take a long time between calls to GetGroups(), GetUsers() and AttachToGroup(), Initialize() is called more than once. This ensures that any configuration information passed to the synchronization service is available, even if the session has timed out.

1. Implement ISyncProvider.Initialize

   The Initialize() method is passed a SyncInfo object from the portal. The SyncInfo object is a set of name-value pairs, populated with information entered in the portal Service Configuration Interface (SCI) editor by a portal administrator. Typically, this is information such as credentials for connecting to the back-end system.

   Java:

   public boolean initialize(SyncInfo info)
     throws ServiceException
   {
       return true;
   }

   C#:

   public bool Initialize(SyncInfo syncInfo)
   {
       return true;
   }

   For this example authentication service, there is no need to perform any initialization, so the method simply returns true.

   In a production implementation, false should be returned if initialization fails. For example, if the authentication service cannot make a connection with the back-end repository. If false is returned, the synchronization job will stop.

2. Implement ISyncProvider.GetGroups

   The GetGroups() method is responsible for returning all of the groups from the back-end system. A SyncObject should be created for each group, using the static SyncObject.CreateGroup() method. The return value, a SyncObjectList, is then constructed using an array of SyncObject objects and a boolean flag, isDone.

   The isDone flag determines whether or not the GetGroups() method will be called again. When you have a large number of groups in your back-end system, you can return groups to the portal in smaller batches. The size of each batch should be based on network bandwidth, the SOAP timeout set in the Authentication Web Service, and the speed of the back-end system. As a general rule, return no more than 1000 groups per batch.

   If GetUsers() returns SyncObjects in batches, it must maintain state and set isDone to false until the last batch. Otherwise, isDone should be set to true.

   Java:

   public SyncObjectList getGroups()
     throws ServiceException
   {
     SyncObject[] groups = new SyncObject[1];
     groups[0] = SyncObject.createGroup(
         Constants.GROUPNAME,
         Constants.GROUPNAME);
     return new SyncObjectList(groups, true);
   }

   C#:

   public SyncObjectList GetGroups()
   {
     SyncObject[] groups = new SyncObject[1];
     groups[0] = SyncObject.CreateGroup(
         Constants.GROUPNAME,
         Constants.GROUPNAME);
     return new SyncObjectList(groups, true);
   }

   For this authentication service, GetGroups() returns a single group, BASEGROUP. As stated above, Constants.GROUPNAME is a String set to "BASEGROUP". SyncObject.CreateGroup() accepts two String arguments. The first argument is the name the imported group will have in the portal. The second argument is the name of the group in the back-end system. In this case, we set both to "BASEGROUP". The returned SyncObjectList is then constructed with the single item SyncObject array and the isDone flag set to true, signifying there are no more groups for the portal to synchronize.

3. Implement ISyncProvider.GetUsers

   The GetUsers() method is responsible for returning all of the users from the back-end system. Similar to GetGroups(), a SyncObject should be created for each group. For GetUsers(), use the static SyncObject.CreateUser() method to create each new SyncObject. The return value, a SyncObjectList, is then constructed using an array of SyncObject objects and a boolean flag, isDone.

   As with GetGroups(), the isDone flag tells the portal whether it should call GetUsers() again or not, allowing you to break retrieval of users into batches. The size of each batch should be based on network bandwidth, the SOAP timeout set in the Authentication Web Service, and the speed of the back-end system. As a general rule, return no more than 1000 users per batch.

   If GetUsers() returns SyncObjects in batches, it must maintain state and set isDone to false until the last batch. Otherwise, isDone should be set to true.

   Java:

   public SyncObjectList getUsers()
     throws ServiceException
   {
       SyncObject[] users = new SyncObject[10];
       for (int i = 0; i < 10; i++)
       {
         String userName = Constants.USERNAME + i;
         users[i] = SyncObject.createUser(
             userName, userName, userName);
       }
       return new SyncObjectList(users, true);
   \}

   C#

   public SyncObjectList GetUsers()
   {
       SyncObject[] users = new SyncObject[10];
       for (int i = 0; i < 10; i++)
       {
         String userName = Constants.USERNAME + i;
         users[i] = SyncObject.CreateUser(
                      userName, userName, userName);
       }
       return new SyncObjectList(users, true);

   For this authentication service, GetUsers() returns ten users, TESTUSER0 - TESTUSER9. An array of ten SyncObject objects is created, and then populated using a for loop. The SyncObject.CreateUser() method takes three String arguments: The first is the name of the user in the portal, the second is the user name that will be passed for authentication, and the third is the name of the user in the back-end system. In this case, all are set to the same String, Constants.USERNAME + i.

   The returned SyncObjectList is then constructed with the ten item SyncObject array and the isDone flag set to true, signifying there are no more users for the portal to synchronize.

4. Implement ISyncProvider.AttachToGroup

   AttachToGroup() returns an IGroup object that allows the portal to query for users and groups contained within a given group. For details on implementing the IGroup interface, see Implementing the IGroup Interface, below. AttachToGroup() is passed a String, a group identifier on the back-end system. This is the same as the second argument passed to SyncObject.CreateGroups() in ISyncProvider.GetGroups(). AttachToGroup() should return an instance of an implementation of the IGroup interface.

   Java:

   public IGroup attachToGroup(String groupID)
     throws ServiceException
   {
       if (groupID.equals(Constants.GROUPNAME))
       {
         return new Group();
       }
       else
       {
         return null;
       }
   }

   C#:

   public IGroup AttachToGroup(String groupID)
   {
       if (groupID.Equals(Constants.GROUPNAME))
         return new Group();
       else
         return null;
   }

   For this authentication service, there is only one group, BASEGROUP. If the group ID passed to AttachToGroup() is BASEGROUP, a Group object is returned. Otherwise, null is returned. This is highly simplified; in a production implementation, AttachToGroup() would query a back-end system and return a group object with specific information for the given group.

The IGroup interface provides methods that allow the portal to determine relationships between users and groups. The portal takes the IGroup object returned from each call to ISyncProvider.AttachToGroup() and calls two IGroup methods:

1. IGroup.GetChildGroups()
2. IGroup.GetChildUsers()

Similar to the ISyncProvider.GetGroups() and ISyncProvider.GetUsers() methods, the GetChildGroups() and GetChildUsers() methods return objects that contain an array of either groups or users. In both cases, the isDone flag can be used to send results back to the portal in batches. The size of each batch should be based on network bandwidth, the SOAP timeout set in the Authentication Web Service, and the speed of the back-end system. As a general rule, return no more than 1000 groups or users per batch.

1. Implement IGroup.GetChildGroups

   The GetChildGroups() method defines which child groups (subgroups) each group contains. The child groups are returned as ChildGroup objects in a ChildGroupList object. The ChildGroup constructor takes a single String argument, the unique name that identifies the group in the authentication service. The ChildGroupList constructor should be passed the array of ChildGroup objects and the isDone flag. If you want to return child groups in batches, your implementation of IGroup must maintain state internally and the isDone flag must be set to false until the final batch.

   Java:

   public ChildGroupList getChildGroups()
     throws ServiceException
   {
       ChildGroup[] children = new ChildGroup[0]);
       return new ChildGroupList(children, true);
   }

   C#:

   public ChildGroupList GetChildGroups()
   {
       ChildGroup[] children = new ChildGroup[0];
       return new ChildGroupList(children, true);
   }

   In this example authentication service, there are no child groups, so an empty array is returned.

2. Implement IGroup.GetChildUsers

   The GetChildUsers() method returns the user membership of the group. The users are returned as ChildUser objects, which are constructed with the same arguments as ISyncProvider.CreateUser(). The ChildUserList constructor should be passed the array of ChildGroup objects and the isDone flag. If you want to return child users in batches, your implementation of IGroup must maintain state internally and the isDone flag must be set to false until the final batch.

   Java:

   public ChildUserList getChildUsers()
     throws ServiceException
   {
       ChildUser[] users = new ChildUser[10];
       for (int i = 0; i < 10; i++)
       {
         String userName = Constants.USERNAME + i;
         users[i] = new ChildUser(userName, userName, userName);
       }
   \    return new ChildUserList(users, true);
   }

   C#:

   public ChildUserList GetChildUsers()
   {
       ChildUser[] users = new ChildUser[10];
       for (int i = 0; i < 10; i++)
       {
         String userName = Constants.USERNAME + i;
         users[i] = new ChildUser(userName, userName, userName);
       }
       return new ChildUserList(users, true);
   }

   For this authentication service, GetChildUsers() returns the same ten users as ISyncProvider.GetUsers(), TESTUSER0 - TESTUSER9. An array of ten ChildUser objects is created, and then populated using a for loop. The ChildUser constructor takes three String arguments: the first is the name of the user in the portal, the second is the user name that will be passed for authentication, and the third is the name of the user in the back-end system. In this case, all are set to the same String, Constants.USERNAME + i.

   The returned ChildUserList is then constructed with the ten item ChildUser array and the isDone flag set to true, signifying there are no more users associated with this group.

The IAuthProvider interface validates credentials from a portal login against a back-end repository. There is a single method to implement,Authenticate().

The Authenticate() method is passed three arguments: two Strings for username and password, and an AuthInfo object. The AuthInfo object, like the SyncInfo object passed to ISyncProvider.Initialize(), is a set of name-value pairs, populated with information entered in the portal SCI editor by a portal administrator. Typically, this is information such as credentials for connecting to the back-end system.

If the credentials passed are valid, Authenticate() should return normally; however, if the credentials are invalid, an exception of type ServiceException must be thrown. See the IDK API documentation for a complete description of the exceptions derived from ServiceException.

Java:

public void authenticate(String username,
               String password, AuthInfo authinfo)
  throws ServiceException
{
    if (username.startsWith(Constants.USERNAME_BASE) &&     
        password.startsWith(Constants.USERNAME_BASE))
    {
      //do nothing- authenticated
    }
    else
    {
      throw new AccessDeniedException();
    }
}

C#:

public void Authenticate(String username,
               String password, AuthInfo authInfo)
{
    if (username.StartsWith(Constants.USERNAME) &&
        password.StartsWith(Constants.USERNAME))
    {
       //do nothing- authenticated
    }
    else
    {
      throw new AccessDeniedException();
    }
}

For this authentication service, if the username and password passed in start with Constants.USERNAME ("TESTUSER"), the user is authenticated. Otherwise, an AccessDeniedException is thrown.