Difference between revisions of "OpenKM authentication"

From OpenKM Documentation
Jump to: navigation, search
m (→‎Roles)
 
(33 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
Authentication (from Greek: αυθεντικός; real or genuine, from authentes; author) is the act of establishing or confirming something (or someone) as authentic, that is, that claims made by or about the subject are true. This might involve confirming the identity of a person, the origins of an artifact, or assuring that a computer program is a trusted one. This task is addressed by JAAS.
+
{{TOCright}} __TOC__
  
−
JAAS uses a service provider approach to its authentication features, meaning that it is possible to configure different login modules for an application without changing any code. The application remains unaware of the underlying authentication logic. It's even possible for an application to contain multiple login modules, somewhat akin to a stack of authentication procedures.
+
Authentication (from Greek: αυθεντικός; real or genuine, from authentes; author) is the act of establishing or confirming something (or someone) as authentic, that is, that claims made by or about the subject are true. This might involve confirming the identity of a person, the origins of an artifact, or assuring that a computer program is a trusted one.
  
−
OpenKM relies the authentication on the standard JAAS implemented in JBoss application server. JBoss comes with some interesting modules which can be used to authenticate against a plain-text file, a database or an LDAP, for example. On recent versions, OpenKM uses the DatabaseServerLoginModule class to manage authentication.  
+
{{Note|Authentication is handled by '''SpringSecurity in OpenKM 6.2''' and '''JBoss and JAAS in OpenKM 5.1'''.}}
  
−
The JBoss security is configured in the file ''$JBOSS_HOME/server/default/conf/login-config.xml''.
+
{{Advice|OpenKM 5.1.x is deployed in JBoss which uses JAAS. Read [[Debugging_OpenKM#Debugging_JAAS_configuration|Debugging JAAS configuration]] to learn how to debug a problematic JAAS configuration.}}
  
−
Also remember the principal.adapter configuration option. OpenKM need this configuration to create a list of users and roles available in the changing permissions dialog. This is done by the '''DatabasePrincipalAdapter''' class. This is an implementation of the '''es.git.openkm.principal.PrincipalAdapter''' interface:
+
Also remember the '''principal.adapter''' configuration option. OpenKM need this configuration to create a list of users and roles available in the changing permissions dialog. This is done by the '''DatabasePrincipalAdapter''' class. This is an implementation of the '''com.openkm.principal.PrincipalAdapter''' interface:
  
 
<source lang="java">
 
<source lang="java">
Line 13: Line 13:
 
     /**
 
     /**
 
     * Method to retrieve all users from a authentication source.
 
     * Method to retrieve all users from a authentication source.
−
     *
+
     *  
 
     * @return A Collection with all the users.
 
     * @return A Collection with all the users.
 
     * @throws PrincipalAdapterException If any error occurs.
 
     * @throws PrincipalAdapterException If any error occurs.
 
     */
 
     */
−
     public Collection<String> getUsers() throws PrincipalAdapterException;
+
     public List<String> getUsers() throws PrincipalAdapterException;
  
 
     /**
 
     /**
 
     * Method to retrieve all roles from a authentication source.
 
     * Method to retrieve all roles from a authentication source.
−
     *
+
     *  
 
     * @return A Collection with all the roles.
 
     * @return A Collection with all the roles.
 
     * @throws PrincipalAdapterException If any error occurs.
 
     * @throws PrincipalAdapterException If any error occurs.
 
     */
 
     */
−
     public Collection<String> getRoles() throws PrincipalAdapterException;
+
     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 users 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 mail from a list of users.
+
     * Method to retrieve the name from a user.
−
     *
+
     *  
−
     * @param users A list of users.
+
     * @param users A user id.
−
     * @return A list of user emails.
+
     * @return The name of the user.
 
     * @throws PrincipalAdapterException If any error occurs.
 
     * @throws PrincipalAdapterException If any error occurs.
 
     */
 
     */
−
     public Collection<String> getMails(Collection<String> users) throws PrincipalAdapterException;
+
     public String getName(String user) throws PrincipalAdapterException;
 
}
 
}
 
</source>
 
</source>
  
−
== Plain-text file ==
+
== Roles ==  
−
This is the simplest security configuration. This was the default authentication method in older OpenKM versions. It is achieved using the JBoss UsersRolesLoginModule login module. User are stored in the file ''$JBOSS_HOME/server/default/conf/props/openkm-users.properties'' in this form:
+
OpenKM has two roles defined by default: '''ROLE_ADMIN''' and '''ROLE_USER'''.
−
 
 
−
<source lang="java">
 
−
user1=pass1
 
−
user2=pass2
 
−
...
 
−
</source>
 
−
 
 
−
The password in not encrypted. The roles are in the file ''$JBOSS_HOME/server/default/conf/props/openkm-roles.properties'' in this form:
 
−
 
 
−
<source lang="java">
 
−
user1=Rol1,Rol2,...
 
−
user1=Rol1,Rol2,...
 
−
...
 
−
</source>
 
−
 
 
−
This is the JBoss configuration for this method:
 
−
 
 
−
<source lang="xml">
 
−
<application-policy name = "OpenKM">
 
−
  <authentication>
 
−
    <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag = "required">
 
−
        <module-option name="usersProperties">props/openkm-users.properties</module-option>
 
−
        <module-option name="rolesProperties">props/openkm-roles.properties</module-option>
 
−
    </login-module>
 
−
    <login-module code="org.jboss.security.ClientLoginModule" flag="required" />
 
−
  </authentication>
 
−
</application-policy>
 
−
</source>
 
−
 
 
−
The principal.adapter should be set to es.git.openkm.principal.UsersRolesPrincipalAdapter.
 
−
 
 
−
== Database ==
 
−
This is the default security configuration for recent OpenKM version. Is a good option because simplifies user and role management: now user and roles can be managed from OpenKM administration. This module connect to the database using a data-source.
 
−
 
 
−
<source lang="xml">
 
−
<application-policy name = "OpenKM">
 
−
  <authentication>
 
−
    <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag = "required">
 
−
        <module-option name="dsJndiName">java:/OKMAuthDS</module-option>
 
−
        <module-option name="principalsQuery">select usr_pass as PASSWD from users where usr_id=? and usr_active='true'</module-option>
 
−
      <module-option name="rolesQuery">select ur_role as ROLEID, 'Roles' from user_role where ur_user=?</module-option>
 
−
    </login-module>
 
−
  </authentication>
 
−
</application-policy>
 
−
</source>
 
−
 
 
−
The principal.adapter should be set to es.git.openkm.principal.DatabasePrincipalAdapter, which is the default value.
 
−
 
 
−
== LDAP (Active Directory, Open Directory) ==
 
−
You can get LDAP integration through the LdapExtLoginModule login module.
 
−
 
 
−
<source lang="xml">
 
−
<application-policy name="OpenKM">
 
−
  <authentication>
 
−
    <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="required" >
 
−
      <module-option name="java.naming.provider.url">ldap://my-company.com:389</module-option>
 
−
      <module-option name="bindDN">cn=My_adm_account,ou=Admin Accounts,dc=my-company,dc=br</module-option>
 
−
      <module-option name="java.naming.security.authentication">simple</module-option>
 
−
      <module-option name="bindCredential">My_adm_account_password</module-option>
 
−
      <module-option name="baseCtxDN">ou=Users Accounts,dc=my-company,dc=com</module-option>
 
−
      <module-option name="baseFilter">(sAMAccountName={0})</module-option>
 
−
      <module-option name="rolesCtxDN">ou=Users Accounts,dc=my-company,dc=com</module-option>
 
−
      <module-option name="roleFilter">(sAMAccountName={0})</module-option>
 
−
      <module-option name="roleAttributeID">memberOf</module-option>
 
−
      <module-option name="roleAttributeIsDN">true</module-option>
 
−
      <module-option name="roleNameAttributeID">cn</module-option>
 
−
      <module-option name="roleRecursion">-1</module-option>
 
−
      <module-option name="searchScope">SUBTREE_SCOPE</module-option>
 
−
      <module-option name="defaultRole">UserRol</module-option>
 
−
    </login-module>
 
−
  </authentication>
 
−
</application-policy>
 
−
</source>
 
−
 
 
−
Here are some configuration comments:
 
−
 
 
−
* '''bindDN''': This is some DN with read/search permissions on the baseCtxDN and rolesCtxDN.
 
−
* '''bindCredential''': The password for the bindDN.
 
−
* '''baseCtxDN''': The fixed DN of the context to start the user search from.
 
−
* '''rolesCtxDN''': The fixed DN of the context to search for user roles.
 
−
 
 
−
Don't forget the <module-option name="defaultRole">UserRol</module-option> (adds this role to every authenticated user, because only users with that role are allowed to access OpenKM)
 
−
 
 
−
Here are some tips on OSX OpenDirectory:
 
−
 
 
−
* '''Create user''': dscl . -create /Users/openkm
 
−
* '''Assign shell''': dscl . -create /Users/openkm UserShell /bin/bash
 
−
* '''Assign user name''': dscl . -create /Users/openkm RealName "OpenKM user"
 
−
* '''Search UID''': dscl . -search /Users uid 503
 
−
* '''Assign UID''': dscl . -create /Users/openkm UniqueID 503
 
−
* '''Assign user home''': dscl . -create /Users/openkm NFSHomeDirectory /opt/openkm
 
−
* '''Assign password''': dscl . -passwd /Users/openkm xxxxxx
 
  
−
More on OpenDirectory and the dscl Tool at
+
'''ROLE_USER''' is mandatory for all users, because is internally used by OpenKM for connection purposes. Without this right, users can not connect to OpenKM and you'll get a 403 status code error.
−
[http://developer.apple.com/mac/library/documentation/Porting/Conceptual/PortingUnix/intro/intro.html Introduction to Porting UNIX/Linux Applications to Mac OS X].
 
  
−
More information about JASS and other login modules can be found at:
+
You can give '''ROLE_ADMIN''' to any user, and he'll get administrator privileges, seeing any folder and doing any operation without retrictions. Users with '''ROLE_ADMIN''' have access to the administrator tab in the web user interface.
  
−
* http://jboss.org/community/docs/DOC-10760.
+
[[Category: Installation Guide]]
−
* LdapExtLoginModule: http://www.jboss.org/community/docs/DOC-11251.
 
−
* OSXOpenDirectoryLoginConfig.xml: http://www.jboss.org/community/docs/DOC-11530.
 

Latest revision as of 19:25, 1 December 2012

Contents

Authentication (from Greek: αυθεντικός; real or genuine, from authentes; author) is the act of establishing or confirming something (or someone) as authentic, that is, that claims made by or about the subject are true. This might involve confirming the identity of a person, the origins of an artifact, or assuring that a computer program is a trusted one.


Nota clasica.png Authentication is handled by SpringSecurity in OpenKM 6.2 and JBoss and JAAS in OpenKM 5.1.


Nota idea.png OpenKM 5.1.x is deployed in JBoss which uses JAAS. Read Debugging JAAS configuration to learn how to debug a problematic JAAS configuration.

Also remember the principal.adapter configuration option. OpenKM need this configuration to create a list of users and roles available in the changing permissions dialog. This is done by the DatabasePrincipalAdapter class. This is an implementation of the com.openkm.principal.PrincipalAdapter interface: 

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 users 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 users A user id.
     * @return The name of the user.
     * @throws PrincipalAdapterException If any error occurs.
     */
    public String getName(String user) throws PrincipalAdapterException;
}

Roles

OpenKM has two roles defined by default: ROLE_ADMIN and ROLE_USER.

ROLE_USER is mandatory for all users, because is internally used by OpenKM for connection purposes. Without this right, users can not connect to OpenKM and you'll get a 403 status code error.

You can give ROLE_ADMIN to any user, and he'll get administrator privileges, seeing any folder and doing any operation without retrictions. Users with ROLE_ADMIN have access to the administrator tab in the web user interface.

Retrieved from "https://www.openkm.com/wiki/index.php?title=OpenKM_authentication&oldid=8104"