SignonIdentity: libgsignon-glib Reference Manual

SignonIdentity

SignonIdentity — client side presentation of a credential.

Functions

void	(*SignonIdentityVoidCb) ()
SignonIdentity *	signon_identity_new_from_db ()
SignonIdentity *	signon_identity_new ()
SignonIdentity *	signon_identity_new_with_context_from_db ()
SignonIdentity *	signon_identity_new_with_context ()
const GError *	signon_identity_get_last_error ()
SignonAuthSession *	signon_identity_create_session ()
void	(*SignonIdentityStoreCredentialsCb) ()
void	signon_identity_store_credentials_with_info ()
void	signon_identity_store_credentials_with_args ()
void	(*SignonIdentityVerifyCb) ()
void	signon_identity_verify_user ()
void	(*SignonIdentityInfoCb) ()
void	signon_identity_query_info ()
void	signon_identity_remove ()
void	signon_identity_request_credentials_update ()
void	signon_identity_signout ()
void	signon_identity_add_reference ()
void	signon_identity_remove_reference ()
void	(*SignonIdentitySessionReadyCb) ()
void	signon_identity_get_auth_session ()

Properties

gchar *	app-ctx	Read / Write
guint	id	Read / Write

Signals

void	removed	No Hooks
void	signout	No Hooks

Types and Values

typedef	SignonIdentityRemovedCb
typedef	SignonIdentityCredentialsUpdatedCb
typedef	SignonIdentitySignedOutCb
typedef	SignonIdentityReferenceAddedCb
typedef	SignonIdentityReferenceRemovedCb

Object Hierarchy

    GObject
    ╰── SignonIdentity

Description

The SignonIdentity objects represent identities and provide operations that can be performed on them such as identity creation, removal, starting an authentication session, and so on.

Identities can also be stored and retrieved from a gSSO database, in which case they also contain a number of properties that can be retrieved using signon_identity_query_info() and are represented via SignonIdentityInfo. Such identities are identified by a numeric id number and they are subject to access control.

Operations on an identity

