|
|
| (12 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| {{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Basics}}
| | This tutorial was moved to https://develop.kde.org/docs/features/kauth/ |
| | |
| {{TutorialBrowser|
| |
| | |
| series=KAuth Tutorial|
| |
| | |
| name=KAuth Basics|
| |
| | |
| pre=|
| |
| | |
| next=[[Development/Tutorials/PolicyKit/Helper_HowTo|Using the caller-helper model to perform actions as root]]|
| |
| | |
| 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 KAuth. 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 ''action'' 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 ''org.kde.this.is.an.action''. 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.
| |
| *''Authorization'' 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.
| |
| *''Authentication'' 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.
| |
| *''Execution'' happens '''only''' if the Authorization was successful: the execution might consist in a simple confirmation of the successful authorization, or eventually in the execution of a function in an helper.
| |
| | |
| *An ''Helper ''is a separate application running as a privileged user (usually root), which is called upon execution if your action was attached to an helper. KAuth uses a completely transparent approach: IPC between your application and the helper itself is handled internally through an extremely simple API, and you won't even know that the helper is a separate application: spawning, killing and all the process handling is handled by KAuth.
| |
| | |
| Supposing that you want to use KAuth to perform a privileged operation and the action you are considering requires the user to authenticate (which is the most common use case of KAuth), the break down of phases would be:
| |
| | |
| *The user want to perform some privileged task
| |
| *The application creates an action for the task in question.
| |
| *The action is requested to be executed.
| |
| *The following steps are handed internally, either by KAuth or the underlying authorization system.
| |
| *'''Authorization phase begins'''
| |
| *The system detects that the user needs to authenticate to authorize the action.
| |
| *'''Authentication phase begins'''
| |
| *The user is requested to input his password, swipe his finger, press a button...
| |
| *'''Authentication phase ends'''
| |
| *If authentication was unsuccessful, the action is rejected.
| |
| *Otherwise, the system grants an explicit authorization to the user
| |
| *'''Authorization phase ends'''
| |
| *If authorization was unsuccessful, the action is rejected
| |
| *Otherwise, the action is executed
| |
| *'''Execution phase begins'''
| |
| *A separate application is spawned by root, and the requested portion of code is executed.
| |
| *The helper code, immediately after starting, checks the authorization again to improve security, and also because some authorization systems delay the authorization phase in the beginning of the execution phase. If the helper is not authorized, the execution is aborted.
| |
| *If the caller is authorized, the helper executes the task
| |
| *'''Execution phase ends'''
| |
| *The application receives the result of the execution from the helper
| |
| | |
| This is how, concept-proof, KAuth works. However, please note that in your implementation you will have to deal with the pre-authorization phase only, since everything else is handled internally.
| |
