Development/Tutorials/KAuth/KAuth Basics

KAuth Basics

Tutorial Series	KAuth Tutorial
Previous
What's Next	Using the caller-helper model to perform actions as root
Further Reading	None

What is KAuth

KAuth (part of kdelibs/kdecore) is an authentication framework for KDE. Just like any other components in the KDE Development Platform, it is a wrapper around lower-level tools. If you're planning to use KAuth, however, you won't have to care about what authentication system is the system you're targeting using: KAuth will take care of that on its own.

In addition, KAuth is also able to perform privilege elevation on restricted portions of code (helpers), giving the developer an efficient and easy to use pipe to communicate with them, and making them secure throughout authorization.

Concepts

There are a few concepts to understand when using the library. Much of those are carried from underlying APIs such as polkit, so if you are familiar with one of them you might as well skip this section.

An [i]action[/i] is a single task that needs authorization to be performed. Each action has an unique action identifier, which is a string in reverse domain name syntax, like [i]org.kde.this.is.an.action[/i]. For example, if the date/time control center module needs to change the date, it would need an action like "org.kde.datatime.change". Please note that each action has to refer to a single task: this allows system administrators to fine tune the policies that allow users to perform your actions, and also a more secure way of locking down the privileged actions in your application.

[i]Authorization[/i] is a particular phase where the underlying authorization framework performs the needed checks (and eventually asks the user its credentials in order to authorize him). Before any action is executed, the Authorization phase takes place. This is handled internally by KAuth: even if you are able to trigger this phase manually, most of the times you don't need to: KAuth will still execute an action only if the underlying authorization framework allows its execution.

[i]Authentication[/i] is an optional phase that takes place during authorization, if the policy for the action requests the user to input a credential to give him an explicit authorization. This phase is external and not handled by KAuth, but entirely by the underlying authorization framework. It is, however, important for you to know something about it even if KAuth has no way to hijack the Authentication phase by design.

A typical session with the authorization API is like this:
- The user want to perform some privileged task
- The application asks the system if the user is authorized.
- The system asks the user to authenticate, if needed, and reply the application.
- The application uses some system-provided mechanism to execute the helper's code as the root user. Previously, you had to set the setuid bit to do this, but we have something cool called
  "dbus activation" that doesn't require the setuid bit and is much more flexible.
- The helper code, immediately after starting, checks if the caller is authorized to do what it asks. If not the helper immediately exits!
- If the caller is authorized, the helper executes the task and exits.
- The application receives data back from the helper.

All these steps are managed by the library. Following sections will focus on how to write the helper to implement your actions and how to call the helper from the application.