a new identity can be created with signon_identity_new() or signon_identity_new_with_context(). This operation does not store the identity to the database, the identity is not visible to other applications, and accordingly it is not subject to access control.
an authentication session can be started from an identity using signon_identity_create_session() or signon_auth_session_new(). If the identity has been retrieved from a database, only the authentication methods listed in associated SignonIdentityInfo are allowed to be used.
identites stored in a database can be enumerated using signon_auth_service_query_identities(). Only the identites owned by the requesting application are returned.
identities stored in a database can be retrieved using signon_identity_new_from_db() or signon_identity_new_with_context_from_db(), subject to access control (an application performing that operation has to be either the identity's owner, or it has to be on the ACL list).
newly created identities can be stored to the database, and identities already in the database can be updated using signon_identity_store_credentials_with_info() (with SignonIdentityInfo) or signon_identity_store_credentials_with_args() (with separate arguments that together form the contents of SignonIdentityInfo). Only the owners can update identites.
identites in the database can be removed by their owners using signon_identity_remove().
identity owners can request to close all authentication sessions and remove all secrets and tokens using signon_identity_signout().

Data fields in SignonIdentityInfo

These are the data fields that are stored into the database as a part of an identity record using signon_identity_store_credentials_with_args() or signon_identity_store_credentials_with_info() and can be retrieved using signon_identity_query_info() or signon_auth_service_query_identities():

Caption is a display name for the identity, presented to the user. Default value is an empty caption.
Realms is a list of realms that the identity can be used in. Interpretation of this field is up to the method. Typically it is a list of internet domains allowed for an authentication request. Default value is an empty list.
Type is a SignonIdentityType. Interpretation of this field is up to the application; gSSO does not use it. Default value is SIGNON_IDENTITY_TYPE_OTHER
Owner is a SignonSecurityContext object, which specifies the identity owner. Owners are allowed to perform all of the operations on the identity specified above. By default an identity's owner is determined by gSSO daemon using system services for the system context, and a string supplied in signon_identity_new_with_context() for the application context.
ACL is a list of SignonSecurityContext objects, that specifies applications that can access the identity to perform authentication sessions. They're not allowed to make any changes to the identity. Default value is an empty list, and depending on how gSSO is configured it's also possible to provide a list with a wildcard item to relax the access control restriction (see SignonSecurityContext).
Methods is a GHashTable containing method names as keys, and lists of allowed mechanisms as values (also, a special value "*" means that any mechanism is allowed). Only those methods and mechanisms that are in the table are allowed to be used in authentication sessions. Default is an empty list.
Id is a numeric identification of the identity record in the database. The application cannot set this, as it's determined by the daemon.
Username is used to provide a username to authentication plugins after issuing signon_auth_session_process_async(). Applications can override this by providing a username explicitly in the session_data parameter to that function. By default there is no username.
Secret is used in the same way as username, but it is write-only (cannot be retrieved from a SignonIdentityInfo). It is also possible to prevent secret from being stored in the database.

Functions

SignonIdentityVoidCb ()

void
(*SignonIdentityVoidCb) (SignonIdentity *self,
                         const GError *error,
                         gpointer user_data);

Generic callback to be passed to several SignonIdentity methods.

Parameters

self	the SignonIdentity.
error	a GError if an error occurred, or `NULL` otherwise.
user_data	the user data that was passed when installing this callback.

signon_identity_new_from_db ()

SignonIdentity *
signon_identity_new_from_db (guint32 id);

Construct an identity object associated with an existing identity record. This is essentially equivalent to calling signon_identity_new_with_context_from_db() and passing NULL as the application context.

Applications can determine the id either by enumerating the identities with signon_auth_service_query_identities() (if they're the owner of the identity) or via other means (such as the system's accounts service, or an application configuration).

Parameters

identity ID.

Returns

an instance of a SignonIdentity.

signon_identity_new ()

SignonIdentity *
signon_identity_new ();

Construct a new, empty, identity object. This is essentially equivalent to calling signon_identity_new_with_context() and passing NULL as the application context.

Returns

an instance of an SignonIdentity.

signon_identity_new_with_context_from_db ()

SignonIdentity *
signon_identity_new_with_context_from_db
                               (guint32 id,
                                const gchar *application_context);

Construct an identity object associated with an existing identity record. See SignonSecurityContext for a discussion of application_context contents. Together with the system context it is used to determine by the gSSO daemon if the application can access the identity (the application needs to be either the identity's owner or to be present on the ACL).

Parameters

id	identity ID.
application_context	application security context, can be `NULL`.

Returns

an instance of a SignonIdentity.

signon_identity_new_with_context ()

SignonIdentity *
signon_identity_new_with_context (const gchar *application_context);

Construct a new, empty, identity object. See SignonSecurityContext for a discussion of application_context contents. application_context is used to set the identity's owner if the identity is stored to the database with signon_identity_store_credentials_with_args() or signon_identity_store_credentials_with_info().

Parameters

application_context

application security context, can be NULL.

Returns

an instance of an SignonIdentity.

signon_identity_get_last_error ()

const GError *
signon_identity_get_last_error (SignonIdentity *identity);

Get the most recent error that occurred on identity .

Parameters

identity

the SignonIdentity.

Returns

a GError containing the most recent error, or NULL on failure.

signon_identity_create_session ()

SignonAuthSession *
signon_identity_create_session (SignonIdentity *self,
                                const gchar *method,
                                GError **error);

Creates an authentication session for this identity. If the identity has been retrieved from the database, the authentication method must be one of those listed in signon_identity_info_get_methods(), otherwise it can be any method supported by gSSO.

Parameters

self	the SignonIdentity.
method	authentication method.
error	pointer to a location which will receive the error, if any.

Returns

a new SignonAuthSession.

[transfer full]

SignonIdentityStoreCredentialsCb ()

void
(*SignonIdentityStoreCredentialsCb) (SignonIdentity *self,
                                     guint32 id,
                                     const GError *error,
                                     gpointer user_data);

Callback to be passed to signon_identity_store_credentials_with_args() or signon_identity_store_credentials_with_info().

Parameters

self	the SignonIdentity.
id	the numeric ID of the identity in the database.
error	a GError if an error occurred, or `NULL` otherwise.
user_data	the user data that was passed when installing this callback.

signon_identity_store_credentials_with_info ()

void
signon_identity_store_credentials_with_info
                               (SignonIdentity *self,
                                const SignonIdentityInfo *info,
                                SignonIdentityStoreCredentialsCb cb,
                                gpointer user_data);

Stores the data contained in info into the identity record in the database. See above for the detailed discussion of the meaning of various fields and their defaults.

Parameters

self	the SignonIdentity.
info	the SignonIdentityInfo data to store.
cb	callback.	[scope async]
user_data	user_data.	[closure]

signon_identity_store_credentials_with_args ()

void
signon_identity_store_credentials_with_args
                               (SignonIdentity *self,
                                const gchar *username,
                                const gchar *secret,
                                const gboolean store_secret,
                                GHashTable *methods,
                                const gchar *caption,
                                const gchar * const *realms,
                                const SignonSecurityContext *owner,
                                GList *access_control_list,
                                SignonIdentityType type,
                                SignonIdentityStoreCredentialsCb cb,
                                gpointer user_data);

Stores the given data into the identity. See above for the meaning of the specific fields.

Parameters

self	the SignonIdentity.
username	username.	[allow-none]
secret	secret.	[allow-none]
store_secret	whether gSSO should save the password in secret storage.
methods	allowed methods.	[transfer none][element-type utf8 GStrv]
caption	caption.	[allow-none]
realms	allowed realms.	[allow-none]
owner	owner.	[allow-none]
access_control_list	(allow-none) (transfer container) (element-type SignonSecurityContext): access control list.
type	the type of the identity.
cb	callback.	[scope async]
user_data	user_data.	[closure]

SignonIdentityVerifyCb ()

void
(*SignonIdentityVerifyCb) (SignonIdentity *self,
                           gboolean valid,
                           const GError *error,
                           gpointer user_data);

Callback to be passed to signon_identity_verify_user().

Parameters

self	the SignonIdentity.
valid	whether the verification succeeded.
error	a GError if an error occurred, or `NULL` otherwise.
user_data	the user data that was passed when installing this callback.

signon_identity_verify_user ()

void
signon_identity_verify_user (SignonIdentity *self,
                             GVariant *args,
                             SignonIdentityVerifyCb cb,
                             gpointer user_data);

Asks user to enter his credentials to verify the current user.

Parameters

self	the SignonIdentity.
args	optional extra arguments (vardict) controlling SignOn UI.
cb	callback.	[scope async]
user_data	user_data.

SignonIdentityInfoCb ()

void
(*SignonIdentityInfoCb) (SignonIdentity *self,
                         SignonIdentityInfo *info,
                         const GError *error,
                         gpointer user_data);

Callback to be passed to signon_identity_query_info().

Parameters

self	the SignonIdentity.
info	the SignonIdentityInfo for `self` .	[transfer none]
error	a GError if an error occurred, or `NULL` otherwise.
user_data	the user data that was passed when installing this callback.

signon_identity_query_info ()

void
signon_identity_query_info (SignonIdentity *self,
                            SignonIdentityInfoCb cb,
                            gpointer user_data);

Fetches the SignonIdentityInfo data associated with this identity.

Parameters

self	the SignonIdentity.
cb	callback.	[scope async]
user_data	user_data.	[closure user_data]

signon_identity_remove ()

void
signon_identity_remove (SignonIdentity *self,
                        SignonIdentityRemovedCb cb,
                        gpointer user_data);

Removes the corresponding credentials record from the database.

Parameters

self	the SignonIdentity.
cb	callback to be called when the operation has completed.	[scope async]
user_data	user_data to pass to the callback.	[closure user_data]

signon_identity_request_credentials_update ()

void
signon_identity_request_credentials_update
                               (SignonIdentity *self,
                                const gchar *message,
                                SignonIdentityCredentialsUpdatedCb cb,
                                gpointer user_data);

Requests user to re-enter his credentials.

Parameters

self	the SignonIdentity.
message	message to be displayed to the user.
cb	callback to be called when the operation has completed.	[scope async]
user_data	user_data to pass to the callback.	[closure user_data]

signon_identity_signout ()

void
signon_identity_signout (SignonIdentity *self,
                         SignonIdentitySignedOutCb cb,
                         gpointer user_data);

Asks signond to close all authentication sessions for this identity, and to remove any stored secrets associated with it (password and authentication tokens).

Parameters

self	the SignonIdentity.
cb	callback.	[scope async]
user_data	user_data.	[closure user_data]

signon_identity_add_reference ()

void
signon_identity_add_reference (SignonIdentity *self,
                               const gchar *reference,
                               SignonIdentityReferenceAddedCb cb,
                               gpointer user_data);

Adds named reference to identity. Not currently supported by gSSO.

Parameters

self	the SignonIdentity.
reference	reference to be added
cb	callback.	[scope async]
user_data	user_data.	[closure user_data]

signon_identity_remove_reference ()

void
signon_identity_remove_reference (SignonIdentity *self,
                                  const gchar *reference,
                                  SignonIdentityReferenceRemovedCb cb,
                                  gpointer user_data);

Removes named reference from identity. Not currently supported by gSSO.

Parameters

self	the SignonIdentity.
reference	reference to be removed
cb	callback.	[scope async]
user_data	user_data.	[closure user_data]

SignonIdentitySessionReadyCb ()

void
(*SignonIdentitySessionReadyCb) (SignonAuthSession *self,
                                 GError *error,
                                 GDBusConnection *connection,
                                 const gchar *bus_name,
                                 const gchar *object_path);

Callback to be passed to signon_identity_get_auth_session().

Parameters

self	the SignonAuthSession.
error	a GError if an error occurred, or `NULL` otherwise.
connection	a GDBusConnection for the session.
bus_name	a D-Bus bus name for the session.
object_path	a D-Bus object path for the session.

signon_identity_get_auth_session ()

void
signon_identity_get_auth_session (SignonIdentity *self,
                                  SignonAuthSession *session,
                                  const gchar *method,
                                  SignonIdentitySessionReadyCb cb);

Obtain a remote object for a local session object. Should not be used by applications.

Parameters

self	the SignonIdentity.
session	the SignonAuthSession object to get the remote object for.
method	method name for the session.
cb	completion callback.	[scope async]

Types and Values

SignonIdentityRemovedCb

typedef SignonIdentityVoidCb SignonIdentityRemovedCb;

Callback to be passed to signon_identity_remove().

SignonIdentityCredentialsUpdatedCb

typedef SignonIdentityVoidCb SignonIdentityCredentialsUpdatedCb;

Callback to be passed to signon_identity_request_credentials_update().

SignonIdentitySignedOutCb

typedef SignonIdentityVoidCb SignonIdentitySignedOutCb;

Callback to be passed to signon_identity_signout().

SignonIdentityReferenceAddedCb

typedef SignonIdentityVoidCb SignonIdentityReferenceAddedCb;

Callback to be passed to signon_identity_add_reference().

SignonIdentityReferenceRemovedCb

typedef SignonIdentityVoidCb SignonIdentityReferenceRemovedCb;

Callback to be passed to signon_identity_remove_reference().

Property Details

The `“app-ctx”` property

  “app-ctx”                  gchar *

Set/Get Application Security Context.

Flags: Read / Write

Default value: ""

The `“id”` property

  “id”                       guint

Set/Get Identity ID.

Flags: Read / Write

Default value: 0

Signal Details

The `“removed”` signal

void
user_function (SignonIdentity *arg0,
               gpointer        user_data)

Emitted when the identity was removed (deleted).

Parameters

user_data

user data set when the signal handler was connected.

Flags: No Hooks

The `“signout”` signal

void
user_function (SignonIdentity *arg0,
               gpointer        user_data)

Emitted when the identity was signed out.

Parameters

user_data

user data set when the signal handler was connected.

Flags: No Hooks

SignonIdentity

Functions

Properties

Signals

Types and Values

Object Hierarchy

Description

Operations on an identity

Data fields in SignonIdentityInfo

Functions

SignonIdentityVoidCb ()

Parameters

signon_identity_new_from_db ()

Parameters

Returns

signon_identity_new ()

Returns

signon_identity_new_with_context_from_db ()

Parameters

Returns

signon_identity_new_with_context ()

Parameters

Returns

signon_identity_get_last_error ()

Parameters

Returns

signon_identity_create_session ()

Parameters

Returns

SignonIdentityStoreCredentialsCb ()

Parameters

signon_identity_store_credentials_with_info ()

Parameters

signon_identity_store_credentials_with_args ()

Parameters

SignonIdentityVerifyCb ()

Parameters

signon_identity_verify_user ()

Parameters

SignonIdentityInfoCb ()

Parameters

signon_identity_query_info ()

Parameters

signon_identity_remove ()

Parameters

signon_identity_request_credentials_update ()

Parameters

signon_identity_signout ()

Parameters

signon_identity_add_reference ()

Parameters

signon_identity_remove_reference ()

Parameters

SignonIdentitySessionReadyCb ()

Parameters

signon_identity_get_auth_session ()

Parameters

Types and Values

SignonIdentityRemovedCb

SignonIdentityCredentialsUpdatedCb

SignonIdentitySignedOutCb

SignonIdentityReferenceAddedCb

SignonIdentityReferenceRemovedCb

Property Details

The “app-ctx” property

The “id” property

Signal Details

The “removed” signal

Parameters

The “signout” signal

Parameters

The `“app-ctx”` property

The `“id”` property

The `“removed”` signal

The `“signout”` signal