SignonAuthSession: libgsignon-glib Reference Manual

SignonAuthSession

SignonAuthSession — the authentication session object

Functions

SignonAuthSession *	signon_auth_session_new ()
SignonAuthSession *	signon_auth_session_new_for_identity ()
const gchar *	signon_auth_session_get_method ()
void	(*SignonAuthSessionQueryAvailableMechanismsCb) ()
void	signon_auth_session_query_available_mechanisms ()
void	(*SignonAuthSessionProcessCb) ()
void	signon_auth_session_process ()
void	signon_auth_session_process_async ()
GVariant *	signon_auth_session_process_finish ()
void	signon_auth_session_cancel ()

Properties

SignonIdentity *

identity

Read / Write / Construct Only

Signals

void

state-changed

Action

Types and Values

#define	SIGNON_SESSION_DATA_USERNAME
#define	SIGNON_SESSION_DATA_SECRET
#define	SIGNON_SESSION_DATA_REALM
#define	SIGNON_SESSION_DATA_PROXY
enum	SignonSessionDataUiPolicy
enum	SignonAuthSessionState
#define	SIGNON_SESSION_DATA_UI_POLICY
#define	SIGNON_SESSION_DATA_CAPTION
#define	SIGNON_SESSION_DATA_TIMEOUT
#define	SIGNON_SESSION_DATA_WINDOW_ID
#define	SIGNON_SESSION_DATA_RENEW_TOKEN
struct	SignonAuthSession
struct	SignonAuthSessionClass

Object Hierarchy

    GObject
    ╰── SignonAuthSession

Description

The SignonAuthSession object is responsible for handling the client authentication. SignonAuthSession objects should be created from existing identities (via signon_identity_create_session() or by passing a non-NULL identity to signon_auth_session_new()).

Functions

signon_auth_session_new ()

SignonAuthSession *
signon_auth_session_new (gint id,
                         const gchar *method_name,
                         GError **err);

Creates a new SignonAuthSession, which can be used to authenticate using the specified method.

Parameters

id	the id of the SignonIdentity to be used. Can be 0, if this session is not bound to any stored identity.
method_name	the name of the authentication method to be used.
err	a pointer to a location which will contain the error, in case this function fails.

Returns

a new SignonAuthSession.

signon_auth_session_new_for_identity ()

SignonAuthSession *
signon_auth_session_new_for_identity (SignonIdentity *identity,
                                      const gchar *method_name,
                                      GError **err);

Creates a new SignonAuthSession, which can be used to authenticate using the specified method.

Parameters

identity	SignonIdentity parent object.
method_name	the name of the authentication method to be used.
err	a pointer to a location which will contain the error, in case this function fails.

Returns

a new SignonAuthSession.

signon_auth_session_get_method ()

const gchar *
signon_auth_session_get_method (SignonAuthSession *self);

Get the current authentication method.

Parameters

self

the SignonAuthSession.

Returns

the authentication method being used, or NULL on failure.

SignonAuthSessionQueryAvailableMechanismsCb ()

void
(*SignonAuthSessionQueryAvailableMechanismsCb)
                               (SignonAuthSession *self,
                                gchar **mechanisms,
                                const GError *error,
                                gpointer user_data);

Callback to be passed to signon_auth_session_query_available_mechanisms().

Parameters

self	the SignonAuthSession.
mechanisms	list of available mechanisms.	[transfer full][type GStrv]
error	a GError if an error occurred, `NULL` otherwise.
user_data	the user data that was passed when installing this callback.

signon_auth_session_query_available_mechanisms ()

void
signon_auth_session_query_available_mechanisms
                               (SignonAuthSession *self,
                                const gchar **wanted_mechanisms,
                                SignonAuthSessionQueryAvailableMechanismsCb cb,
                                gpointer user_data);

signon_auth_session_query_available_mechanisms is deprecated and should not be used in newly-written code.

Queries the mechanisms available for this authentication session. The result will be the intersection between wanted_mechanisms and the mechanisms supported by the authentication plugin (and allowed by the SignonIdentity that this session belongs to).

