SignonIdentity

SignonIdentity — client side presentation of a credential.

Synopsis

struct              SignonIdentityClass;
void                (*SignonIdentityInfoCb)             (SignonIdentity *self,
                                                         const SignonIdentityInfo *info,
                                                         const GError *error,
                                                         gpointer user_data);
typedef             SignonIdentityReferenceAddedCb;
typedef             SignonIdentityReferenceRemovedCb;
typedef             SignonIdentityRemovedCb;
void                (*SignonIdentitySessionReadyCb)     (SignonAuthSession *self,
                                                         GError *error,
                                                         GDBusConnection *connection,
                                                         const gchar *bus_name,
                                                         const gchar *object_path);
typedef             SignonIdentitySignedOutCb;
void                (*SignonIdentityStoreCredentialsCb) (SignonIdentity *self,
                                                         guint32 id,
                                                         const GError *error,
                                                         gpointer user_data);
void                (*SignonIdentityVerifyCb)           (SignonIdentity *self,
                                                         gboolean valid,
                                                         const GError *error,
                                                         gpointer user_data);
void                (*SignonIdentityVoidCb)             (SignonIdentity *self,
                                                         const GError *error,
                                                         gpointer user_data);
void                signon_identity_add_reference       (SignonIdentity *self,
                                                         const gchar *reference,
                                                         SignonIdentityReferenceAddedCb cb,
                                                         gpointer user_data);
SignonAuthSession * signon_identity_create_session      (SignonIdentity *self,
                                                         const gchar *method,
                                                         GError **error);
void                signon_identity_get_auth_session    (SignonIdentity *self,
                                                         SignonAuthSession *session,
                                                         const gchar *method,
                                                         SignonIdentitySessionReadyCb cb);
const GError *      signon_identity_get_last_error      (SignonIdentity *identity);
SignonIdentity *    signon_identity_new                 (const gchar *application_context);
SignonIdentity *    signon_identity_new_from_db         (guint32 id,
                                                         const gchar *application_context);
void                signon_identity_query_info          (SignonIdentity *self,
                                                         SignonIdentityInfoCb cb,
                                                         gpointer user_data);
void                signon_identity_remove              (SignonIdentity *self,
                                                         SignonIdentityRemovedCb cb,
                                                         gpointer user_data);
void                signon_identity_remove_reference    (SignonIdentity *self,
                                                         const gchar *reference,
                                                         SignonIdentityReferenceRemovedCb cb,
                                                         gpointer user_data);
void                signon_identity_signout             (SignonIdentity *self,
                                                         SignonIdentitySignedOutCb cb,
                                                         gpointer user_data);
void                signon_identity_store_credentials_with_args
                                                        (SignonIdentity *self,
                                                         const gchar *username,
                                                         const gchar *secret,
                                                         const gboolean store_secret,
                                                         const GHashTable *methods,
                                                         const gchar *caption,
                                                         const gchar * const *realms,
                                                         const SignonSecurityContext *owner,
                                                         const SignonSecurityContextList *access_control_list,
                                                         SignonIdentityType type,
                                                         SignonIdentityStoreCredentialsCb cb,
                                                         gpointer user_data);
void                signon_identity_store_credentials_with_info
                                                        (SignonIdentity *self,
                                                         const SignonIdentityInfo *info,
                                                         SignonIdentityStoreCredentialsCb cb,
                                                         gpointer user_data);
void                signon_identity_verify_secret       (SignonIdentity *self,
                                                         const gchar *secret,
                                                         SignonIdentityVerifyCb cb,
                                                         gpointer user_data);

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(). 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.

  • identities stored in a database can be retrieved using signon_identity_new_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).

  • 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.

  • 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() 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.

Details

struct SignonIdentityClass

struct SignonIdentityClass {
    GObjectClass parent_class;
};

Opaque struct. Use the accessor functions below.

GObjectClass parent_class;

 reference to a parent class

SignonIdentityInfoCb ()

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

Callback to be passed to signon_identity_query_info().

self :

 the SignonIdentity.

info :

 the SignonIdentityInfo for self.

error :

 a GError if an error occurred, or NULL otherwise.

user_data :

 the user data that was passed when installing this callback.

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().

SignonIdentityRemovedCb

typedef SignonIdentityVoidCb SignonIdentityRemovedCb;

Callback to be passed to signon_identity_remove().

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().

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.

SignonIdentitySignedOutCb

typedef SignonIdentityVoidCb SignonIdentitySignedOutCb;

Callback to be passed to signon_identity_signout().

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().

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.

SignonIdentityVerifyCb ()

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

Callback to be passed to signon_identity_verify_secret().

self :

 the SignonIdentity.

valid :

 whether the secret is valid.

error :

 a GError if an error occurred, or NULL otherwise.

user_data :

 the user data that was passed when installing this callback.

SignonIdentityVoidCb ()

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

Generic callback to be passed to several SignonIdentity methods.

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_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.

self :

 the SignonIdentity.

reference :

 reference to be added

cb :

 callback

user_data :

 user_data.

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.

self :

 the SignonIdentity.

method :

 authentication method.

error :

 pointer to a location which will receive the error, if any.

Returns :

 a new SignonAuthSession. [transfer full]

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.

self :

 the SignonIdentity.

session :

 the SignonAuthSession object to get the remote object for.

method :

 method name for the session.

cb :

 completion callback. [scope async]

signon_identity_get_last_error ()

const GError *      signon_identity_get_last_error      (SignonIdentity *identity);

Get the most recent error that occurred on identity.

identity :

 the SignonIdentity.

Returns :

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

signon_identity_new ()

SignonIdentity *    signon_identity_new                 (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().

application_context :

 application security context, can be NULL.

Returns :

 an instance of an SignonIdentity.

signon_identity_new_from_db ()

SignonIdentity *    signon_identity_new_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).

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).

id :

 identity ID.

application_context :

 application security context, can be NULL.

Returns :

 an instance of a SignonIdentity.

signon_identity_query_info ()

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

Fetches the SignonIdentityInfo data associated with this identity.

self :

 the SignonIdentity.

cb :

 callback. [scope async]

user_data :

 user_data.

signon_identity_remove ()

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

Removes the corresponding credentials record from the database.

self :

 the SignonIdentity.

cb :

 callback to be called when the operation has completed. [scope async]

user_data :

 user_data to pass to the callback.

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.

self :

 the SignonIdentity.

reference :

 reference to be removed

cb :

 callback

user_data :

 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).

self :

 the SignonIdentity.

cb :

 callback. [scope async]

user_data :

 user_data.

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,
                                                         const GHashTable *methods,
                                                         const gchar *caption,
                                                         const gchar * const *realms,
                                                         const SignonSecurityContext *owner,
                                                         const SignonSecurityContextList *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.

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 :

 realms. [allow-none]

owner :

 owner. [allow-none]

access_control_list :

 access control list. [allow-none]

type :

 the type of the identity.

cb :

 callback. [scope async]

user_data :

 user_data.

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.

self :

 the SignonIdentity.

info :

 the SignonIdentityInfo data to store.

cb :

 callback. [scope async]

user_data :

 user_data.

signon_identity_verify_secret ()

void                signon_identity_verify_secret       (SignonIdentity *self,
                                                         const gchar *secret,
                                                         SignonIdentityVerifyCb cb,
                                                         gpointer user_data);

Verifies the given secret. Not currently supported by gSSO.

self :

 the SignonIdentity.

secret :

 the secret (password) to be verified.

cb :

 callback. [scope async]

user_data :

 user_data.
Generated by GTK-Doc V1.18