File Content: 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> Submit