Parameters

self	the SignonAuthSession.
wanted_mechanisms	a `NULL`-terminated list of mechanisms supported by the client.
cb	a callback which will be called with the result.	[scope async]
user_data	user data to be passed to the callback.

SignonAuthSessionProcessCb ()

void
(*SignonAuthSessionProcessCb) (SignonAuthSession *self,
                               GHashTable *session_data,
                               const GError *error,
                               gpointer user_data);

SignonAuthSessionProcessCb is deprecated and should not be used in newly-written code.

This callback is invoked when the authentication plugin delivers the result of the signon_auth_session_process() operation.

Parameters

self	the SignonAuthSession.
session_data	a dictionary with the response.	[transfer full][element-type utf8 GValue]
error	a GError if an error occurred, `NULL` otherwise.
user_data	the user data that was passed when installing this callback.

signon_auth_session_process ()

void
signon_auth_session_process (SignonAuthSession *self,
                             GHashTable *session_data,
                             const gchar *mechanism,
                             SignonAuthSessionProcessCb cb,
                             gpointer user_data);

signon_auth_session_process has been deprecated since version 1.8 and should not be used in newly-written code.

Use signon_auth_session_process_async() instead.

Performs one step of the authentication process. If the SignonIdentity that this session belongs to contains a username and a password, they will be also passed to the authentication plugin, otherwise they should be set directly in session_data . session_data should be used to add additional authentication parameters to the session, or to override the parameters otherwise taken from the identity.

Parameters

self	the SignonAuthSession.
session_data	a dictionary of parameters.	[transfer none][element-type utf8 GValue]
mechanism	the authentication mechanism to be used.
cb	a callback which will be called with the result.	[scope async]
user_data	user data to be passed to the callback.

signon_auth_session_process_async ()

