Interface IUserAuthenticationUI

Method Details

• initialize

  SignInPermissions initialize(IClientSessionGyro clientGyro, SignInPermissions initialPermissions, VSField user, VSField password, VSField rememberMe, VSField autoLogin, VSField authProvider) throws ValueConversionException

  Initializes the user ID, password, "Remember Me" enabled and auto-login settings.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this initialization.

  initialPermissions - The initial permissions.

  user - The user name field (String).

  password - The password field (String): always set to the empty String, as no password is kept anywhere (CC-LOGIN-L5-DEVICE-TOKEN).

  rememberMe - The "Remember Me" check box (Boolean).

  autoLogin - The "auto-login" check box (Boolean): set when the device holds a device token to sign in with, see performDeviceSignIn(IClientSessionGyro, SignInPermissions).

  authProvider - The previous authentication provider String, or empty String if none exists or has not been chosen on the client device. If non-empty if the user had previously chosen "Remember My Choice" for the authentication provider, i.e. the panel to choose authentication provider should be skipped.

  Returns:

  The auto-login permission.

  Throws:

  ValueConversionException - In case of value conversion errors.

• getPasswordPolicy

  PasswordPolicy getPasswordPolicy()

  Gets the password policy property used for password validation.

  Returns:

  The password policy.

  Throws:

  NullPointerException - If server is not started.

• isUserNameFree

  boolean isUserNameFree(IClientSessionGyro clientGyro, String user) throws UserException

  Checks if the user name is free to use, i.e. has not yet been signed up.

  Every call is counted against the source of the client as a failed attempt, whatever the answer, and a source that is held back is refused: the answer tells whether an account exists, and a caller that asks often is enumerating (CC-LOGIN-L10A1-SERVER-GAPS, SignIn flow D-38). The SignIn module never calls it: a sign-up that names a taken name is refused with SigninResult.USER_NAME_TAKEN.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this verification.

  user - The user name.

  Returns:

  true if free, false if already taken.

  Throws:

  UserException - If the user name is invalid, or with SigninResult.TOO_MANY_INVALID_LOGINS_RETRY_LATER when the source of the client is held back.

• saveUser

  @Deprecated boolean saveUser(IClientSessionGyro clientGyro, AuthenticationProvider provider, String user, String password, boolean rememberMe, SignInPermissions autoLogin)

  Deprecated.

  Use rememberUser(IClientSessionGyro, AuthenticationProvider, boolean, boolean, SignInPermissions), which takes no password and tells remembering the user from staying signed in.

  Saves the user ID and "Remember Me" enabled settings. This is method should be called after successful login, and PRIOR to potentially changing to an active session.

  If the application does not support saving settings, the method does nothing.

  The password is NOT saved, on the device or anywhere else (CC-LOGIN-L5-DEVICE-TOKEN): the parameter is kept for the callers written before and is not read. This method is rememberUser(IClientSessionGyro, AuthenticationProvider, boolean, boolean, SignInPermissions) with the user remembered and staying signed in when rememberMe is set, and neither when it is not.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this user data saving.

  provider - The authentication provider, or null to remove the provider for next time.

  user - The user name: the user the session has signed in. Nothing is saved for another one.

  password - Not read.

  rememberMe - The "Remember Me" flag, only useful for internal authentication.

  autoLogin - The permission to perform an auto-login next time also requires user and "Remember Me" flag. The permission SignInPermissions.isBiometricsRequired() is generally not possible with external authentication providers, so if the authentication provider is not "Internal", then autoLogin will be set to SignInPermissions.NONE.

  Returns:

  true for success, false for failure. In case of failure, an error is logged in the server.

