Creating your own Principal Adapter

Principal adapters are used by authentication module to retrieve users and roles information. For example retrieve users and roles from some LDAP, or external database that stores all the company users and roles.

To create your own antivirus analiser must create a new class that implements PrincipalAdapter interface:

package com.openkm.principal;

import java.util.List;

public interface PrincipalAdapter {

  /**
   * Method to retrieve all users from a authentication source.
   *
   * @return A Collection with all the users.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public List<String> getUsers() throws PrincipalAdapterException;

  /**
   * Method to retrieve all roles from a authentication source.
   *
   * @return A Collection with all the roles.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public List<String> getRoles() throws PrincipalAdapterException;

  /**
   * Method to retrieve all users from a role.
   *
   * @return A Collection with all the users within a role.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public List<String> getUsersByRole(String role) throws PrincipalAdapterException;

  /**
   * Method to retrieve all roles from a user.
   *
   * @return A Collection with all the roles of the user.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public List<String> getRolesByUser(String user) throws PrincipalAdapterException;

  /**
   * Method to retrieve the mail from a user.
   *
   * @param user A user id.
   * @return The email of the user.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public String getMail(String user) throws PrincipalAdapterException;

  /**
   * Method to retrieve the name from a user.
   *
   * @param user A user id.
   * @return The name of the user.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public String getName(String user) throws PrincipalAdapterException;

  /**
   * Method to retrieve the user password
   *
   * @param user A user id.
   * @return The password of the user.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public String getPassword(String user) throws PrincipalAdapterException;

  /*
   * ------------------------------------------------------------------
   * These methods only works if using the OpenKM user database.
   * ------------------------------------------------------------------
   */

  /**
   * Method to create a new user
   *
   * @param user A user id.
   * @param password The password of the user.
   * @param email The user mail.
   * @param name The full user name.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public void createUser(String user, String password, String email, String name, boolean active) throws PrincipalAdapterException;

  /**
   * Method to create a delete a user
   *
   * @param user A user id.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public void deleteUser(String user) throws PrincipalAdapterException;

  /**
   * Update user information
   *
   * @param user A user id.
   * @param password The password of the user.
   * @param email The user mail.
   * @param name The full user name.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public void updateUser(String user, String password, String email, String name, boolean active) throws PrincipalAdapterException;

  /**
   * Method to create a new role
   *
   * @param role A role id.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public void createRole(String role, boolean active) throws PrincipalAdapterException;

  /**
   * Method to create a delete a role
   *
   * @param role A role id.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public void deleteRole(String role) throws PrincipalAdapterException;

  /**
   * Update role information
   *
   * @param role A role id..
   * @throws PrincipalAdapterException If any error occurs.
   */
  public void updateRole(String role, boolean active) throws PrincipalAdapterException;

  /**
   * Method to assign a role
   *
   * @param user A user id.
   * @param role A role id.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public void assignRole(String user, String role) throws PrincipalAdapterException;

  /**
   * Method to remove a role
   *
   * @param user A user id.
   * @param role A role id.
   * @throws PrincipalAdapterException If any error occurs.
   */
  public void removeRole(String user, String role) throws PrincipalAdapterException;
}

The new class must be loaded into the package com.openkm.principal because application plugins system will try to load from there. See the sample below:

Methods description

Method	Type	Description
getUsers()	List	Return a list of users ID.
getRoles()	List	Return a list of roles ID.
getUsersByRole(String role)()	List	Return a list of users ID filtered by a role.
getRolesByUser(String user)	List	Return a list of roles ID filtered by a user.
getMail(String user)	String	Return the mail associated to a specific user.
getName(String user)	String	Return the name associated to a specific user.
String getPassword(String user)	String	Return the password associated to a specific user.
createUser(String user, String password, String email, String name, boolean active)	void	Create a new user.
deleteUser(String user)	void	Delete a user.
updateUser(String user, String password, String email, String name, boolean active)	void	Update user values. Password parameter can be null or empty.
createRole(String role, boolean active)	void	Create a new role.
deleteRole(String role)	void	Delete a role.
updateRole(String role, boolean active)	void	Update a role.
assignRole(String user, String role)	void	Grant user with some role.
removeRole(String user, String role)	void	Revoke a role to some user.

Example of the Principal adapter implementation

The example retrieves users, roles and mails based on properties files.

package com.openkm.principal;

import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.List;
import java.util.Properties;
import java.util.StringTokenizer;

import org.apache.commons.lang.NotImplementedException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.openkm.core.Config;

