## org.freedesktop.Flatpak.Authenticator

org.freedesktop.Flatpak.Authenticator

## Methods

    RequestRefTokens (IN  s           handle_token,
                      IN  a{sv}       authenticator_options,
                      IN  s           remote,
                      IN  s           remote_uri,
                      IN  a(ssia{sv}) refs,
                      IN  a{sv}       options,
                      IN  s           parent_window,
                      OUT o           handle);

## Properties

    version  readable   u

## Description

## Method Details

### The RequestRefTokens() method

    RequestRefTokens (IN  s           handle_token,
                      IN  a{sv}       authenticator_options,
                      IN  s           remote,
                      IN  s           remote_uri,
                      IN  a(ssia{sv}) refs,
                      IN  a{sv}       options,
                      IN  s           parent_window,
                      OUT o           handle);

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 xdg-desktop-portal docs 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 succeeds 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:

s: The ref being pulled
s: The exact commit being pulled
i: The token-type of the commit
a{sv}: Extra per-ref metadata, currently only has summary.* fields which are copied from the summary per-commit metadata.

On success (response 0) the returned details should have:

tokens a{sas} | A list of tokens (the first element of the struct), and the refs (the second).

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:

xa.oci-registry-uri s | For OCI remotes this is extracted from the summary file and contains the uri to the OCI registry that contains the images.
no-interation b | 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.

`IN s `handle_token``: | A string that will be used as the last element of the `handle`. Must be a valid
`IN a{sv} `authenticator_options``: |
`IN s `remote``: |
`IN s `remote_uri``: |
`IN a(ssia{sv}) `refs``: |
`IN a{sv} `options``: |
`IN s `parent_window``: |
`OUT o `handle``: |

## Property Details

### The "version" property

    version  readable   u