• rememberUser

  boolean rememberUser(IClientSessionGyro clientGyro, AuthenticationProvider provider, boolean rememberUser, boolean staySignedIn, SignInPermissions permissions)

  Remembers the user the session has signed in on the client's device, or forgets it there: to be called after a successful sign-in (performInternalLogin(IClientSessionGyro, String, String) and the others), and PRIOR to potentially changing to an active session.

  What is kept on the device, sealed with the server's own key, is the Sign In Provider and the user name when the user is remembered, and a device token when the user stays signed in: see the description of this interface. A device token that the device held before is replaced, or revoked when the user no longer stays signed in.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this saving; its session must have signed a user in.

  provider - The authentication provider, or null to remove the provider for next time.

  rememberUser - true to remember the user name and the provider, false to forget everything about the user on the device.

  staySignedIn - true to keep the user signed in on the device, so that performDeviceSignIn(IClientSessionGyro, SignInPermissions) signs in without the password the next time; requires rememberUser.

  permissions - The permissions: nothing is remembered that they do not allow. The user stays signed in only when the auto sign-in of the provider's kind is allowed (SignInPermissions.isAutoSignInUserPasswordAllowed() for the internal provider, SignInPermissions.isAutoSignInProviderAllowed() for the others), the server lets users stay signed in (its setting $signIn.staySignedIn), and biometrics are not required: what biometrics unlock is kept by the device itself, which is not this method's doing.

  Returns:

  true for success, false for failure: the session has signed in no user, the device parameters are unavailable, or the device token could not be stored. In case of failure, an error is logged in the server, and the device keeps no device token.

• performDeviceSignIn

  IUserAuthenticationInfo performDeviceSignIn(IClientSessionGyro clientGyro, SignInPermissions permissions) throws UserException

  Signs the user in with the device token the client's device holds, without a password: the automatic sign-in of a device the user stays signed in on. The token is verified against the server's record of it, replaced by a new one that the device is given in its place, and the user is verified as every sign-in verifies it (a disabled user, or one held back, is refused) and recorded in the session as performInternalLogin(IClientSessionGyro, String, String) records it.

  The device token is a first factor, as the password is (CC-SIGNIN-MERGE-L5-L6-L8): when the second factor of the user is due - the account has one and the token does not carry the trust for MFA (trustDeviceForMFA(IClientSessionGyro, boolean)), or the policy requires one and the account has none - the sign-in waits for it, as after performInternalLogin(IClientSessionGyro, String, String), and the answer is a result that is pending. The token proves the device, not that the user is at it: a sign-in it completes by itself is no recent sign-in, and a change of a sign-in method asks the user to confirm first (IUserAuthenticationPasskeys.isRecentlyAuthenticated(IClientSessionGyro) is false until then).

  A token is good for one use: one that is presented again after its replacement has been in use for more than a moment revokes the device, as two parties then hold it.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this sign-in.

  permissions - The permissions as they are now, those initialize(IClientSessionGyro, SignInPermissions, VSField, VSField, VSField, VSField, VSField) returned: a device whose auto sign-in they no longer allow does not sign in, and its device token is revoked.

  Returns:

  The authenticated user information; with the result SigninResult.SUCCESS_SECOND_FACTOR_REQUIRED the token was accepted and the sign-in waits for the second factor: NO user is signed in and the information names no user. null when the device does not sign in: it holds no device token, or the token is unknown, expired, revoked, another device's or another application's, or its user is refused. The reason is in the server log and is not told; the user signs in with the password instead.

  Throws:

  UserException - If the server or the application accepts no sign-in now, if the client's source is held back, or for a system failure.

• signOut

  boolean signOut(IClientSessionGyro clientGyro, boolean everywhere)

  Signs the user out: the device token the client's device holds is revoked and removed from it, so that the device does not sign in by itself again and is no longer trusted for MFA, and the session ends (G-4 of the SignIn flow design). The remembered user name and provider stay on the device, for the sign-in panel to offer; rememberUser(IClientSessionGyro, AuthenticationProvider, boolean, boolean, SignInPermissions) with rememberUser false, called before, forgets them too.

  The session ends as IClientSessionGyro.restartRemoteClient() ends one: every client of the application session disconnects and loads the application again, a new session in which nobody is signed in, and the application session is disposed of. No further processing should be done after calling this method.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this sign-out.

  everywhere - true to revoke every device the signed-in user is remembered on, in every application of this server, and not the client's alone. Sessions that are open on other devices are not ended by it; they cannot be resumed once they end.

  Returns:

  true when the session had a signed-in user or the device held a device token, and the session ends; false when there was nothing to sign out of, and nothing is done.

• getSignedInDevices

  SignedInDevice[] getSignedInDevices(IClientSessionGyro clientGyro)

  Gets the devices the signed-in user is remembered on, in every application of this server, the most recently used first.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  Returns:

  The devices, possibly none.

  Throws:

  IllegalStateException - If the session has signed in no user.

