# Authentication Agent

This part discusses the GNOME/GTK+ specific Authentication Agent.

## Overview

The PolicyKit model provides letting an user authenticate in order to gain the privilege to let a Mechanism carry work out related to a specific Action on the users behalf. In the PolicyKit libraries, this functionality is programmatically exposed in the PolKitGrant class. As it's tedious to use this low-level functionality from a GTK+ or GNOME application, the high-level functionality is wrapped in a D-Bus service available on the session message bus. The way it works is that when an application needs privileges, it can call into this D-Bus service and an authentication dialog will appear. When the user is done with the authentication dialog, the application recieves a reply from the D-Bus containing a boolean indicating whether the user gained the privilege or not.

## D-Bus interface

The D-Bus service is available on the session message bus with the name `org.freedesktop.PolicyKit.AuthenticationAgent` and exports a single object `/` that implements the interface `org.freedesktop.PolicyKit.AuthenticationAgent`. The D-Bus introspection XML looks like this

    <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
             "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">

    <node name="/">

      <!-- this interface is deprecated and will be removed in a future release -->
      <interface name="org.gnome.PolicyKit.Manager">
        <method name="ShowDialog">
          <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>

          <!-- IN: PolicyKit action identifier; see PolKitAction -->
          <arg name="action_id" direction="in" type="s"/>

          <!-- IN: X11 window ID for the top-level X11 window the dialog will be transient for. -->
          <arg name="xid" direction="in" type="u"/>

          <!-- OUT: whether the user gained the authorization -->
          <arg name="gained_authorization" direction="out" type="b"/>

        </method>
      </interface>

      <interface name="org.freedesktop.PolicyKit.AuthenticationAgent">
        <method name="ObtainAuthorization">
          <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>

          <!-- IN: PolicyKit action identifier; see PolKitAction -->
          <arg name="action_id" direction="in" type="s"/>

          <!-- IN: X11 window ID for the top-level X11 window the dialog will be transient for. -->
          <arg name="xid" direction="in" type="u"/>

          <!-- IN: Process ID to grant authorization to -->
          <arg name="pid" direction="in" type="u"/>

          <!-- OUT: whether the user gained the authorization -->
          <arg name="gained_authorization" direction="out" type="b"/>

        </method>
      </interface>

    </node>

The `ObtainAuthorization()` method may throw an exception if another client is currently using the service to show an authentication dialog. In practice this should never happen because the authentication daemon grabs the X11 keyboard and pointer thus preventing the user from activating widgets in other applications that would lead to calling into the `ObtainAuthorization` method.

## Operation

The authentication daemon uses `libpolkit-grant` which in turn uses PAM for authentication services (however, other authentication back-ends can be plugged in as required). As such, a wide range of authentication mechanisms are available.

The authentication daemon is using D-Bus activation and exits after 30 seconds of inactivity. Thus the code implementing this dialog only runs when necessary.

## UI elements

The appearance of the authentication dialog depends on the result from PolicyKit and also whether administrator authentication is defined as "authenticate as the root user" or "authenticate as one of the users from UNIX group wheel" or however the PolicyKit library is configured (see the `PolicyKit.conf(5)` manual page for details). Note that some of the screenshots below were made on a system set up to use the ThinkFinger PAM module.

The text shown in the authentication dialogs stems from the PolicyKit `.policy` XML files residing in `/usr/share/PolicyKit/policy` and is read by the authentication daemon when an applications uses the `ShowDialog()` method. Thus, what the user sees is not under application control (e.g. it's not passed from the application) which rules out a class of attacks where applications are trying to fool the user into gaining a privilege.

Authentication dialog where the user is asked to authenticate as herself:

Authentication dialog where the user is asked to authenticate as an administrative user and PolicyKit is configured to use the root password for this:

Authentication dialog where the user is asked to authenticate as an administrative user and PolicyKit is configured to use the UNIX wheel group for this:

Same authentication dialog, showing drop down box where the user can be selected:

Authentication dialog showing an Action where the privilege can be retained indefinitely:

Authentication dialog showing an Action where the privilege can be retained only for the remainer of the desktop session:

The details view detailing what Action is being asked for as well as what application is requesting the authentication: