GSignondPlugin

GSignondPlugin — an interface for implementing GLib-based authentication plugins

Functions

Properties

GStrv mechanisms Read
gchar * type Read

Signals

Types and Values

Object Hierarchy

    GInterface
    ╰── GSignondPlugin

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:

                        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:

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

 

Property Details

The “mechanisms” property

  “mechanisms”               GStrv

This property holds a list of authentication mechanisms that the plugin implements, all specified within the authentication method. For example, OAuth plugin could implement "oauth1" and "oauth2" mechanisms.

Flags: Read


The “type” property

  “type”                     gchar *

This property holds a plugin type, or authentication method it implements (for example "oauth" or "sasl").

Flags: Read

Default value: "none"

Signal Details

The “error” signal

void
user_function (GSignondPlugin *plugin,
               GError         *error,
               gpointer        user_data)

This signal is issued by the plugin when an error has occured, or the plugin otherwise has a reason to cancel the authentication session. The error should be specified according to

GSignond errors.

Parameters

plugin

the plugin which emitted the signal

 

error

the details of the error

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “refreshed” signal

void
user_function (GSignondPlugin       *plugin,
               GSignondSignonuiData *ui_data,
               gpointer              user_data)

This signal is issued by the plugin when the UI interaction is ongoing and the UI needs to be refreshed. This can be used for example to update captcha image in the UI.

Parameters

plugin

the plugin which emitted the signal

 

ui_data

parameters for UI refresh

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “response” signal

void
user_function (GSignondPlugin      *plugin,
               GSignondSessionData *session_data,
               gpointer             user_data)

This signal is issued by the plugin when it wants to provide an intermediate response to the application or needs additional information from the application.

After issuing this signal the plugin expects a gsignond_plugin_response() call.

Parameters

plugin

the plugin which emitted the signal

 

session_data

a GSignondSessionData containing signal parameters

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “response-final” signal

void
user_function (GSignondPlugin      *plugin,
               GSignondSessionData *session_data,
               gpointer             user_data)

This signal is issued by the plugin when it has completed the authentication sequence and is used to provide the final response to the application.

After issuing this signal the plugin is idle and is ready for a new authentication session.

Parameters

plugin

the plugin which emitted the signal

 

session_data

a GSignondSessionData containing signal parameters

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “status-changed” signal

void
user_function (GSignondPlugin     *plugin,
               GSignondPluginState state,
               gchar              *message,
               gpointer            user_data)

This signal is issued by the plugin when plugin state has changed. This can be used by applications to report authentication progress.

Parameters

plugin

the plugin which emitted the signal

 

state

the plugin state

 

message

the message that accompanies the state change

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “store” signal

void
user_function (GSignondPlugin     *plugin,
               GSignondDictionary *data,
               gpointer            user_data)

This signal is issued by the plugin when it has data to store in persistant storage. The same data would later be provided to plugin via gsignond_plugin_request_initial identity_method_cache parameter.

Parameters

plugin

the plugin which emitted the signal

 

data

a GSignondDictionary containing data to place in persistent storage

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “user-action-required” signal

void
user_function (GSignondPlugin       *plugin,
               GSignondSignonuiData *ui_data,
               gpointer              user_data)

This signal is issued by the plugin when it needs a UI interaction with the user to happen. When the interaction is complete, gsignond_plugin_user_action_finished() should be issued.

Parameters

plugin

the plugin which emitted the signal

 

ui_data

parameters for UI interaction

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First