• revokeSignedInDevice

  boolean revokeSignedInDevice(IClientSessionGyro clientGyro, SignedInDevice device)

  Revokes a device of the signed-in user: its device token is deleted, so that the device neither signs in by itself again nor is trusted for MFA. A session that is open on the device is not ended by it.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  device - The device, as getSignedInDevices(IClientSessionGyro) returned it.

  Returns:

  true when the device was revoked, false when it was not the user's or already gone.

  Throws:

  IllegalStateException - If the session has signed in no user.

• revokeOtherSignedInDevices

  int revokeOtherSignedInDevices(IClientSessionGyro clientGyro)

  Revokes every device of the signed-in user but the client's own.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  Returns:

  The number of devices revoked.

  Throws:

  IllegalStateException - If the session has signed in no user.

• isAccountNoticesWanted

  boolean isAccountNoticesWanted(IClientSessionGyro clientGyro)

  Checks if the signed-in user wants the e-mail notices about changes to the account that are not security-critical (CC-SERVERADMIN-SIGNOUT-DEVICES, AM-1): a changed or reset password, a removed sign-in method, the reset of the sign-in methods and the change of this setting are mailed whatever the answer.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  Returns:

  true when the notices are on (the default), false when the user turned them off, or when nobody is signed in.

• setAccountNoticesWanted

  boolean setAccountNoticesWanted(IClientSessionGyro clientGyro, boolean wanted)

  Turns the e-mail notices about changes to the account on or off for the signed-in user, when the sign-in is recent (IUserAuthenticationPasskeys.isRecentlyAuthenticated(IClientSessionGyro)); the user is mailed of the change whatever the new value.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  wanted - true for on, false for off.

  Returns:

  true when the setting is written, false when nobody is signed in, the sign-in is not recent, or the database failed (logged).

• trustDeviceForMFA

  boolean trustDeviceForMFA(IClientSessionGyro clientGyro, boolean trust)

  Trusts the client's device for MFA, or ends the trust: a trusted device is not asked for the second factor when the signed-in user signs in on it again ("Do not ask again on this device", D-31 of the SignIn flow design). For how long is the policy's to say: the days trustDeviceDays of the sign-in policy of the application (IUserAuthenticationSecondFactor.getSignInPolicy(IClientSessionGyro); the server setting $signIn.trustDeviceDays, 30 unless configured, which the application may override), and never when that is zero. The trust is recorded by the server with the device's token, never by the device, and ends with the token: at sign-out, when the device is revoked, and at EVERY change of the password - on the device the change is made on too. It ends for every device of the user when the second factor is removed, and when one is enrolled.

  It is the trust IUserAuthenticationSecondFactor.verifySecondFactor(IClientSessionGyro, String, String, int) gives with its days, and the rules are the same (CC-SIGNIN-MERGE-L5-L6-L8): a device is trusted by a verification code, or by a passkey, which is accepted with user verification only (CC-LOGIN-M11-PASSKEY-PROOF). The device of a user who has a second factor is trusted here only in a session that verified one of the two - not after a recovery code, which is what is left when the device is lost, and not in a session that was asked for no second factor.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request; its session must have signed a user in.

  trust - true to trust the device from now on for the policy's days, false to end the trust.

  Returns:

  true for success, false for failure, logged in the server; false also when the policy trusts no device, and when the rules above refuse.

  Throws:

  IllegalStateException - If the session has signed in no user.

• isDeviceTrustedForMFA

  boolean isDeviceTrustedForMFA(IClientSessionGyro clientGyro, String user)

  Checks if the client's device is trusted for MFA for a user: whether the device holds a device token of that user for this application whose trust has not ended, and the sign-in policy of the application trusts devices. It is what the sign-in asks after the password is verified and before the second factor is.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  user - The user name.

  Returns:

  true when the second factor may be skipped on this device.

• getPendingSignIn

  SigninResult getPendingSignIn(IClientSessionGyro clientGyro)

  Gets what the sign-in of this session waits for (CC-SIGNIN-MERGE-L5-L6-L8). One sign-in waits per client session, for one thing; the answer is the result it was answered with, for the callers that were not given one: performInternalSignup(IClientSessionGyro, UserProfileInfo, String, int) throws it, and IUserAuthenticationSecondFactor.confirmTotpEnrolment(IClientSessionGyro, String) answers with the recovery codes when the sign-in it completes waits on for a passkey.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  Returns:

  A result that is pending - SUCCESS_SECOND_FACTOR_REQUIRED, SUCCESS_PASSKEY_REQUIRED or SUCCESS_PASSKEY_ENROLMENT_REQUIRED - or null when no sign-in of this session waits.

