Sailfish Accounts

API Documentation

SignInParameters QML Type

Provides access to sign-in parameters applicable to a service More...

Import Statement: import .

List of all members, including inherited members

Properties

mechanisms : QStringList
method : string
parameters : QVariantMap
password : QString
serviceName : string
username : QString

Methods

void removeParameter(const QString &parameterName)
void setParameter(const QString &parameterName, const QVariant &parameterValue)
void setParameters(const QVariantMap &params)

Detailed Description

The Account::signIn() function requires clients to pass in SignInParameters which allow the application to sign in using the specified credentials. These parameters include the authentication method and mechanism associated with a service (for example, Facebook requires a user_agent OAuth2 flow) and can include other parameters pertinent to the sign in process (for example, scopes which define permissions requested from the user).

The properties of an SignInParameter instance will NOT update automatically if the credentials in the database are updated or removed by a different process, or if any services change.

When performing sign-in, applications will retrieve the parameters applicable for them through the account, and then modify the parameters (for example, to add the ClientId parameter) as necessary for their use-case.

An example of using the SignInParameters type to create sign-in credentials with an OAuth-based service is:

 import Sailfish.Accounts 1.0

 Account {
     id: account
     identifier: 12 // retrieved from AccountManager or AccountModel

     onStatusChanged: {
         if (status == Account.Initialized) {
             var siParams = signInParameters("facebook-sharing")
             siParams.setParameter("ClientId", "123456789abcdef") // set application-specific client id
             siParams.setParameter("Scope", ["user_events"])      // set application-specific scopes
             if (!hasSignInCredentials("MyApp", "MyCredentials")) {
                 createSignInCredentials("MyApp", "SharingCredentials", "MySecretKey", siParams)
             } else {
                 signIn("MyApp", "SharingCredentials", "MySecretKey", siParams)
             }
         }
     }

     onSignInCredentialsCreated: {
         for (var i in data) console.log(i+"="+data[i]) // AccessToken etc
     }

     onSignInResponse: {
         for (var i in data) console.log(i+"="+data[i]) // AccessToken etc
     }
 }

Credentials for non-OAuth-based services often require a username and password to be specified. These fields of the SignInParameters need only be specified if the application needs to create sign-in credentials (as you should not ask the user to input username/password once the credentials have been created).

 import Sailfish.Accounts 1.0

 Account {
     id: account
     identifier: 15 // some Jabber account retrieved from AccountManager or AccountModel

     onStatusChanged: {
         if (status == Account.Initialized) {
             if (!hasSignInCredentials("MyApp", "MyCredentials")) {
                 // ... request username/password from user via UI
                 var usernameFromUI = ...
                 var passwordFromUI = ...
                 // once we have those, create the SignInParameters:
                 var siParams = signInParameters("jabber", usernameFromUI, passwordFromUI)
                 createSignInCredentials("MyApp", "JabberCredentials", "MySecretKey", siParams)
             } else {
                 // already have sign in credentials, so use the existing SignInParameters:
                 var siParams = signInParameters("jabber")
                 signIn("MyApp", "JabberCredentials", "MySecretKey", siParams)
             }
         }
     }

     onSignInCredentialsCreated: {
         for (var i in data) console.log(i+"="+data[i]) // AccessToken etc
     }

     onSignInResponse: {
         for (var i in data) console.log(i+"="+data[i]) // AccessToken etc
     }
 }

Property Documentation

mechanisms : QStringList

The mechanisms used to authenticate with the service

method : string

The name of the method used to authenticate with the service

parameters : QVariantMap

The parameters used during authentication with the service. These parameters can be used as SessionData when invoking Account::signIn().

password : QString

The password to be used during authentication with the service. It is only applicable to services which use password-based authentication methods, and does not affect OAuth-based services (as these use web-based authentication instead).

This property should only be set during credentials creation; subsequent sign-in requests will use the password specified during credentials creation only.

serviceName : string

The name of the service for which these parameters are valid

username : QString

The username to be used during authentication with the service.

This property should only be set during credentials creation; subsequent sign-in requests will use the username specified during credentials creation only.

Method Documentation

void removeParameter(const QString &parameterName)

Unsets the value of the parameter specified by the given parameterName. This does not affect the method, mechanism, username or password parameters.

Example:

 var params = account.signInParameters("facebook-sharing")
 params.removeParameter("Scope")
 // no scopes (permissions) will be requested during sign in

void setParameter(const QString &parameterName, const QVariant &parameterValue)

Sets the value of the parameter specified by the given parameterName to the given parameterValue. This does not affect the method, mechanism, username or password parameters.

Only QString, QStringList, int and bool values are recognised.

Example:

 var params = account.signInParameters("facebook-sharing")
 params.setParameter("ClientId", "123456789abcdef")
 // application can now sign in to Facebook with these parameters

Different services accept different parameters. Valid parameter names may be ascertained by inspecting account provider .service files, and some commonly-used parameter names are included below for information purposes:

OAuth-based services using the user_agent flow have the following known parameter names:

Host
AuthPath
RedirectUri
Scope
Display ("touch" is a valid value)
ClientId
ClientSecret

OAuth-based services using the HMAC-SHA1 flow have the following known parameter names:

RequestEndpoint
TokenEndpoint
AuthorizationEndpoint
AllowedSchemes
Callback
ConsumerKey
ConsumerSecret

Generally speaking most of these parameters should be provided by the service automatically. Some, like the ClientId or ConsumerKey parameters MUST be provided by applications performing sign-in.

Additionally, the "UiPolicy" parameter is applicable for all services, and valid values are defined by the UiPolicy enumeration, which are as follows:

DefaultPolicy - UI may be shown to the user if no cached credentials exist
RequestPasswordPolicy - UI will be shown to the user even if cached credentials exist
NoUserInteractionPolicy - UI will not be shown to the user even if no cached credentials exist. The sign in operation will fail unless cached credentials exist.
ValidationPolicy - UI will only be shown to the user if validation (eg, CAPTCHA) is requested by the service

In general, the DefaultPolicy should suffice for most use-cases, except for sync use-cases (where NoUserInteractionPolicy) should generally be defined. For example:

 var params = account.signInParameters("facebook-sync")
 params.setParameter("ClientId", "123456789abcdef")
 params.setParameter("UiPolicy", SignInParameters.NoUserInteractionPolicy)
 // application can now sign in to Facebook with these parameters

Further, the "CredentialsPolicy" parameter is applicable for OAuth services. The value of this parameter may be:

UseCachedCredentialsPolicy - sign in will return cached credentials if they exist and have not expired
RefreshCredentialsPolicy - sign in will cause a token refresh to occur even if cached credentials exist and have not expired

Note that the UseCachedCredentialsPolicy can still result in a token refresh occurring, if the currently cached tokens have expired. The RefreshCredentialsPolicy should be used if the token has been invalidated server-side, and the client application has detected this case (due to the error message which is returned from the server). For example:

 var params = account.signInParameters("google-sync")
 params.setParameter("ClientId", "123456789abcdef")
 params.setParameter("ClientSecret", "abcdef123456789")
 params.setParameter("UiPolicy", SignInParameters.NoUserInteractionPolicy)
 params.setParameter("CredentialsPolicy", SignInParameters.RefreshCredentialsPolicy)
 // signing in will return refreshed tokens (if they are able to be refreshed)

The CredentialsPolicy parameter is ignored if the service is not an OAuth-enabled service.

void setParameters(const QVariantMap &params)

Removes all existing parameters, and then calls setParameter() for each parameter in the specified params map.