GSignondPlugin: gsignond Reference Manual

GSignondPlugin

GSignondPlugin — an interface for implementing GLib-based authentication plugins

Functions

void	gsignond_plugin_cancel ()
void	gsignond_plugin_request_initial ()
void	gsignond_plugin_request ()
void	gsignond_plugin_user_action_finished ()
void	gsignond_plugin_refresh ()
void	gsignond_plugin_response ()
void	gsignond_plugin_response_final ()
void	gsignond_plugin_store ()
void	gsignond_plugin_error ()
void	gsignond_plugin_user_action_required ()
void	gsignond_plugin_refreshed ()
void	gsignond_plugin_status_changed ()

Types and Values

enum	GSignondPluginState

Includes

#include <gsignond/gsignond-plugin-interface.h>

Description

GSignondPlugin is an interface for implementing GLib-based authentication plugins.

When creating a plugin, write the GObject boilerplate code as usual, but

a) declare the type as follows:

1
2
3

G_TYPE_OBJECT,
G_IMPLEMENT_INTERFACE (GSIGNOND_TYPE_PLUGIN,
                       gsignond_plugin_interface_init));

b) implement gsignond_plugin_interface_init as follows:

gsignond_plugin_interface_init (GSignondPluginInterface *iface)
{
    iface->cancel = gsignond_password_plugin_cancel;
    iface->request_initial = gsignond_password_plugin_request_initial;
    iface->request = gsignond_password_plugin_request;
    iface->user_action_finished = gsignond_password_plugin_user_action_finished;
    iface->refresh = gsignond_password_plugin_refresh;
}

where the gsignond_password_plugin_cancel etc. are specific implementations of plugin interface methods that every plugin must provide (see below for when and how they're used by the daemon).

c) override “type” and “mechanisms” property implementations in the plugin class constructor like this:

gsignond_password_plugin_class_init (GSignondPasswordPluginClass *klass)
{
    GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
    
    gobject_class->set_property = gsignond_password_plugin_set_property;
    gobject_class->get_property = gsignond_password_plugin_get_property;
    
    g_object_class_override_property (gobject_class, PROP_TYPE, "type");
    g_object_class_override_property (gobject_class, PROP_MECHANISMS, 
                                      "mechanisms");
}

(naturally, plugin's property setter should ignore attempts to set these properties, and plugin's property getter should provide their values when asked)

The plugin API

Plugins implement authentication sessions which are controlled through the plugin API. Authentication sessions follow one another so there is only one active session at a time.

The plugin API is a set of methods and signals that should be used in a specific sequence:

successful authentication session begins with gsignond_plugin_request_initial() and ends with the plugin issuing a “response-final” signal
at any point the application can cancel an active session with gsignond_plugin_cancel()
at any point the plugin can cancel an active session by issuing “error” signal, which also provides some details about the cancellation reason.
if a session is active, and the plugin has an intermediate response or needs additional information, it issues “response” signal, which the application should respond to with gsignond_plugin_request() method. This can happen more than once.
if the plugin needs to launch UI interaction with the user, it's issuing “user-action-required” signal, which the application should follow up with gsignond_plugin_user_action_finished() method. This can happen more than once as well.
if, during an active UI session, the application needs a UI refresh (for example, to fetch a new captcha image), it's requested from the plugin with gsignond_plugin_refresh() method, followed by the plugin's response via “refreshed” signal. This can happen more than once.
changes in plugin state are reported through “status-changed” signal.
if the plugin needs to store information in persistent storage, it issues “store” signal. Later, that same information is provided as a parameter to gsignond_plugin_request_initial().

Example plugins

See example plugin implementation here:

https://gitlab.com/accounts-sso/gsignond/tree/master/src/plugins.

For examples of out of tree plugins, you can have a look at SASL or OAuth plugin implementations:

https://gitlab.com/accounts-sso/gsignond-plugin-sasl/tree/master. https://gitlab.com/accounts-sso/gsignond-plugin-oa/tree/master.

Functions

gsignond_plugin_cancel ()

void
gsignond_plugin_cancel (GSignondPlugin *self);

This method cancels an ongoing authentication session. The plugin implementations should issue a “error” signal with GSIGNOND_ERROR_SESSION_CANCELED error, and prepare for a new authentication session.

Parameters

self

plugin instance

gsignond_plugin_request_initial ()

