How does this work?
When you start your KDE session, KDM creates a PolicyKit instance. Your application can ask this instance for authorization. For example, an application that needs to set the machine clock can run *safely* as a normal user. When the user wants to set a new time, it calls a helper application (which should be D-Bus-activated and runs as root). This helper application should check PolicyKit if the caller application is able to do the requested action. If so, the helper application performs the actual action and reports its status. If the user cannot perform the action, the helper replies "no auth". The original application then calls PolicyKit and asks to get an authorization to change the clock action. Now PolicyKit calls PolicyKit-KDE. This opens an authentication dialog, completely in KDE's look-n-feel.
If the authentication was successful, the caller application can now ask the helper again, which will look again at PolicyKit. This time PolicyKit will say the application is trusted and the time can be changed.
Apart from the authentication user interface, we also have a manager to manage the actions and grant explicit rights for some users.
To help interested developers to integrate this powerful tool into their applications we are planning to create a library for KDE 4.3 and to write a TechBase page.