7.2 Account System

The Limax provides a credential account sytem supporting sub-account via Auany, assigning the sessionid.

  • The basic concept

    1. credential, the credential signed by the key of the auany and represented via string. The current system provides the Session credential and Temporary credential.

    2. authcode, the authoriztion code from the user, is used for the credential signature.

    3. serial, the credential serial number. After the credential updates, the serial number increases one. The system confirms the validity of the credential via serial number and denies the overdue credential.

    4. loginConfig, the object of login.

    5. mainid, the sessionid of the main account.

    6. uid, the user id of the sytem, is the lowcase string convered by username@platflag.

    7. appid, the application flag. An applid is assigned for each application of the Auany. In the same uid, different appid maps the different mainid.

    8. derive, creates a non-binding main account or derives sub-account under the main account.

    9. bind, creats a binding main account, or binds an account, or updates the credential serial number.

  • Session Credential

    The below method might return a string like credential[,subid]+ to support the sub-account. This string is a complete Session credential representation, among which the subid is the sub-account.

    • Creating a non-binding account


      AuanyService.derive(String httpHost, int httpPort, int appid, String authcode, long timeout, Result onresult);

      The httpHost and httpPost here are the http server address provided by the Auany, and the appid indicates the requested application.

      If onresult.errorSource == ErrorSource.LIMAX && onresult.errorCode == SUCCEED, the onresult.result is the returned initial Session credential.

    • Creating a binding account


      AuanyService.bind(String httpHost, int httpPort, int appid, String authcode, LoginConfig loginConfig, long timeout, Result onresult);

      Compared with the non-binding account, parameter loginConfig added. A bound Session credential is created after successful authentication with the parameter.

      In particularly, if the appid in the mapped uid has associated a mainid after the authentication of the username, token and platflag, the relative serial is incremented and the complete Session credential representation is returned. This function might be used to retrieve account.

    • Deriving a sub-account


      AuanyService.derive(String credential, String authcode, long timeout, Result onresult);

      If this method executes successfully, the onresult.result returns the complete Session credential representation. If there are N subid before, the N+1 subsid are included after the return, and the last subid is the derived new sub-account.

      The upper limitation of the derived sub-account id decided by the configuration paramter maxSubordinates of the application. For the detailed information, please refer the service-auany.xml.

    • Binding an account


      AuanyService.bind(String credential, String authcode, LoginConfig loginConfig, long timeout, Result onresult);

      This method processes the binding after the authentication of the loginConfig, and returns the complete Session credential representation.

      Except for binding the non-binding account(credential), this method also uses the same loginConfig used when binding for the repeatedly binding to return the complete the Session credential representation.

    • The influence of the Provider

      The ProviderTransport interface provides two methods:


      long getMainId();
String getUid();

      Through comparing the mainid returned by the getMainId() with the current sessionid, we could learn whether the current login is in the main account or sub-account.

    • Logining with the Session credential

      The username parameter of the login specifies the Session credential, the token specifies the authcode, and the platflag specifies the "credential". If the sub-account logins, the platflag add the suffix ":subid".Method LoginConfig.credentialLogin is preferred..

    • The consideration for the mobile client

      The credential mode is suitable for the mobile client implementation, and meets the requirement that the account binds when necessary.

      The returned Session credential should be stored locally for the directly logining when next accessing. If the sub-account is supported, the association with the relative UI resource should be considered in the multiple condition.

      A question which need to be considered is the exception which might happen when non-binding account processes the binding after logining -- after initiating the bind operation, the network disconnects -- in this condition, it is unsure whether the binding is successful. So the previous credential is firstly used for the next login. If unsuccessful, non-credential way is used to login. After the successfully login, the bind is initiated again until the complete Session credential representation is obtained, then saves it locally.

    • The consideration for the pc and web clients

      These two kinds of clients usually do not store the credentail locally. The common way could be used to login. If there is requirement for the sub-account, the bind way is used to obtain the complete Session credential representation, then derives the sub-account. Or the main account is used to login using empty credential and empty authcode, and call the derive. In this condition, the onresult.result just returns the new sub-account string.

    • The consideration for the sub-account

      In the system using sub-account function, the Provider usually maintains the relationship between the sub-account and the main account. There are two problems to be considered.

      1. The relationship between the mainid and the session provided by the ProviderTransport should be verified. If the sub-account logins, it should verify whether the affiliation has changed. If it changed, the relative update should be executed because there might be the sub-account migration happened.

      2. The sub-account id provided by the client should not be trusted. For example, the sub-account derived from the client should not be provided to the Provider to creat the relative record. The correct solution is that after the client derives the sub-account, the sub-account is used to login, and the Provider finds that the relative record of the corresponding session does not exist and create it.

  • Temporary Credential

    The Temporary credential addes the timeline on the basis of the Session credential which will be invalid when expiration; addes the subid attribute which could directly identify the sub-account; addes the usage attribute which supports two usages -- temporary login and account transfer.

    • Creating the Temporary Credential


      1.  AuanyService.temporary(String credential, String authcode, String authcode2, long millisecond, byte usage, String subid, long timeout, Result onresult);
