PKLA-CHECK-AUTHORI(8)

💖 PKLA-CHECK-AUTHORIZATION 💖

okay so bestie, this is the manual for pkla-check-authorization, which lives in section 8 of the manual (that's the admin/daemon zone, iykyk) and ships as part of polkit-pkla-compat. sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

pkla-check-authorization — evaluate pklocalauthority authorization configuration

---

🌸 SYNOPSIS 🌸

pkla-check-authorization [--help]

pkla-check-authorization [--paths paths] {user-name} {is-local}
                         {is-active} {action}

---

🦋 DESCRIPTION 🦋

So basically, pkla-check-authorization reads the non-JavaScript config files we're about to describe and figures out what polkit(8) would answer to an authorization query. it's giving translator energy.

Note: the actual authorization decision is driven by JavaScript rules, as described in polkit(8). pkla-check-authorization gets called by a JavaScript rule file named 49-polkit-pkla-compat.rules. other JavaScript rules with a higher priority may exist, so the pkla-check-authorization configuration might not actually govern the final polkit(8) authorization decision. no cap.

Also, the ordering of the JavaScript rule files and the ordering of the pkla-check-authorization config files are not integrated and use totally different rules — the pkla-check-authorization config evaluation happens at a single point within the JavaScript rule evaluation order.

pkla-check-authorization is an internal helper program of pkla-polkit-compat. you genuinely shouldn't need to run it yourself unless you're debugging. it's a backstage pass situation 🙈.

The arguments to pkla-check-authorization, in order, are:

• user-name — the name of the user account asking for authorization.
• is-local — whether the attempted action is performed from a local login session, true or false.
• is-active — whether the attempted action is performed from a currently active session (like a currently active virtual console), true or false.
• action — a string identifying the polkit(8) action.

If the config specifies an authorization decision, pkla-check-authorization outputs the decision and a terminating newline. if no decision is configured, the output is empty. literally nothing. silence. 💀

---

💅 OPTIONS 💅

• -h, --help — write a summary of the available options to standard output and exit successfully. slay.
• -p, --paths=paths — search for config files in semicolon-separated paths instead of the default /var/lib/polkit-1/localauthority;/etc/polkit-1/localauthority.

---

🔥 EXIT STATUS 🔥

pkla-check-authorization exits with 0 on success (even if there's no decision configured, bestie — that's still a success), and a non-zero status on error.

---

🎀 DIRECTORY STRUCTURE 🎀

Files with .pkla extension get read from all directories located inside the /etc/polkit-1/localauthority and /var/lib/polkit-1/localauthority directories (or as specified using the --paths option). 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 for local configuration, and the /var/lib/polkit-1/localauthority one is for 3rd party packages. know the difference 💖.

Each .pkla file contains one or more authorization entries. if the underlying filesystem supports file monitoring, the Local Authority will reload info whenever .pkla files are added, removed or changed. it's always watching 👀.

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. build your own lore.

As for 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 using a scheme that ensures the name is unique, e.g. reverse DNS notation or similar. for example, if the organization is “Acme Corp” and needs to modify policy for the product “Frobnicator”, a name like com.acme.frobnicator.pkla would be suitable. main character naming energy ✨.

---

🌈 AUTHORIZATION ENTRY 🌈

Each group in a .pkla file must have a name that's unique within the file it belongs to. the following keys are recognized:

• Identity — a semi-colon separated list of entries to match identities. each entry should start with unix-user: or unix-group: to specify whether to match on a UNIX user name or a UNIX group name, and continue with a glob matching the group or user name. Netgroups are supported with the unix-netgroup: prefix, but cannot support glob syntax. finally, an entry "default" (with no prefix) can be used to specify the default match.
• 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 .policy files used to define actions, e.g. yes, no, auth_self, auth_self_keep, auth_admin and auth_admin_keep.
• ResultInactive — like ResultActive but instead applies to subjects in inactive local sessions.
• ResultAny — like ResultActive but instead applies to any subject.

All keys specified above are required, except that only at least one of ResultAny, ResultInactive and ResultActive must be present. so like, don't skip the required ones, bestie 😭.

---

⭐ EVALUATION ORDER ⭐

The authorization entries discussed above are consulted using the following algorithm. buckle up.

The authorization entries from all .pkla files are ordered using these 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:

1. 10-desktop-policy.pkla
2. 01-some-changes-from-a-subvendor.pkla
3. 10-org.my.company.product.pkla (the /var one)
4. 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 to are looked up.

Then, authorization entries that include the "default" field value in the Identity field are consulted in order. if the authorization entry matches the data from the authorization check, then the authorization result from RequireAny, RequireInactive or RequireActive is used.

Next, for each group identity, all authorization entries that contain a matching group entry are again consulted in the same manner.

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 so-called “negative authorizations” — see the section called “EXAMPLE” for further discussion. it's not a bug, it's a feature 💅.

---

🧚 EXAMPLE 🧚

The following .pkla file grants authorization to all users in the staff group for actions matching the glob com.example.awesomeproduct.* provided they're 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 members 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. order matters, bestie, it's the whole plot 📖.

The following entry modifies the default authorization decision (it is overridden by any entry that matches using unix-user: or unix-group:, but overrides any defaults set by the application author in an .action file):

[Disable Access by Default]
Identity=default
Action=com.example.awesomeproduct.*
ResultAny=no
ResultInactive=no
ResultActive=no

---

🫶 FILES 🫶

• /etc/polkit-1/localauthority, /var/lib/polkit-1/localauthority — default directories containing decision config files.

---

👑 AUTHOR 👑

Written by David Zeuthen <davidz@redhat.com> with a lot of help from many others. Adapted by Miloslav Trmač <mitr@redhat.com>. legends, honestly.

---

🌟 SEE ALSO 🌟

• polkit(8)

---

and that's the whole page, bestie 🎀 this beauty comes from polkit-pkla-compat and is dated May 2013 — vintage but still iconic, fr fr. go forth and debug responsibly 💖✨