• performExternalLogin

  SigninResult performExternalLogin(IClientSessionGyro clientGyro, AuthenticationProvider provider, boolean rememberProvider, BiConsumer<SigninResult, IAuthenticatedUser> callback)

  Performs the login for any external login authentication provider.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this login.

  provider - The provider.

  rememberProvider - The flag to remember the external authentication provider in case of successful login for the user's current device.

  callback - The callback with SigninResult as first parameter, and the second parameter is the IAuthenticatedUser if the login was successful, null for unsuccessful logins.

  Returns:

  A SigninResult in case of error and the operation is not completed, null indicating the operation will proceed.

  Throws:

  IllegalArgumentException - If the provider is the internal login provider.

• performInternalLogin

  IUserAuthenticationInfo performInternalLogin(IClientSessionGyro clientGyro, String user, String password) throws UserException

  Performs the login for the internal login provider.

  The account is named by its user name or by its e-mail address (SignIn flow D-3, CC-LOGIN-L10A1-SERVER-GAPS): an identifier that contains @ is first looked up as the registered address, exactly as typed, and names the account when exactly one account holds that address, verified or not; when none does, the identifier is taken as a user name; when SEVERAL do (EM-D-1, CC-FIX-SIGNIN-ACCOUNT-MAIL: a shared address is allowed), the sign-in is refused with SigninResult.ADDRESS_SHARED - the user signs in with the user name - at this step, before any password is checked. Every other refusal is the same either way, SigninResult.INVALID_USER_OR_PASSWORD: nothing in the answer tells whether an address is registered.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this login.

  user - The user name, or the e-mail address of the account.

  password - The password.

  Returns:

  The authenticated user information. With a result that is pending the password was right and the sign-in waits: NO user is signed in and the information names no user. With SigninResult.SUCCESS_SECOND_FACTOR_REQUIRED a second factor is due, and the sign-in waits for IUserAuthenticationSecondFactor.verifySecondFactor(IClientSessionGyro, String, String, int), or for the enrolment the policy requires (IUserAuthenticationSecondFactor.getSignInMethods(IClientSessionGyro) tells which); with SigninResult.SUCCESS_PASSKEY_REQUIRED and SigninResult.SUCCESS_PASSKEY_ENROLMENT_REQUIRED it waits for a passkey (IUserAuthenticationPasskeys).

  Throws:

  NullPointerException - If user or password is null.

  IllegalArgumentException - If user or password is empty.

  UserException - If the user login failed. Please note that the exception is NOT thrown if the user needs to change password, that must be checked using UserInfoBase.mustChangePassword().

• performExternalSignup

  UserInfoBase performExternalSignup(IClientSessionGyro clientGyro, UserProfileInfo userProfile, AuthenticationProvider provider, boolean rememberProvider) throws UserException

  Performs a sign-up using the external authentication provider. If the user already exists matching the authentication provider, this method will only return the existing user information.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this sign-up.

  userProfile - The user profile data.

  provider - The external authentication provider.

  rememberProvider - The flag to remember the external authentication provider in case of successful login for the user's current device.

  Returns:

  The user information.

  Throws:

  UserException - If the user sign-up failed.

• performInternalSignup

  UserInfoBase performInternalSignup(IClientSessionGyro clientGyro, UserProfileInfo userProfile, String password, int autoLogin) throws UserException, PasswordPolicyException

  Performs a sign-up using the internal login provider: the account is created with the user name and the address of the profile, the users' password policy applies, and the sign-in of the new user follows. A user name that is taken is refused with SigninResult.USER_NAME_TAKEN, whatever the password: nothing signs in to an existing account through a sign-up (CC-LOGIN-SERVER-CORE D-2, reworded by CC-LOGIN-L10A1-SERVER-GAPS).

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this sign-up.

  userProfile - The user profile data.

  password - The password.

  autoLogin - Perform an auto-login next time (requires user, password and "Remember Me" flag). The application or server settings may override this choice. The value can be 0 (zero) for no auto-login, 1 (one) for auto-login next time, or 2 (two) for auto-login next time with biometric authentication. The last option is generally not possible with external authentication providers, so if the authentication provider is "Internal", then the autoLogin value will be set to zero. If this value is not in range or 0 to 2, it will be set to zero.

  Returns:

  The user information.

  Throws:

  UserException - If the user sign-up failed. With a result that is pending the sign-up did NOT fail: the account is created, and the sign-in of the new user waits - for the enrolment of a second factor, or for a passkey - with nothing recorded in the session (getPendingSignIn(IClientSessionGyro) tells the result again).

  PasswordPolicyException - If the password (for internal login) does not match the password policy.