public class UsersRolesPrincipalAdapter implements PrincipalAdapter {
  private static Logger log = LoggerFactory.getLogger(UsersRolesPrincipalAdapter.class);

  @Override
  public List<String> getUsers() throws PrincipalAdapterException {
    log.debug("getUsers()");
    List<String> list = new ArrayList<String>();
    Properties prop = new Properties();

    try {
      prop.load(new FileInputStream(Config.HOME_DIR + "/server/default/conf/props/openkm-users.properties"));
    } catch (FileNotFoundException e) {
      e.printStackTrace();
    } catch (IOException e) {
      e.printStackTrace();
    }

    for (Enumeration<Object> e = prop.keys(); e.hasMoreElements();) {
      String user = (String) e.nextElement();
      if (!Config.SYSTEM_USER.equals(user)) {
        list.add(user);
      }
    }

    log.debug("getUsers: {}", list);
    return list;
  }

  @Override
  public List<String> getRoles() throws PrincipalAdapterException {
    log.debug("getRoles()");
    List<String> list = new ArrayList<String>();
    Properties prop = new Properties();

    try {
      prop.load(new FileInputStream(Config.HOME_DIR + "/server/default/conf/props/openkm-roles.properties"));
    } catch (FileNotFoundException e) {
      e.printStackTrace();
    } catch (IOException e) {
      e.printStackTrace();
    }

    for (Enumeration<Object> e = prop.elements(); e.hasMoreElements();) {
      for (StringTokenizer st = new StringTokenizer((String) e.nextElement(), ","); st.hasMoreTokens();) {
        String role = st.nextToken();

        if (!Config.DEFAULT_ADMIN_ROLE.equals(role) && !list.contains(role)) {
          list.add(role);
        }
      }
    }

    log.debug("getRoles: {}", list);
    return list;
  }

  @Override
  public List<String> getUsersByRole(String role) throws PrincipalAdapterException {
    throw new NotImplementedException("getUsersByRole");
  }

  @Override
  public List<String> getRolesByUser(String user) throws PrincipalAdapterException {
    throw new NotImplementedException("getRolesByUser");
  }

  @Override
  public String getMail(String user) throws PrincipalAdapterException {
    log.debug("getMail({})", user);
    Properties prop = new Properties();
    String mail = null;

    try {
      prop.load(new FileInputStream(Config.HOME_DIR + "/server/default/conf/props/openkm-emails.properties"));
    } catch (FileNotFoundException e) {
      e.printStackTrace();
    } catch (IOException e) {
      e.printStackTrace();
    }

    mail = prop.getProperty(user);
    log.debug("getMail: {}", mail);
    return mail;
  }

  @Override
  public String getName(String user) throws PrincipalAdapterException {
    log.debug("getName({})", user);
    Properties prop = new Properties();
    String name = null;

    try {
      prop.load(new FileInputStream(Config.HOME_DIR + "/server/default/conf/props/openkm-names.properties"));
    } catch (FileNotFoundException e) {
      e.printStackTrace();
    } catch (IOException e) {
      e.printStackTrace();
    }

    name = prop.getProperty(user);
    log.debug("getName: {}", name);
    return name;
  }

  @Override
  public String getPassword(String user) throws PrincipalAdapterException {
    throw new UnsupportedOperationException("Not implemented");
  }

  @Override
  public void createUser(String user, String password, String email, String name, boolean active) throws PrincipalAdapterException {
    throw new NotImplementedException("createUser");
  }

  @Override
  public void deleteUser(String user) throws PrincipalAdapterException {
    throw new NotImplementedException("deleteUser");
  }

  @Override
  public void updateUser(String user, String password, String email, String name, boolean active) throws PrincipalAdapterException {
    throw new NotImplementedException("updateUser");
  }

  @Override
  public void createRole(String role, boolean active) throws PrincipalAdapterException {
    throw new NotImplementedException("createRole");
  }

  @Override
  public void deleteRole(String role) throws PrincipalAdapterException {
    throw new NotImplementedException("deleteRole");
  }

  @Override
  public void updateRole(String role, boolean active) throws PrincipalAdapterException {
    throw new NotImplementedException("updateRole");
  }

  @Override
  public void assignRole(String user, String role) throws PrincipalAdapterException {
    throw new NotImplementedException("assignRole");
  }

  @Override
  public void removeRole(String user, String role) throws PrincipalAdapterException {
    throw new NotImplementedException("removeRole");
  }
}