Difference between revisions of "Using filesystem access controls"

From FileSys.Org Wiki
 
(One intermediate revision by the same user not shown)
Line 115: Line 115:
 
=== Registering Your Custom Access Control Rules ===
 
=== Registering Your Custom Access Control Rules ===
  
To make your custom access control rules available to the default access control manager you must register the parser classes with the access control manager via the server configuration file.
+
To make your custom access control rules available to the default access control manager you must register the parser classes with the access control manager via the ''<security>'' section of the server configuration file.
 +
 
 +
The following syntax is used to add custom access control rules to the default access control manager :-
 +
 
 +
<security>
 +
    ...
 +
    <accessControlManager>
 +
        <class>org.filesys.server.auth.acl.DefaultAccessControlManager</class>
 +
        <rule>...</rule>
 +
        <rule>...</rule>
 +
        ...
 +
    </accessControlManager>
 +
</security>
 +
 
 +
The default access control manager class must be specified via the ''<class>'' configuration value. Each custom rule full class name of the access control parser class is specified within the ''<rule>'' configuration value.

Latest revision as of 13:18, 26 September 2019

The JFileServer has an access control mechanism that allows the virtual filesystem access to be controlled depending on a set of rules. A set of access control rules can be applied on a per filesystem basis and/or via a global set of access control rules.

The access control mechanism has a built in set of rules but can also be extended with new rules. The access control mechanism can also be customised if required by writing your own access control manager class that implements the org.filesys.server.auth.acl.AccessControlManager interface.

The allowed access for an access control can be specified as Read for read-only access, Write for read/write access or None to disallow access. A virtual filesystem access control that evaluates to the None access level will not be visible to the client.

The following built-in access control rules are available :-

Access Control Rule Description
<user name="..." access="..."/> Set access depending on the connecting user name
<protocol type="..." access="..."/> Set access depending on the connecting protocol. The type parameter should contain a comma delimited list of protocol names - SMB, FTP, NFS
<address subnet="..." mask="..." access="..."/> Set access depending on the client TCP/IP address, for a range of addresses.

The subnet parameter specifies the network subnet in n.n.n.n format. The mask parameter specifies the network mask in n.n.n.n format.

<address ip="..." access="..."/> Set access depending on the client TCP/IP address, for a specific address.

The ip parameter specifies the client address in n.n.n.n format.

<domain name="..." access="..."/> Set access depending on the client domain name. This rule only applies to SMB sessions.
<gid id="..." access="..."/> Set access depending on the client group id. This rule only applies to NFS sessions.
<uid id="..." access="..."/> Set access depending on the client user id. This rule only applies to NFS sessions.

How Access Controls Are Applied

A client can connect to the file server through a number of different protocols depending on what is enabled for the server. The client connection will usually start with an authentication phase before it then tries to connect to one or more virtual filesystems. When the client tries to connect to a particular virtual filesystem, or it may try to connect to, or get a list of, all available virtual filesystems, then the access control rules will be evaluated.

If the result of evaluating the access control rules for a virtual filesystem is an access level of None then the virtual filesystem will not be visible to the client.

Setting Access Controls On A Virtual Filesystem

To add access control rules to a virtual filesystem an <accessControl default="..."> block of access control rules is added to the <diskshare> virtual filesystem configuration section. The following syntax is used :-

<shares>
    <diskshare name="..." comment="...">
        ...

        <accessControl default="...">
            ...
        </accessControl>
    </diskshare>
</shares>

The default="..." parameter of the <accessControl> block is an optional default access control level to be applied if none of the access control rules match the current client session values. The possible values for the default="..." setting are the same as for access control rules, ie. Read or Write or None.

It is valid to have an access control block with a default access of Read or Write without any rules within the access control block, eg.

<accessControl default="Read"/>

In this case all clients will only be allowed read access to the virtual filesystem.

Setting Global Access Controls

A set of global access controls can be specified that apply to all virtual filesystems that do not have their own set of access controls.

The global access control block is specified via the <security> configuration section using the following syntax :-

<security>
    ...

    <globalAccessControl default="...">
        ...
    </globalAccessControl>
</security>

As with the per virtual filesystem access control block the default="..." parameter is optional.

Adding Your Own Access Control Rules

The access control mechanism can be extended by adding your own access control rules. The access control rules evaluate their result using the session and shared filesystem details. The session object can be used to access other objects specific to the session such as the client information object which contains details about the client and client connection.

To implement a new access control rule requires two classes to be created, the parser class and the access control rule class.

The parser class is responsible for parsing the rule parameters and creating the access control rule instance with those specific settings. The parser class must extend the org.filesys.server.auth.acl.AccessControlParser abstract class.

There are two methods to be implemented for the parser class :-

public abstract String getType();
public abstract AccessControl createAccessControl(ConfigElement params)
    throws ACLParseException;

The getType() method returns the unique type name for the access control. This will be the rule name used in the access control configuration block.

The createAccessControl() method parses the configuration parameters for the access control and creates the access control instance with those settings.

The access control class is responsible for evaluating the access level at runtime when a client is connecting to a particular virtual filesystem or is getting a list of the available virtual filesystems. The access control class must extend the org.filesys.server.auth.acl.AccessControl abstract class.

The access control implementation must call the AccessControl constructor :-

protected AccessControl(String name, String type, int access);

The name parameter can be used to hold a parameter value for the access control rule eg. the required user name value, the type parameter should be the unique type name from the access control parser and the access parameter will be the access type parsed from the access parameter.

The access control must implement the abstract method :-

public abstract int allowsAccess(SrvSession sess, SharedDevice share, AccessControlManager mgr);

The allowsAccess() method evaluates the allowed access and returns a value of Read, Write or None.

Registering Your Custom Access Control Rules

To make your custom access control rules available to the default access control manager you must register the parser classes with the access control manager via the <security> section of the server configuration file.

The following syntax is used to add custom access control rules to the default access control manager :-

<security>
    ...
    <accessControlManager>
        <class>org.filesys.server.auth.acl.DefaultAccessControlManager</class>
        <rule>...</rule>
        <rule>...</rule>
        ...
    </accessControlManager>
</security>

The default access control manager class must be specified via the <class> configuration value. Each custom rule full class name of the access control parser class is specified within the <rule> configuration value.