void
gsignond_plugin_request_initial (GSignondPlugin *self,
                                 GSignondSessionData *session_data,
                                 GSignondDictionary *identity_method_cache,
                                 const gchar *mechanism);

This method starts a new authentication session.

Parameters

self	plugin instance
session_data	parameters for the session
identity_method_cache	data from persistent storage, saved previously via “store” signal
mechanism	mechanism to use for the authentication

gsignond_plugin_request ()

void
gsignond_plugin_request (GSignondPlugin *self,
                         GSignondSessionData *session_data);

This method provides the plugin with additional parameters for the session after the plugin has asked for it via “response” signal.

Parameters

self	plugin instance
session_data	additional parameters for the session

gsignond_plugin_user_action_finished ()

void
gsignond_plugin_user_action_finished (GSignondPlugin *self,
                                      GSignondSignonuiData *ui_data);

This method provides the plugin with the results of UI interaction after the plugin has asked for it via “user-action-required” signal.

Parameters

self	plugin instance
ui_data	results of UI interaction

gsignond_plugin_refresh ()

void
gsignond_plugin_refresh (GSignondPlugin *self,
                         GSignondSignonuiData *ui_data);

This method asks the plugin to refresh the UI. The plugin responds with “refreshed” signal.

Parameters

self	plugin instance
ui_data	UI refresh parameters

gsignond_plugin_response ()

void
gsignond_plugin_response (GSignondPlugin *self,
                          GSignondSessionData *session_data);

Plugin implementations should use this to issue “response” signal. This method should not be used otherwise.

Parameters

self	plugin instance
session_data	session data

gsignond_plugin_response_final ()

void
gsignond_plugin_response_final (GSignondPlugin *self,
                                GSignondSessionData *session_data);

Plugin implementations should use this to issue “response-final” signal. This method should not be used otherwise.

Parameters

self	plugin instance
session_data	session data

gsignond_plugin_store ()

void
gsignond_plugin_store (GSignondPlugin *self,
                       GSignondDictionary *identity_method_cache);

Plugin implementations should use this to issue “store” signal. This method should not be used otherwise.

Parameters

self	plugin instance
identity_method_cache	data to store

gsignond_plugin_error ()

void
gsignond_plugin_error (GSignondPlugin *self,
                       GError *error);

Plugin implementations should use this to issue “error” signal. This method should not be used otherwise.

Parameters

self	plugin instance
error	the error

gsignond_plugin_user_action_required ()

void
gsignond_plugin_user_action_required (GSignondPlugin *self,
                                      GSignondSignonuiData *ui_data);

Plugin implementations should use this to issue “user-action-required” signal. This method should not be used otherwise.

Parameters

self	plugin instance
ui_data	UI data

gsignond_plugin_refreshed ()

void
gsignond_plugin_refreshed (GSignondPlugin *self,
                           GSignondSignonuiData *ui_data);

Plugin implementations should use this to issue “refreshed” signal. This method should not be used otherwise.

Parameters

self	plugin instance
ui_data	UI data

gsignond_plugin_status_changed ()

void
gsignond_plugin_status_changed (GSignondPlugin *self,
                                GSignondPluginState state,
                                const gchar *message);

Plugin implementations should use this to issue “status-changed” signal. This method should not be used otherwise.

Parameters

self	plugin instance
state	the new state
message	the message

Types and Values

enum GSignondPluginState

The plugin provides state updates by emitting “status-changed” signal with this enum and a string describing what happened.

Members

GSIGNOND_PLUGIN_STATE_NONE	State unknown
GSIGNOND_PLUGIN_STATE_RESOLVING	Resolving remote server host name
GSIGNOND_PLUGIN_STATE_CONNECTING	Connecting to remote server
GSIGNOND_PLUGIN_STATE_SENDING_DATA	Sending data to remote server
GSIGNOND_PLUGIN_STATE_WAITING	Waiting for reply from remote server
GSIGNOND_PLUGIN_STATE_USER_PENDING	Waiting for response from user
GSIGNOND_PLUGIN_STATE_REFRESHING	Refreshing ui request
GSIGNOND_PLUGIN_STATE_PROCESS_PENDING	Request has been queued
GSIGNOND_PLUGIN_STATE_STARTED	Request has been dequeued
GSIGNOND_PLUGIN_STATE_CANCELING	Canceling current process
GSIGNOND_PLUGIN_STATE_DONE	Process is finished
GSIGNOND_PLUGIN_STATE_HOLDING	Holding long non-expired token