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:

To enable the new Principal adapter go to Administration > Configuration parameters > find the parameter named principal.adapter and modify the value with com.openkm.adapter.OwnPrincipalAdapter

To take effect this change we need to restart the application.

Methods description

MethodTypeDescription

getUsers()

List<String>

Return a list of users ID.

getRoles()

List<String>

Return a list of roles ID.

getUsersByRole(String role)()

List<String>

Return a list of users ID filtered by a role.

getRolesByUser(String user)

List<String>

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