2.  AuanyService.temporary(String httpHost, int httpPort, int appid, String credential, String authcode, String authcode2, long millisecond, byte usage, String subid, long timeout, Result onresult);
3.  AuanyService.temporary(LoginConfig loginConfig, int appid, String authcode,long millisecond, byte usage, String subid, long timeout, Result onresult);
4.  AuanyService.temporary(String httpHost, int httpPort, int appid, LoginConfig loginConfig, String authcode, long millisecond, byte usage, String subid, long timeout, Result onresult);

      The method 1, 2, create the temporary credential via Session credential. The method 2 need not to be performed in the login status.

      The method 3, 4, create the temporary credential via logining the account. The method 4 need to to be performed in the login status.

      The authcode2 parameter of the method 1, 3 and the authcode parameter of the method 2, 4, identify the authcode of the temporary credential.

      The millisecond parameter specifies the effective time which is counted when the temporary credential is created, and the unit is millisecond.

      The usage parameter specifies the usage of the temporary credential. USAGE_LOGIN = 1 specifies that the temporary credential is used to login. USAGE_TRANSFER = 2 specifies that the temporary credential is used for account transferring.

      The subid parameter specifies the sub-account flag string. The empty string specifies that the temporary credential is used in the main account.

      After successful execution, the onresult.result returns the temporary credential.

    • Temporary credential login

      Similar as the login of the Session credential, the difference is the suffix of the sub-account in the platflag has no meaning because the temporary credential itself includes the subid.

    • Account transfer


      AuanyService.transfer(String httpHost, int httpPort, int appid, LoginConfig loginConfig, String authcode, String temp, String authtemp, long timeout, Result onresult);

      The httpHost and httpPort here are the http server address provied by the Auany, and appid specifies the requested application.

      The loginConfig specifies the receive account. The authcode is the generated authorization code of the Session credential after the account receives.

      The temp and authtemp are the temporary credential and its authorization code.

      After successful execution, the onresult.result returns the complete Session credential representation of the receive account.


      The matters need to be considered:

      1. A valid account must be used to receive the transfer account.

      2. When the account identified by the temporary credential is transferred, it could be the main account -- in this condition, the main accound and all the sub-account are transferred together, and the receive account has not bound this application, or the appid conflict is reported; it also could be the sub-account -- in this condition, if this receive account has not bound this application, the main account should be created firstly, then add this sub-account. If this receive account has bound this application, the sub-account could be added without violating the restriction of the maxSubordinates.

      3. If the application provides the support to the sub-account transfer, the implementation of the Provider must verify the relationship between the mainid and the sessionid.

  • Matters need attention

    1. The method with the httpHost, httpPort and appid three parameter as the beginning need not to be executed in the account login status. These methods are the synchronization methods and returned after the onresult is triggered; the other methods are asynchronous.

    2. As long as the account is bound, the account parameter used duing binding could be used anytime to call the bind method to obtain the complete Session credential representation.

    3. Through calling the methods EndpointManager.getAccountFlags() and ProviderTransport.getAccountFlags(), the Provider and Endpoint could obtain the flag of the current login account. This flag processes the mask operation with SessionFlags.FLAG_ACCOUNT_BOUND = 1 and SessionFlags.FLAG_TEMPORARY_LOGIN = 2 and obtains whether the current login account is bound, and whether the login account is temporary, so that the specific response is taken.

    4. The temporary credential is mainly provided to be used by others. If you pull back within the validity period, the account parameters used during binding could be used to call the bind method, increments the serial and invalids all the previous generated temporary credential. The non-binding account could not be pulled back because the non-binding account forbids increment serial. Once the serial is incremented, the new credential lose due to the network issue and the old credential could not login, which means that the account lose.