code: public Tuple<User,String> login (
          String username, Password password, int expires, Authenticator auth)
          throws PersistenceException, AuthenticationFailedException
      {
          // load up the requested user
          User user = _repository.loadUser(username);
          if (user == null) {
              throw new NoSuchUserException("error.no_such_user");
          }
  
          // run the user through the authentication gamut
          auth.authenticateUser(user, username, password);
  
          // register a session for this user
          String authcode = _repository.registerSession(user, expires);
          if (USERMGR_DEBUG) {
              log.info("Session started", "user", username, "code", authcode);
          }
          return new Tuple<User,String>(user, authcode);
      }
docs: Attempts to authenticate the requester and initiate an authenticated session for them. A
  session token will be assigned to the user and returned along with the associated {@link
  User} record. It is assumed that the client will maintain the session token via its own
  means.
  
  @param username the username supplied by the user.
  @param password the password supplied by the user.
  @param expires the number of days in which this session should expire.
  @param auth the authenticator used to check whether the user should be authenticated.
  
  @return the user object of the authenticated user.