|  |  |  | polkit Reference Manual |  | 
|---|
| pklocalauthoritypklocalauthority — PolicyKit Local Authority | 
The Local Authority is the default PolicyKit authority implementation. Configuration for the Local Authority and information pertaining to authorization decisions are read from local files on the disk. One design goal of the Local Authority is to split configuration items into separate files such that 3rd party packages and users won't conflict trying to edit the same files. This policy also ensures smooth upgrades when distributing PolicyKit using a package management system.
Files shipped with PolicyKit and 3rd party packages (e.g. under package manager control) typically have comments (such as “DO NOT EDIT THIS FILE, it will be overwritten on update”) telling the system administrator that changes will be overwritten on update.
PolicyKit makes a distinction between user authentication (to make the user in front of the system prove he really is the user) and administrator authentication (to make the user in front of the system prove he really is an administrator). Since various operating systems (or even flavors of the same operating system) has different ways of defining "administrator", the Local Authority provides a way to specify what "administrator authentication" means.
By default, "administrator authentication" is defined as asking for the root password. Since some systems, for usability reasons, don't have a root password and instead rely on a group of users being member of an administrative group that gives them super-user privileges, the Local Authority can be configured to support this use-case as well.
      Configuration for the Local Authority is read from files in
      the /etc/polkit-1/localauthority.conf.d
      directory. All files are read in lexigraphical order (using the
      C locale) meaning that later files can override earlier
      ones. The file 50-localauthority.conf
      contains the settings provided by the OS vendor. Users and 3rd
      party packages can drop configuration files with a priority
      higher than 60 to change the defaults. The configuration file
      format is simple. Each configuration file is a key
      file (also commonly known as a ini
      file) with a single group
      called [Configuration].  Only a single
      key, AdminIdentities is read.  The value of
      this key is a semi-colon separated list of identities that can
      be used when administrator authentication is required. Users are
      specified by prefixing the user name with
      unix-user:, groups of users are specified by 
      prefixing with unix-group:, and netgroups of
      users are specified with unix-netgroup:. See
      the section called “EXAMPLES” for an example of a
      configuration file.
    
      The Local Authority reads files with .pkla
      extension from all directories located inside the
      /etc/polkit-1/localauthority
      and /var/lib/polkit-1/localauthority
      directories. By default, the following sub-directories are installed.
    
/etc/polkit-1/
`-- localauthority
    |-- 10-vendor.d
    |-- 20-org.d
    |-- 30-site.d
    |-- 50-local.d
    `-- 90-mandatory.d
    
and
/var/lib/polkit-1/
`-- localauthority
    |-- 10-vendor.d
    |-- 20-org.d
    |-- 30-site.d
    |-- 50-local.d
    `-- 90-mandatory.d
    
      The /etc/polkit-1/localauthority hierarchy
      is inteded for local configuration and
      the /var/lib/polkit-1/localauthority is
      intended for 3rd party packages.
    
      Each .pkla file contains one or more
      authorization entries. If the underlying filesystem supports
      file monitoring, the Local Authority will reload information
      whenever .pkla files are added, removed or
      changed.
    
Each directory is intended for a specific audience
| 10-vendor.d | Intended for use by the OS vendor. | 
| 20-org.d | Intended for the organization deploying the OS. | 
| 30-site.d | Intended for the site deploying the system. | 
| 50-local.d | Intended for local usage. | 
| 90-mandatory.d | Intended for the organization deploying the OS. | 
and new directories can be added/removed as needed.
      As to regards to the content, each .pkla
      file is a standard key file and contains
      key/value pairs in one or more groups with each group
      representing an authorization entry.
      A .pkla file MUST be named by using a
      scheme to ensure that the name is unique, e.g. reverse DNS
      notation or similar. For example, if the organization is
      “Acme Corp” needs to modify policy for the
      product “Frobnicator”, a name
      like com.acme.frobnicator.pkla would be
      suitable.
    
      Each group in a .pkla file must have a name
      that is unique within the file it belongs to. The following keys
      are are recognized:
    
| Identity | 
            A semi-colon separated list of globs to match identities. Each glob
            should start with  | 
| Action | A semi-colon separated list of globs to match action identifiers. | 
| ResultActive | 
            The result to return for subjects in an active local
            session that matches one or more of the given identities.
            Allowed values are similar to what can be used in
            the defaults section
            of  | 
