Creating your own Principal Adapter

Principal adapters are used by the authentication module to retrieve user and role information. For example, to retrieve users and roles from an LDAP directory or an external database that stores the company’s users and roles.

You can create your own Principal Adapter.

Conditions:

• The new Principal Adapter class must implement the “PrincipalAdapter” interface.
• The new Principal Adapter class must be declared in the package “com.openkm.plugin.principal”.
• The new Principal Adapter class must be annotated with “@PluginImplementation”.
• The new Principal Adapter class must extend “BasePlugin”.

Principal Adapter interface:

package com.openkm.plugin.principal;

import com.openkm.bean.CommonUser;
import com.openkm.db.bean.Profile;
import com.openkm.principal.PrincipalAdapterException;
import net.xeoh.plugins.base.Plugin;

import java.util.List;

public interface PrincipalAdapter extends Plugin {

    List<CommonUser> getUsers() throws PrincipalAdapterException;

    List<String> getRoles() throws PrincipalAdapterException;

    CommonUser getUser(String userId) throws PrincipalAdapterException;

    List<CommonUser> getUsersByRole(String role) throws PrincipalAdapterException;

    List<String> getRolesByUser(String user) throws PrincipalAdapterException;

    String getPassword(String user) throws PrincipalAdapterException;

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

    CommonUser createUser(CommonUser user) throws PrincipalAdapterException;

    void deleteUser(String user) throws PrincipalAdapterException;

    CommonUser updateUser(CommonUser user) throws PrincipalAdapterException;

    void createRole(String role, boolean active) throws PrincipalAdapterException;

    void deleteRole(String role) throws PrincipalAdapterException;

    void updateRole(String role, boolean active) throws PrincipalAdapterException;

    void assignRole(String user, String role) throws PrincipalAdapterException;

    void removeRole(String user, String role) throws PrincipalAdapterException;

    List<Profile> getProfiles(boolean filterByActive) throws PrincipalAdapterException;

    Profile getUserProfile(String userId) throws PrincipalAdapterException;

    void setUserProfile(String userId, long profileId) throws PrincipalAdapterException;

    boolean isManageUsers();

    boolean isManageRoles();
}

The new class must be loaded into the package com.openkm.plugin.principal because the application plugin system will try to load from there.

Caution

Do not omit the tag @PluginImplementation; otherwise, the application plugin system will not be able to retrieve the new class.

Note

More information at Register a new plugin.

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

For this change to take effect, we need to restart the application.

Method descriptions

Method	Type	Description
getUsers()	List	Returns a list of all users.
getRoles()	List	Returns a list of all roles.
getUser(String userId)	CommonUser	Returns all user data.
getUsersByRole(String role)	List	Returns a list of all users who have been assigned a role.
getRolesByUser(String user)	List	Returns a list of all roles assigned to a user.
String getPassword(String user)	String	Returns the password associated with a specific user.
createUser(CommonUser user)	void	Creates a new user.
deleteUser(String user)	void	Deletes a user.
updateUser(CommonUser user)	void	Updates a user. Password parameter can be null or empty.
createRole(String role, boolean active)	void	Creates a new role.
deleteRole(String role)	void	Deletes a role.
updateRole(String role, boolean active)	void	Updates a role.
assignRole(String user, String role)	void	Assigns a role to a user.
removeRole(String user, String role)	void	Revokes a role from a user.
getProfiles(boolean filterByActive)	List	Returns a list of all profiles.
getUserProfile(String userId)	Profile	Returns the profile assigned to a user.
setUserProfile(String userId, long profileId)	void	Changes the profile assigned to a user.
isManageUsers()	boolean	Returns a boolean that indicates whether the user is a manager.
isManageRoles()	boolean	Returns a boolean that indicates whether the role is managed.

Example of the Principal Adapter implementation

The example retrieves users, roles, and emails from properties files.

package com.openkm.plugin.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.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;

import com.openkm.api.OKMAuth;
import com.openkm.bean.CommonUser;
import com.openkm.core.Config;
import com.openkm.db.bean.Profile;
import com.openkm.plugin.BasePlugin;
import com.openkm.principal.PrincipalAdapterException;

public class UsersRolesPrincipalAdapter extends BasePlugin implements PrincipalAdapter {

    private static Logger log = LoggerFactory.getLogger(UsersRolesPrincipalAdapter.class);

    @Autowired
    private OKMAuth okmAuth;

    @Override
    public List<CommonUser> getUsers() throws PrincipalAdapterException {
        log.debug("getUsers()");
        List<CommonUser> list = new ArrayList<>();
        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)) {
                CommonUser commonUser = okmAuth.getUser(null, user);
                list.add(commonUser);
            }
        }

        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 CommonUser getUser(String userId) throws PrincipalAdapterException {
        throw new UnsupportedOperationException("getUser");
    }

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

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

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

    @Override
    public CommonUser createUser(CommonUser user) throws PrincipalAdapterException {
        throw new UnsupportedOperationException("createUser");
    }

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

    @Override
    public CommonUser updateUser(CommonUser user) throws PrincipalAdapterException {
        throw new UnsupportedOperationException("updateUser");
    }

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

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

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

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

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

    @Override
    public List<Profile> getProfiles(boolean filterByActive) throws PrincipalAdapterException {
        throw new UnsupportedOperationException("getProfiles");
    }

    @Override
    public Profile getUserProfile(String userId) throws PrincipalAdapterException {
        throw new UnsupportedOperationException("getUserProfile");
    }

    @Override
    public void setUserProfile(String userId, long profileId) throws PrincipalAdapterException {
        throw new UnsupportedOperationException("setUserProfile");
    }

    @Override
    public boolean isManageUsers() {
        throw new UnsupportedOperationException("isManageUsers");
    }

    @Override
    public boolean isManageRoles() {
        throw new UnsupportedOperationException("isManageRoles");
    }

}