• validatePassword

  PasswordPolicyResult validatePassword(IClientSessionGyro clientGyro, String user, String password)

  Validates the password against a password policy that would apply to the user in question.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this validation.

  user - The user name.

  password - The password.

  Returns:

  The password policy result.

• changePassword

  SigninResult changePassword(IClientSessionGyro clientGyro, String user, String oldPassword, String newPassword) throws PasswordPolicyException

  Changes the password for the user.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this change.

  user - The user name.

  oldPassword - The old password.

  newPassword - The new password.

  Returns:

  The login result. A result that is pending when the session has not signed the user in and its sign-in waits - for the second factor, for a passkey: nothing is changed, the sign-in waits as after performInternalLogin(IClientSessionGyro, String, String), and the change is made after it is completed.

  Throws:

  PasswordPolicyException - If the new password does not match the current password policy.

• requestPasswordReset

  void requestPasswordReset(IClientSessionGyro clientGyro, String identifier, String linkBase)

  Requests a password reset for a user who has forgotten the password: a mail with a link that is valid for 30 minutes and for one reset goes to the registered e-mail address of the account the identifier names. The link is the linkBase with the reset token appended as a query parameter; the token is sealed with the server's own key and bound to the account and to its current password, so it is spent by the reset it makes and by any other change of the password. No password is ever mailed.

  This method answers every caller the same way, whether or not the account exists, has an address, or may reset its password: it returns, and the mail is sent in the background when there is one to send. The reason nothing was sent is in the server log. Requests are limited per account and per client source; a request over the limit is dropped silently.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  identifier - The user name or the e-mail address of the account.

  linkBase - The URL the link starts with, e.g. the page of the sign-in module; the token is appended as ? or & and the parameter. It must be on the client session's own external base URL (SessionInfo.getExternalBaseURL(): the name the Browser used, the client's scheme and port, as the web server read them of the connection), otherwise nothing is sent and the refusal is logged SEVERE - no caller can mail a token on another host.

  Throws:

  NullPointerException - If identifier or linkBase is null.

• completePasswordReset

  SigninResult completePasswordReset(IClientSessionGyro clientGyro, String token, String newPassword) throws PasswordPolicyException

  Completes a password reset from the link requestPasswordReset(IClientSessionGyro, String, String) mailed: the token is verified, the new password is checked against the password policy that applies to the user and against the password history, and it replaces the old one. The token is then spent. The user is not signed in by this method.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this reset.

  token - The token from the link's query parameter.

  newPassword - The new password.

  Returns:

  SUCCESS when the password is replaced; INVALID_RESET_LINK for a token that is not this server's, altered, spent or expired, or whose account is gone or disabled; PASSWORD_CHANGE_NOT_ALLOWED for a fixed password; TOO_MANY_INVALID_LOGINS_RETRY_LATER when the client source is held back; or a server or application result.

  Throws:

  PasswordPolicyException - If the new password does not match the password policy of the user, or was used recently.

• getEmailVerificationState

  EmailVerificationState getEmailVerificationState(IClientSessionGyro clientGyro)

  Gets the state of the registered e-mail address of the user of this session: the user the session has signed in, or the user whose sign-in waits (a sign-up whose sign-in waits for the second factor or for a passkey has an address to verify too). The SignIn module shows its "Verify your email" step on it (CC-LOGIN-L10A1-SERVER-GAPS, SignIn flow G-3).

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  Returns:

  The state, never null: EmailVerificationState.NONE when the session has no user, or the user has no registered address.

