Development/Tutorials/KAuth/KAuth Basics - Revision history

AnneW at 15:33, 19 July 2012

2012-07-19T15:33:04Z

Drf at 13:22, 12 February 2010

2010-02-12T13:22:53Z

Drf at 12:03, 12 February 2010

2010-02-12T12:03:46Z

Drf at 12:26, 11 February 2010

2010-02-11T12:26:12Z

Drf at 12:24, 11 February 2010

2010-02-11T12:24:55Z

Drf: Improve

2010-02-11T12:23:50Z

Improve

Drf at 16:43, 10 February 2010

2010-02-10T16:43:36Z

Drf at 16:28, 10 February 2010

2010-02-10T16:28:46Z

Drf at 16:22, 10 February 2010

2010-02-10T16:22:23Z

Drf: Creating a draft of the first KAuth tutorial

2010-02-10T16:04:11Z

Creating a draft of the first KAuth tutorial

New page

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Basics}}

{{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 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.

← Older revision		Revision as of 15:33, 19 July 2012
Line 1:		Line 1:
−	~~{{Template:I18n/Language Navigation Bar\|Development/Tutorials/KAuth/KAuth Basics}}~~	+

	{{TutorialBrowser\|		{{TutorialBrowser\|

@@ Line 60: / Line 60: @@
 == Creating Actions with KAuth ==
 To increase the level of security, authorization systems require to register the actions together with the application installation, so that the authorized actions are all known to the system administrator. This means that if you're using KAuth you probably want to register some new actions in the system.
 === The basic .actions file ===

@@ Line 25: / Line 25: @@
 === Terms and main concepts ===
 *The ''authorization system'' is an underlying framework (like polkit or Authorization Services), which KAuth interfaces with. KAuth's aim is to never make the developer know or care about the underlying auhtorization system, however in this tutorial series this concept will come up quite often to explain better how KAuth works.
-*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.
+*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 our example application needs to read a file the user has no privileges on, it would need an action like "org.kde.auth.example.read". 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.
-* An ''action namespace'' is the first part of the action identifier. In "org.kde.datatime.change", ''org.kde.datetime'' is the '''action namespace''', ''change'' is the '''action name'''. This is a very important concept when dealing with helpers and .actions files.
+* An ''action namespace'' is the first part of the action identifier. In "org.kde.auth.example.read", ''org.kde.auth.example'' is the '''action namespace''', ''read'' is the '''action name'''. This is a very important concept when dealing with helpers and .actions files.
-*''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.
+*''Authorization'' is a particular phase where the underlying authorization system 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 system allows its execution.
-*''Authentication''&nbsp;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.
+*''Authentication''&nbsp;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 system. 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&nbsp;''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.
@@ Line 83: / Line 83: @@
 **''no'': the action should be always denied, without requesting authentication
 **''auth_self'': the action will be authorized if the user will authenticate as himself
-**'auth_admin'': the action will be authorized if the user will authenticate as a system administrator
+**''auth_admin'': the action will be authorized if the user will authenticate as a system administrator
 *'''Persistence''': this field is optional and takes effect only if the authorization system supports it and '''Policy''' is either ''auth_admin'' or ''auth_self''. It defines the persistence of the explicit authorization granted by the user through authentication. It can be one of the following values:
 **''session'': the authorization persists until the user logs out

@@ Line 26: / Line 26: @@
 *The ''authorization system'' is an underlying framework (like polkit or Authorization Services), which KAuth interfaces with. KAuth's aim is to never make the developer know or care about the underlying auhtorization system, however in this tutorial series this concept will come up quite often to explain better how KAuth works.
 *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.
-* An ''action namespace'' is the first part of the action identifier. In "org.kde.datatime.change", ''org.kde.datetime'' is the '''action namespace''', ''change'' is the '''action name'''. This is a very important concept when you'll deal with helpers and .actions files.
+* An ''action namespace'' is the first part of the action identifier. In "org.kde.datatime.change", ''org.kde.datetime'' is the '''action namespace''', ''change'' is the '''action name'''. This is a very important concept when dealing with helpers and .actions files.
 *''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''&nbsp;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.

@@ Line 21: / Line 21: @@
 == 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''&nbsp;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&nbsp;''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 user wants to perform some privileged task
 *The application creates an action for the task in question.
 *The action is requested to be executed.
@@ Line 59: / Line 61: @@
 To increase the level of security, authorization systems require to register the actions together with the application installation, so that the authorized actions are all known to the system administrator. This means that if you're using KAuth you probably want to register some new actions in the system.
-This is done by creating a ''.actions'' file, which is a standard INI files containing a set of new actions. This file is translatable, and if you're developing your project in KDE SVN, scripty will take care of updating it. The file has the following format:
+=== The basic .actions file ===
   [org.kde.auth.example.action]
@@ Line 81: / Line 88: @@
 **''always'': the authorization will persist indefinitely
-Once you defined the actions in your file (you can define an unlimited number of actions in an .actions file, however you can define only actions belonging to a certain namespace, for example org.kde.auth.example.*), KAuth provides a CMake macro to register the actions in the system. From your CMakeLists.txt, supposing your file is named org.kde.auth.example.actions, you would do:
+=== The Domain field ===
   kde4_install_auth_actions(org.kde.auth.example org.kde.auth.example.actions)

@@ Line 9: / Line 9: @@
 pre=|
-next=[[Development/Tutorials/PolicyKit/Helper_HowTo|Using the caller-helper model to perform actions as root]]|
+next=[[Development/Tutorials/KAuth/KAuth_Actions|Using KAuth actions in your application]]|
 reading=None

← Older revision		Revision as of 16:43, 10 February 2010
Line 55:		Line 55:

	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.		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.
		+
		+	== Creating Actions with KAuth ==
		+	To increase the level of security, authorization systems require to register the actions together with the application installation, so that the authorized actions are all known to the system administrator. This means that if you're using KAuth you probably want to register some new actions in the system.
		+
		+	This is done by creating a ''.actions'' file, which is a standard INI files containing a set of new actions. This file is translatable, and if you're developing your project in KDE SVN, scripty will take care of updating it. The file has the following format:
		+
		+	[org.kde.auth.example.action]
		+	Name=Example action
		+	Description=The system is attempting to perform the example action
		+	Policy=auth_admin
		+	Persistence=session
		+
		+	The fields are defined as follows:
		+
		+	*'''Title''': The action identifier
		+	*'''Name''': A human readable action name
		+	*'''Description''': This message will eventually be displayed to the user during the authentication phase, if any.
		+	*'''Policy''': The default policy for this action. It can be one of the following values:
		+	**''yes'': the action should be allowed without requesting authentication
		+	**''no'': the action should be always denied, without requesting authentication
		+	**''auth_self'': the action will be authorized if the user will authenticate as himself
		+	**'auth_admin'': the action will be authorized if the user will authenticate as a system administrator
		+	*'''Persistence''': this field is optional and takes effect only if the authorization system supports it and '''Policy''' is either ''auth_admin'' or ''auth_self''. It defines the persistence of the explicit authorization granted by the user through authentication. It can be one of the following values:
		+	**''session'': the authorization persists until the user logs out
		+	**''always'': the authorization will persist indefinitely
		+
		+	Once you defined the actions in your file (you can define an unlimited number of actions in an .actions file, however you can define only actions belonging to a certain namespace, for example org.kde.auth.example.*), KAuth provides a CMake macro to register the actions in the system. From your CMakeLists.txt, supposing your file is named org.kde.auth.example.actions, you would do:
		+
		+	kde4_install_auth_actions(org.kde.auth.example org.kde.auth.example.actions)
		+
		+	This macro has the following syntax:
		+
		+	kde4_install_auth_actions(<namespace_id> <actions definition file>)
		+
		+	Where namespace_id is the namespace where you defined your actions, in this case org.kde.auth.example.

@@ Line 20: / Line 20: @@
 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 ==
+== 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''&nbsp;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.
+*''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&nbsp;''Helper''
-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:
+*An&nbsp;''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.
-*The user want to perform some privileged task
+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 application creates an action for the task in question.
-*The action is requested to be executed.
+*The user want to perform some privileged task
-*The following steps are handed internally, either by KAuth or the underlying authorization system.
+*The application creates an action for the task in question.
-*'''Authorization phase begins'''
+*The action is requested to be executed.
-*The system detects that the user needs to authenticate to authorize the action.
+*The following steps are handed internally, either by KAuth or the underlying authorization system.
 *'''Authentication phase begins'''
-The user is requested to input his password, swipe his finger, press a button...<br>
+*The user is requested to input his password, swipe his finger, press a button...
 *'''Authentication phase ends'''
-**Otherwise, the system grants an explicit authorization to the user
+*If authentication was unsuccessful, the action is rejected.
 *'''Authorization phase ends'''
-If authorization was unsuccessful, the action is rejected.
+*If authorization was unsuccessful, the action is rejected
-*Otherwise, the action is executed<br>
+*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.

@@ Line 1: / Line 1: @@
 {{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Basics}}
 {{TutorialBrowser|
@@ Line 12: / Line 12: @@
 reading=None
 }}
-== What is KAuth ==
+== 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.
+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.
-== Concepts==
+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.
-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.
+== Concepts ==
-[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.
+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.
-[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.
+*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.
- A typical session with the authorization API is like this:
+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 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.
+*The user want to perform some privileged task