void
signon_auth_session_process_async (SignonAuthSession *self,
                                   GVariant *session_data,
                                   const gchar *mechanism,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Performs one step of the authentication process. session_data should be used to add additional authentication parameters to the session.

What specific parameters should be used can be found from authentication plugins' documentation (look for parameters that are expected in gsignond_plugin_request_initial() for the first step, and parameters that are expected in gsignond_plugin_request() for the subsequent steps). See, for example, GSignondPasswordPlugin and GSignondDigestPlugin.

If the SignonIdentity that this session belongs to contains a username and a password, the daemon will pass them to the authentication plugin, otherwise they should be set directly in session_data . The daemon also passes a list of identity's allowed realms to the plugin, and they cannot be overriden.

Parameters

self	the SignonAuthSession.
session_data	a dictionary of parameters.	[transfer full]
mechanism	the authentication mechanism to be used.
cancellable	optional GCancellable object, `NULL` to ignore.	[allow-none]
callback	a callback which will be called when the authentication reply is available.	[scope async]
user_data	user data to be passed to the callback.

Since: 1.8

signon_auth_session_process_finish ()

GVariant *
signon_auth_session_process_finish (SignonAuthSession *self,
                                    GAsyncResult *res,
                                    GError **error);

Collect the result of the signon_auth_session_process_async() operation.

Parameters

self	the SignonAuthSession.
res	A GAsyncResult obtained from the GAsyncReadyCallback passed to `signon_auth_session_process_async()`.
error	return location for error, or `NULL`.

Returns

a GVariant of type G_VARIANT_TYPE_VARDICT containing the authentication reply. As with signon_auth_session_process_async(), specific parameters contained in the GVariant can be found from plugins' documentation: “response-final” for the final response, and “response” for the intermediate responses. See, for example, GSignondPasswordPlugin and GSignondDigestPlugin.

Since: 1.8

signon_auth_session_cancel ()

void
signon_auth_session_cancel (SignonAuthSession *self);

Cancel the authentication session.

Parameters

self

the SignonAuthSession.

Types and Values

SIGNON_SESSION_DATA_USERNAME

#define SIGNON_SESSION_DATA_USERNAME      "UserName"

Username.

SIGNON_SESSION_DATA_SECRET

#define SIGNON_SESSION_DATA_SECRET        "Secret"

Secret.

SIGNON_SESSION_DATA_REALM

#define SIGNON_SESSION_DATA_REALM         "Realm"

Realm.

SIGNON_SESSION_DATA_PROXY

#define SIGNON_SESSION_DATA_PROXY         "NetworkProxy"

Proxy.

enum SignonSessionDataUiPolicy

UI policy for the signon process, passed to the UI plugin.

Members

SIGNON_POLICY_DEFAULT	The plugin can decide when to show UI.
SIGNON_POLICY_REQUEST_PASSWORD	Force the user to enter the password.
SIGNON_POLICY_NO_USER_INTERACTION	No UI elements will be shown to the user.
SIGNON_POLICY_VALIDATION	UI elements can be shown to the user only when CAPTCHA-like security measures are required.

enum SignonAuthSessionState

State change signals emitted as the request processing proceeds.

Members

SIGNON_AUTH_SESSION_STATE_NOT_STARTED	No message.
SIGNON_AUTH_SESSION_STATE_RESOLVING_HOST	Resolving remote server host name.
SIGNON_AUTH_SESSION_STATE_CONNECTING	Connecting to remote server.
SIGNON_AUTH_SESSION_STATE_SENDING_DATA	Sending data to remote server.
SIGNON_AUTH_SESSION_STATE_WAITING_REPLY	Waiting reply from remote server.
SIGNON_AUTH_SESSION_STATE_USER_PENDING	Waiting response from user.
SIGNON_AUTH_SESSION_STATE_UI_REFRESHING	Refreshing ui request.
SIGNON_AUTH_SESSION_STATE_PROCESS_PENDING	Waiting another process to start.
SIGNON_AUTH_SESSION_STATE_STARTED	Authentication session is started.
SIGNON_AUTH_SESSION_STATE_PROCESS_CANCELING	Canceling.current process.
SIGNON_AUTH_SESSION_STATE_PROCESS_DONE	Authentication completed.
SIGNON_AUTH_SESSION_STATE_CUSTOM	Custom message.
SIGNON_AUTH_SESSION_STATE_LAST	Indicator for last item.

SIGNON_SESSION_DATA_UI_POLICY

#define SIGNON_SESSION_DATA_UI_POLICY     "UiPolicy"

Policy for the signon process.

Parameters

see_also

SignonSessionDataUiPolicy

SIGNON_SESSION_DATA_CAPTION

#define SIGNON_SESSION_DATA_CAPTION       "Caption"

Caption for the UI dialog.

SIGNON_SESSION_DATA_TIMEOUT

#define SIGNON_SESSION_DATA_TIMEOUT       "NetworkTimeout"

Network timeout, in milliseconds (uint32).

SIGNON_SESSION_DATA_WINDOW_ID

#define SIGNON_SESSION_DATA_WINDOW_ID     "WindowId"

Platform-specific window id (for dialog transiency) - uint32.

SIGNON_SESSION_DATA_RENEW_TOKEN

#define SIGNON_SESSION_DATA_RENEW_TOKEN   "RenewToken"

Requests the signon plugin to obtain a new token (boolean).

struct SignonAuthSession

struct SignonAuthSession;

Opaque struct. Use the accessor functions below.

struct SignonAuthSessionClass

struct SignonAuthSessionClass {
    GObjectClass parent;
};

Opaque struct. Use the accessor functions below.

Members

GObjectClass parent;

reference to the parent class

Property Details

The `“identity”` property

  “identity”                 SignonIdentity *

Identity Object construct parameter.

Flags: Read / Write / Construct Only

Signal Details

The `“state-changed”` signal

void
user_function (SignonAuthSession *auth_session,
               gint               state,
               gchar             *message,
               gpointer           user_data)

Emitted when the state of the SignonAuthSession changes. The state change is initiated by GSignondPlugin via “status-changed” signal.

Parameters

auth_session	the SignonAuthSession
state	the current state of the SignonAuthSession
message	the message associated with the state change
user_data	user data set when the signal handler was connected.

Flags: Action