Mini Shell
Direktori : /usr/share/dbus-1/interfaces/ |
|
Current File : //usr/share/dbus-1/interfaces/org.freedesktop.Flatpak.Authenticator.xml |
<!DOCTYPE node PUBLIC
"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<!--
Copyright (C) 2015 Red Hat, Inc.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General
Public License along with this library; if not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
Author: Alexander Larsson <alexl@redhat.com>
-->
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<!--
'org.freedesktop.Flatpak.Authenticator:
@short_description: Flatpak authenticator
An authenticator is a dbus service that flatpak talks to in
order to negotiate downloads of protected content. Each commit
in the repository has a "token-type" value (either directly or
from a default), and whenever this is non-zero flatpak assumes
it will need to do some sort of authentication to download it.
Each configured remote in the system has information about what
authenticator to use for the remote, as well as some config
options for it. The configuration contains the dbus name of the
authenticator, which is activated on demand by dbus. This allows
authenticators to be shipped with the system, or installed as
flatpaks.
The main operation that the authenticator supports is the
RequestRefToken where you pass a set of references and the
authenticator returns a HTTP bearer token (if any) to use for
each ref. Flatpak will then use the returned tokens in all its
http requests, and it is then up to the server to validate the
tokens.
The authenticator dbus calls are not regular dbus calls, but
instead long running (cancellable) object implementing the
AuthenticatorRequest interface. This is very similiar to how
org.freedesktop.portal.Request work when its used in
xdg-desktop-portal.
Most of the details in how the tokens look, are created and
validated and how the token-type is interpreted is up to the
authenticator (in combination with the actual repo server). The
system has been designed to be very generic.
The D-Bus interface for the authenticator is supposed to be
available on the given bus name at the object path
/org/freedesktop/Flatpak/Authenticator.
This documentation describes version 1 of this interface.
-->
<interface name='org.freedesktop.Flatpak.Authenticator'>
<property name="version" type="u" access="read"/>
<!--
RequestRefTokens:
@handle_token: A string that will be used as the last element of the @handle. Must be a valid
object path element. See the #org.freedesktop.Flatpak.AuthenticatorRequest documentation for
more information about the @handle.
@authenticator_options: Data from the xa.authenticator-options key in the configuration for the remote, it is up to the authenticator to interpret this how it wants.
@remote: The name of the remote we're pulling from.
@remote_uri: The uri of the remote we're pulling from.
@refs: An array of ref that flatpak wants to pull and info about each ref.
@options: An extensible dict with extra options.
@parent_window: Identifier for the application window, see <link linkend="https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#parent_window">xdg-desktop-portal docs</link> for details on its format.
@handle: Object path for the #org.freedesktop.Flatpak.AuthenticatorRequest object representing this call.
Starts a request for resolving the tokens to use for @refs from the @remote (with uri @remote_uri).
This is not a regular dbus call that blocks until the result is done, instead it creates
a org.freedesktop.Flatpak.AuthenticatorRequest object representing the ongoing operation and
returns an object path @handle to it. When the operation succeds the Response signal is emitted
on the request with a response status and a dict with details.
The @refs array elements are of type (ssia{sv}) where the items are:
<simplelist>
<member>s: The ref being pulled</member>
<member>s: The exact commit being pulled</member>
<member>i: The token-type of the commit</member>
<member>a{sv}: Extra per-ref metadata, currenlty only has summary.* fields which are copied from the summary per-commit metadata.</member>
</simplelist>
On success (response 0) the returned details should have:
<variablelist>
<varlistentry>
<term>tokens a{sas}</term>
<listitem><para>
A list of tokens (the first element of the struct), and the refs (the second).
</para></listitem>
</varlistentry>
</variablelist>
For other response types, see the #org.freedesktop.Flatpak.AuthenticatorRequest docs.
Exactly how the authenticator decides on what token to use is up to each implementation, but typically it needs to talk to
some kind of network service which in turn may need interaction such as login or entering credit card details.
This can be done in two ways:
The authenticator can use a native ui toolkit directly (as its running in the session). To make this work well the
flatpak client can (if its has a UI) pass in the @parent_window argument, allowing the authenticator to open its
dialog in a way that is correctly parented.
Alternatively, if the interaction is web-based, then rather than showing a web browser itself it can emit
the WebFlow signal on the request object, which lets the flatpak client show a webview embedded in its ui in a
way that works best with its user interface.
For simple user/password authentication (such as http basic authentication systems) there is also a BasicAuth signal
that can be used to get the user to interactively authenticate. This kind of authentication is quite limited, but
if used it can allow nice interactive authentication even in the command line case.
Currently used keys in the @options argument:
<variablelist>
<varlistentry>
<term>xa.oci-registry-uri s</term>
<listitem><para>
For OCI remotes this is extracted from the summary file and contains the uri to the OCI registry that
contains the images.
</para></listitem>
</varlistentry>
<varlistentry>
<term>no-interation b</term>
<listitem><para>
If true, the authenticator should not do any interaction (and fail instead if it needs to). This can be enabled by
clients that want to run in the background.
</para></listitem>
</varlistentry>
</variablelist>
-->
<method name="RequestRefTokens">
<arg type='s' name='handle_token' direction='in'/>
<arg type='a{sv}' name='authenticator_options' direction='in'/>
<arg type='s' name='remote' direction='in'/>
<arg type='s' name='remote_uri' direction='in'/>
<!-- This is the ref and its token-type -->
<arg type='a(ssia{sv})' name='refs' direction='in'/>
<arg type='a{sv}' name='options' direction='in'/>
<arg type='s' name='parent_window' direction='in'/>
<arg type='o' name='handle' direction='out'/>
</method>
</interface>
<!--
'org.freedesktop.Flatpak.AuthenticatorRequest:
@short_description: Ongoing authenticator request
The AuthenticatorRequest interface is used by the #org.freedesktop.Flatpak.Authenticator interface. When a
method is called, the reply includes a handle (i.e. object path)
for a AuthenticatorRequest object, which will stay alive for the duration of the
user interaction related to the method call.
The authenticator indicates that a request interaction is over by
emitting the #org.freedesktop.Flatpak.AuthenticatorRequest::Response signal on the
Request object.
The application can abort the interaction calling
org.freedesktop.Flatpak.AuthenticatorRequest.Close() on the AuthenticatorRequest object.
The object path of each request object will be of the form
/org/freedesktop/Flatpak/Authenticator/request/SENDER/TOKEN,
where SENDER is the callers unique name, with the initial ':' removed and
all '.' replaced by '_', and TOKEN is a unique token that the caller provided
with the handle_token argument. This lets applications subscribe to the
Response signal before making the initial portal call, thereby avoiding a race condition.
-->
<interface name="org.freedesktop.Flatpak.AuthenticatorRequest">
<!--
Close:
Closes the authenticator request to which this object refers and ends all
related user interaction (dialogs, webflows etc).
A Response signal with the cancelled response will be emitted if the operation
was cancelled. There is still a posibility of a race, so the operation might succeed
or fail before processing the close request, so there is no guarantee that the
operation will be cancelled.
-->
<method name="Close">
</method>
<!--
Webflow:
@uri: The uri to show
@options: An extensible dict with extra options.
Emitted by the authenticator when it needs to do web-based interaction. The
client handles this by showing the URI in a graphical web view. Typically the uri
includes information about a final redirect to a localhost uri that will happen
when the operation is finished allowing the authenticator to get the result of
the operation. This is similar to how OAUTH2 webflows typically work.
If at any point the user closes or otherwise dismisses the web view the client
should call the org.freedesktop.Flatpak.AuthenticatorRequest.Close method to
tell the authenticator that the operation is aborted.
-->
<signal name="Webflow">
<arg type="s" name="uri"/>
<arg type="a{sv}" name="options" direction="in"/>
</signal>
<!--
WebflowDone:
@options: An extensible dict with extra options.
Emitted by the authenticator when the web view is done, at this point the client
can close the WebView.
-->
<signal name="WebflowDone">
<arg type="a{sv}" name="options" direction="in"/>
</signal>
<!--
BasicAuth:
@realm: String showing what the auth is for, similar to http basic auth realm.
@options: An extensible dict with extra options.
Emitted by the authenticator when it needs to do a simple user + password authentication.
This is only useful for very simple authentication interaction, but this is still used (for
instance for http basic access authentication), and for those cases this allows a nicely
integrated UI and CLI experience.
-->
<signal name="BasicAuth">
<arg type="s" name="realm"/>
<arg type="a{sv}" name="options" direction="in"/>
</signal>
<!--
BasicAuthReply:
@user: The user
@password: The password
@options: An extensible dict with extra options.
Call to finish the request started with the BasicAuth signal.
-->
<method name="BasicAuthReply">
<arg type="s" name="user"/>
<arg type="s" name="password"/>
<arg type="a{sv}" name="options" direction="in"/>
</method>
<!--
Response:
@response: Numeric response
@results: Vardict with results. The keys and values in the vardict depend on the request.
Emitted when the user interaction for a portal request is over.
The @response indicates how the user interaction ended:
<simplelist>
<member>0: Success, the request is carried out</member>
<member>1: The user cancelled the interaction</member>
<member>2: The user interaction was ended in some other way</member>
</simplelist>
In the case of an error (response 2) @results can contain a error-message value
describing what went wrong.
-->
<signal name="Response">
<arg type="u" name="response"/>
<arg type="a{sv}" name="results"/>
</signal>
</interface>
</node>
Zerion Mini Shell 1.0