| ResultInactive | Like ResultActive but instead applies to subjects in inactive local sessions. | 
| ResultAny | Like ResultActive but instead applies to any subject. | 
| ReturnValue | A semi-colon separated list of key/value pairs (of the form key=value) that are added to the details of authorization result on positive matches. | 
All keys specified above are required except that only at least one of ResultAny, ResultInactive and ResultActive must be present. The ReturnValue key is optional.
When a Mechanism requests services from the Authority to check if a given Subject is authorized for a given Action, the authorization entries discussed above are consulted using the following algorithm.
      The authorization entries from all .pkla files are ordered using
      the following rules. First all the basename of all
      sub-directories (e.g. 30-site.d) from both
      the /etc/polkit-1/localauthority
      and /var/lib/polkit-1/localauthority
      directories are enumerated and sorted (using the C locale). If a
      name exists in both /etc
      and /var, the one
      in /etc takes precedence. Then
      all .pkla files are read in order from this
      list of sub-directories. For each .pkla
      file, authorizations from each file are appended in order resulting
      in an ordered list of authorization entries.
    
For example, given the following files
/var/lib/polkit-1
└── localauthority
    ├── 10-vendor.d
    │   └── 10-desktop-policy.pkla
    ├── 20-org.d
    ├── 30-site.d
    ├── 50-local.d
    ├── 55-org.my.company.d
    │   └── 10-org.my.company.product.pkla
    └── 90-mandatory.d
/etc/polkit-1
└── localauthority
    ├── 10-vendor.d
    │   └── 01-some-changes-from-a-subvendor.pkla
    ├── 20-org.d
    ├── 30-site.d
    ├── 50-local.d
    ├── 55-org.my.company.d
    │   └── 10-org.my.company.product.pkla
    └── 90-mandatory.d
    
      the evaluation order of the .pkla files is:
    
          10-desktop-policy.pkla
        
          01-some-changes-from-a-subvendor.pkla
        
          10-org.my.company.product.pkla (the /var one)
        
          10-org.my.company.product.pkla (the /etc one)
        
When the list of authorization entries has been calculated, the authorization check can be made. First, the user of the Subject is determined and the groups that the user belongs are looked up. For each group identity, the authorization entries are consulted in order. If the authorization check matches the data from the authorization check, then the authorization result from RequireAny, RequireInactive or RequireActive is used and ReturnValue is added to the authorization result.
Finally, the authorization entries are consulted using the user identity in the same manner.
Note that processing continues even after a match. This allows for socalled “negative authorizations”, see the section called “EXAMPLES” for further discussion.
      The following .conf file
    
[Configuration]
AdminIdentities=unix-group:staff
    
      specifies that any user in the staff UNIX
      group can be used for authentication when administrator
      authentication is needed. This file would typically be installed
      in the /etc/polkit-1/localauthority.conf.d
      directory and given the
      name 60-desktop-policy.conf to ensure that
      it is evaluted after
      the 50-localauthority.conf file shipped
      with PolicyKit. If the local administrator wants to override this (suppose 60-desktop-policy.conf was shipped as part of the OS) he can simply create a file 99-my-admin-configuration.conf with the following content
    
[Configuration]
AdminIdentities=unix-user:lisa;unix-user:marge
    
      to specify that only the users lisa
      and marge can authenticate when
      administrator authentication is needed.
    
      The following .pkla file grants
      authorization to all users in the staff group
      for actions matching the
      glob com.example.awesomeproduct.* provided
      they are in an active session on the local console:
    
[Normal Staff Permissions]
Identity=unix-group:staff
Action=com.example.awesomeproduct.*
ResultAny=no
ResultInactive=no
ResultActive=yes
    
      If the users homer and grimes are member of
      the staff group but policy requires that an
      administrator needs to authenticate every time authorization for
      any action
      matching com.example.awesomeproduct.* is
      required, one would add
    
[Exclude Some Problematic Users]
Identity=unix-user:homer;unix-user:grimes
Action=com.example.awesomeproduct.*
ResultAny=no
ResultInactive=no
ResultActive=auth_admin
    
and make sure this authorization entry is after the first one.
Please send bug reports to either the distribution or the polkit-devel mailing list, see the link http://lists.freedesktop.org/mailman/listinfo/polkit-devel on how to subscribe.