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

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");
	}
}