• resendVerificationMail

  SigninResult resendVerificationMail(IClientSessionGyro clientGyro)

  Sends the verification mail of the registered address of the user of this session again: a sealed link valid for 72 hours, built on the client session's own origin (the configured external URL only when the session has none, R-145), SENT now through the server's mail sender, so that the answer follows what the relay did (CC-FIX-SIGNIN-ACCOUNT-MAIL). An address registered without a pending verification (written by SQL, or by an older path) gets one created and the mail goes. One mail per account per 15 minutes: a request inside that interval sends nothing and SAYS so. Every request is counted against the source of the client, as a password reset request is, and a source that is held back is refused (CC-LOGIN-L10A1-SERVER-GAPS, SignIn flow G-3).

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  Returns:

  SigninResult.SUCCESS when the relay accepted the mail, or when the address is verified (nothing to send); SigninResult.MAIL_SENT_RECENTLY when one went less than 15 minutes ago; SigninResult.MAIL_NOT_SENT_NO_ADDRESS when the account has no address; SigninResult.MAIL_NOT_SENT_NO_RELAY when the server has no mail sender; SigninResult.MAIL_NOT_SENT_NO_LINK when no link could be built; SigninResult.MAIL_NOT_SENT_REFUSED when the relay refused the mail or could not be reached (the reason in the log); SigninResult.SUCCESS_NOT_SIGNED_IN when the session has no user; SigninResult.TOO_MANY_INVALID_LOGINS_RETRY_LATER when the source is held back; SigninResult.SYSTEM_FAILURE when the database failed (logged); or the refusal of the access to the server or the application.

• requestEmailChange

  SigninResult requestEmailChange(IClientSessionGyro clientGyro, String newEmail, String password)

  Requests a change of the registered e-mail address of the user the session has signed in (CC-ACCOUNT-EMAIL-PASSWORD, SE-1; the SignIn module's "Change email" of S13). The address is checked (EmailAddressForm; a shared address is allowed, EM-D-1 of CC-FIX-SIGNIN-ACCOUNT-MAIL), the password is checked as a sign-in checks it (counted per source and per account), then the NEW address is held as pending (IZS-EmailChange detail) and the verification link is mailed to it, sealed for the new address and the user, valid for 72 hours. The account's address changes ONLY when that link is opened: the new address then replaces the registered one, verified, a notice is mailed to the old address, and the pending change is removed. A new request replaces a pending one; a pending change expires with its link. Nothing else switches an address: the administrator's change in ServerAdmin takes effect at once but goes through the same one write.

  Not offered where the user name is the address (the SignIn module shows the address with a note instead): a change is then a rename of the account.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  newEmail - The new address, as typed (trimmed by the implementation).

  password - The current password of the signed-in user.

  Returns:

  SigninResult.SUCCESS when the change is pending and the link is queued; SigninResult.SUCCESS_NOT_SIGNED_IN when the session has no user; SigninResult.INVALID_EMAIL for an address without the form of one; SigninResult.EMAIL_CHANGE_NOT_ALLOWED for an external Sign In Provider's account and when the user name is the address; SigninResult.INVALID_USER_OR_PASSWORD when the password is wrong (counted); SigninResult.TOO_MANY_INVALID_LOGINS_RETRY_LATER when the source is held back; SigninResult.MAIL_NOT_SENT_NO_RELAY, SigninResult.MAIL_NOT_SENT_NO_LINK or SigninResult.MAIL_NOT_SENT_REFUSED when the link cannot be mailed - no mail sender, no base URL for the link, the relay refused it (logged; nothing is pending then; the link is SENT now on the client session's origin, R-145, CC-FIX-SIGNIN-ACCOUNT-MAIL); SigninResult.SYSTEM_FAILURE when the database failed; or the refusal of the access to the server or the application.

  Throws:

  NullPointerException - If newEmail or password is null.

  IllegalArgumentException - If the password is empty.

• getPendingEmailChange

  String getPendingEmailChange(IClientSessionGyro clientGyro)

  Gets the address a pending change of the registered e-mail address names (requestEmailChange(IClientSessionGyro, String, String)): the address the user asked for and has not confirmed yet.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this request.

  Returns:

  The new address, or null when no change is pending, when it has expired, or when the session has no user.

• getActiveUserSessions

  IAppSessionGyro[] getActiveUserSessions(IClientSessionGyro clientGyro)

  Gets the current user sessions that can be switched to, i.e. sessions that have been started by the logged in user.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this change.

  Returns:

  The sessions that are started by the user. The array may be empty, indicating that no session is available to switch to.

  Throws:

  IllegalStateException - If the user is not successfully logged in.

• switchTo

  boolean switchTo(IClientSessionGyro clientGyro, IAppSessionGyro session)

  Switches to the specified active application session. No further processing should be done after calling this method in case it returns true.

  Parameters:

  clientGyro - The Client Session Gyro that is the cause of this change.

  session - The application session to switch to.

  Returns:

  true for success, false if the session has been disposed of and that the switch never occurred.

  Throws:

  IllegalStateException - If the user is not successfully logged in, or the session does not belong to the currently logged in user.