OKMAuth

Used for managing security and users. For example add or remove grants on a node, create or modify users or getting the profiles.

Basics

The class com.openkm.bean.Permission contains permission values ( READ, WRITE, etc. ). You should use it in combination with methods that are changing or getting security grants.

To set READ and WRITE access you should do:

int permission = Permission.READ + Permission.WRITE;

To check if you have permission access you should do:

// permission is a valid integer value
if ((permission | Permission.WRITE) = Permission.WRITE) {
  // Has WRITE grants.
}

On almost methods you'll see parameter named "nodeId". The value of this parameter can be some valid node UUID ( folder, document, mail, record ) or node path.

Example of nodeId:

Using UUID -> "c41f9ea0-0d6c-45da-bae4-d72b66f42d0f";
Using path -> "/okm:root/sample.pdf"

Also on all methods you'll see parameter named "token". When accessing application across SOAP the login process returns a token, what is used to identify the user on all the exposed methods. From default application execution context you must use "null" value what indicates to the application must use the "user session".

On special cases you might be "promoted as Administrator" using the "administrator token".

String systemToken = DbSessionManager.getInstance().getSystemToken();

Methods

Description:

Method	Return values	Description
login()	void	Simulates user UI login process.
When user is logged from UI, are executed some background process what creates main user nodes, like /okm:trash. Unfortunatelly if the user has never logged from UI and login from API these nodes are still not created and will raise an error, for it is necessary at the beginning execute login method. The user must be logged before executing the method.

Method

Return values

Description

login()

void

Simulates user UI login process.

When user is logged from UI, are executed some background process what creates main user nodes, like /okm:trash. Unfortunatelly if the user has never logged from UI and login from API these nodes are still not created and will raise an error, for it is necessary at the beginning execute login method.

The user must be logged before executing the method.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().login();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Description:

Method	Return values	Description
login(String user, String pass)	void	Simulates user UI login process.
When user is logged from UI, are executed some background process what creates main user nodes, like /okm:trash. Unfortunatelly if the user has never logged from UI and login from API these nodes are still not created and will raise an error, for it is necessary at the beginning execute login method.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().login("userId","password");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

logout

Description:

Method	Return values	Description
logout()	void	Kill user session.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().logout();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

grantUser

Description:

Method	Return values	Description
grantUser(String token, String nodeId, String user, int permissions, boolean recursive)	void	Add user grant on a node.
The parameter recursive only has sense when the nodeId is a folder or record node. When parameter recursive is true, the change will be applied to the node and descendants.

Method

Return values

Description

grantUser(String token, String nodeId, String user, int permissions, boolean recursive)

void

Add user grant on a node.

The parameter recursive only has sense when the nodeId is a folder or record node.

When parameter recursive is true, the change will be applied to the node and descendants.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;

public class Test {
    public static void main(String[] args) {
        try {
            // Add john write grants at the node but not descendants
            OKMAuth.getInstance().grantUser(null, "/okm:root", "john", Permission.ALL_GRANTS, false);

            // Add all okmAdmin grants at the node and descendants
            OKMAuth.getInstance().grantUser(null, "/okm:root", "okmAdmin", Permission.ALL_GRANTS, true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

revokeUser

Description:

Method	Return values	Description
revokeUser(String token, String nodeId, String user, int permissions, boolean recursive)	void	Remove user grant on a node.
The parameter recursive only has sense when the nodeId is a folder or a record node. When parameter recursive is true, the change will be applied to the node and descendants.

Method

Return values

Description

revokeUser(String token, String nodeId, String user, int permissions, boolean recursive)

void

Remove user grant on a node.

The parameter recursive only has sense when the nodeId is a folder or a record node.

When parameter recursive is true, the change will be applied to the node and descendants.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;

public class Test {
    public static void main(String[] args) {
        try {
            // Remove john write grants at the node but not descendants
            OKMAuth.getInstance().revokeUser(null, "/okm:root", "john", Permission.ALL_GRANTS, false);

            // Remove all okmAdmin grants at the node and descendants
            OKMAuth.getInstance().revokeUser(null, "/okm:root", "okmAdmin", Permission.ALL_GRANTS, true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getGrantedUsers

Description:

Method	Return values	Description
getGrantedUsers(String token, String nodeId)	Map<String, Integer>	Return the granted users of a node.

Example:

package com.openkm;

import java.util.Map;
import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            Map<String, Integer> grants = OKMAuth.getInstance().getGrantedUsers(null, "/okm:root");
            for (String role : grants.keySet()) {
                System.out.println(role + "->" + grants.get(role));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

grantRole

Description:

Method	Return values	Description
grantRole(String token, String nodeId, String role, int permissions, boolean recursive)	void	Add role grant on a node.
The parameter recursive only has sense when the nodeId is a folder or a record node. When parameter recursive is true, the change will be applied to the node and descendants.

Method

Return values

Description

grantRole(String token, String nodeId, String role, int permissions, boolean recursive)

void

Add role grant on a node.

The parameter recursive only has sense when the nodeId is a folder or a record node.

When parameter recursive is true, the change will be applied to the node and descendants.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;

public class Test {
    public static void main(String[] args) {
        try {
            // Add ROLE_USER write grants at the node but not descendants
            OKMAuth.getInstance().grantRole(null, "/okm:root", "ROLE_USER", Permission.ALL_GRANTS, false);

            // Add all ROLE_ADMIN grants to the node and descendants
            OKMAuth.getInstance().grantRole(null, "/okm:root", "ROLE_ADMIN", Permission.ALL_GRANTS, true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

revokeRole

Description:

Method	Return values	Description
revokeRole(String token, String nodeId, String role, int permissions, boolean recursive)	void	Remove role grant on a node.
The parameter recursive only has sense when the nodeId is a folder or a record node. When parameter recursive is true, the change will be applied to the node and its descendants.

Method

Return values

Description

revokeRole(String token, String nodeId, String role, int permissions, boolean recursive)

void

Remove role grant on a node.

The parameter recursive only has sense when the nodeId is a folder or a record node.

When parameter recursive is true, the change will be applied to the node and its descendants.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;

public class Test {
    public static void main(String[] args) {
        try {
            // Remove ROLE_USER write grants at the node but not descendants
            OKMAuth.getInstance().revokeRole(null, "/okm:root", "ROLE_USER", Permission.ALL_GRANTS, false);

            // Remove all ROLE_ADMIN grants to the node and descendants
            OKMAuth.getInstance().revokeRole(null, "/okm:root", "ROLE_ADMIN", Permission.ALL_GRANTS, true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getGrantedRoles

Description:

Method	Return values	Description
getGrantedRoles(String token, String nodeId)	Map<String, Integer>	Return the granted roles of a node.

Example:

package com.openkm;

import java.util.Map;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            Map<String, Integer> grants = OKMAuth.getInstance().getGrantedRoles(null,"/okm:root");
            for (String role : grants.keySet()) {
                System.out.println(role + "->" + grants.get(role));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getUsers

Description:

Method	Return values	Description
getUsers(String token)	List<String>	Return the list of all the users.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            for (String user : OKMAuth.getInstance().getUsers(null)) {
                System.out.println(user);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getRoles

Description:

Method	Return values	Description
getRoles(String token)	List<String>	Return the list of all the roles.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            for (String user : OKMAuth.getInstance().getRoles(null)) {
                System.out.println(user);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getUsersByRole

Description:

Method	Return values	Description
getUsersByRole(String token, String role)	List<String>	Return the list of all the users who have assigned a role.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            for (String user : OKMAuth.getInstance().getUsersByRole(null, "ROLE_ADMIN")) {
                System.out.println(user);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getRolesByUser

Description:

Method	Return values	Description
getRolesByUser(String token, String user)	List<String>	Return the list of all the roles assigned to a user.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            for (String role : OKMAuth.getInstance().getRolesByUser(null, "okmAdmin")) {
                System.out.println(role);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getMail

Description:

Method	Return values	Description
getMail(String token, String user)	String	Return the mail of a valid user.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            System.out.println(OKMAuth.getInstance().getMail(null, "okmAdmin"));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getName

Description:

Method	Return values	Description
getName(String token, String user)	String	Return the name of a valid user.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            System.out.println(OKMAuth.getInstance().getName(null, "okmAdmin"));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

changeSecurity

Description:

Method	Return values	Description
public void changeSecurity(String token, String nodeId, Map<String, Integer> grantUsers, Map<String, Integer> revokeUsers, Map<String, Integer> grantRoles, Map<String, Integer> revokeRoles, boolean recursive)	void	Change the security of a node.

Example:

package com.openkm;

import java.util.*;
import com.openkm.bean.Permission;
import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
             String nodeId = "b9736924-bb97-4e2c-8450-138c21e0c9d5";
             Map<String, Integer> grantUsers = new HashMap<>();
             Map<String, Integer> revokeUsers = new HashMap<>();
             Map<String, Integer> grantRoles = new HashMap<>();
             grantRoles.put("ROLE_TEST", Permission.READ | Permission.WRITE);	
             Map<String, Integer> revokeRoles = new HashMap<>();
             OKMAuth.getInstance().changeSecurity(null, nodeId, grantUsers, revokeUsers, grantRoles, revokeRoles, false);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

createUser

Description:

Method	Return values	Description
createUser(String token, String user, String password, String email, String name, boolean active)	void	Create a new user.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().createUser(null, "test", "password.2016", "some@mail.com", "User Name", true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

deleteUser

Description:

Method	Return values	Description
deleteUser(String token, String user)	void	Delete a user.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().deleteUser(null, "test");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

updateUser

Description:

Method	Return values	Description
updateUser(String token, String user, String password, String email, String name, boolean active)	void	Update a user.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().updateUser(null, "test", "newpassword", "some@mail.com", "Test", false);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

createRole

Description:

Method	Return values	Description
createRole(String token, String role, boolean active)	void	Create a new role.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().createRole(null, "ROLE_TEST", true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

deleteRole

Description:

Method	Return values	Description
deleteRole(String token, String role)	void	Delete a role.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().deleteRole(null, "ROLE_TEST");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

updateRole

Description:

Method	Return values	Description
updateRole(String token, String role, boolean active)	void	Update a role.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().updateRole(null, "ROLE_TEST",true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

assignRole

Description:

Method	Return values	Description
assignRole(String token, String user, String role)	void	Assign role to a user.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().assignRole(null, "test", "ROLE_USER");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

removeRole

Description:

Method	Return values	Description
removeRole(String token, String user, String role)	void	Remove a role from a user.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
            OKMAuth.getInstance().removeRole(null, "test", "ROLE_USER");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getProfiles

Description:

Method	Return values	Description
getProfiles(String token, boolean filterByActive)	List<Profile>	Return the list of all profiles.
The parameter filterByActive when enabled the method will return only the active profiles, otherwise will return all available profiles. Each user has assigned one profile that enables more or less of the OpenKM UI features.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Profile;

public class Test {
    public static void main(String[] args) {
        try {
            for (Profile profile : OKMAuth.getInstance().getProfiles(null, true)) {
                System.out.println(profile);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getUserProfile

Description:

Method	Return values	Description
getUserProfile(String token, String userId)	Profile	Return the profile assigned to a user.
Each user has assigned one profile that enables more or less of the OpenKM UI features.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;

public class Test {
    public static void main(String[] args) {
        try {
	    System.out.println(OKMAuth.getInstance().getUserProfile(null, "okmAdmin"));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

setUserProfile

Description:

Method	Return values	Description
(String token, String userId, long profileId)	void	Change the assigned profile to a user.
Each user has assigned one profile that enables more or less of the OpenKM UI features.

Example:

package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Profile;

public class Test {
    public static void main(String[] args) {
        try {
	    // Set the profile named "default" to the user
            for (Profile profile : OKMAuth.getInstance().getProfiles(null, true)) {
                if (profile.getName().equals("default")) {
                    OKMAuth.getInstance().setUserProfile(null, "okmAdmin", profile.getId());
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Table of contents [ Hide Show ]

Basics
Methods

login
login
logout
grantUser
revokeUser
getGrantedUsers
grantRole
revokeRole
getGrantedRoles
getUsers
getRoles
getUsersByRole
getRolesByUser
getMail
getName
changeSecurity
createUser
deleteUser
updateUser
createRole
deleteRole
updateRole
assignRole
removeRole
getProfiles
getUserProfile
setUserProfile

OpenKM 6.4

OKMAuth

Basics

Methods

login

login

logout

grantUser

revokeUser

getGrantedUsers

grantRole

revokeRole

getGrantedRoles

getUsers

getRoles

getUsersByRole

getRolesByUser

getMail

getName

changeSecurity

createUser

deleteUser

updateUser

createRole

deleteRole

updateRole

assignRole

removeRole

getProfiles

getUserProfile

setUserProfile