def login(self, subject, authc_token):
try:<EOL><INDENT>account_id = self.authenticator.authenticate_account(subject.identifiers,<EOL>authc_token)<EOL><DEDENT>except AdditionalAuthenticationRequired as exc:<EOL><INDENT>self.update_subject_identity(exc.account_id, subject)<EOL>raise AdditionalAuthenticationRequired<EOL><DEDENT>except AuthenticationException as authc_ex:<EOL><INDENT>try:<EOL><INDENT>self.on_failed_login(authc_token, authc_ex, subject)<EOL><DEDENT>except Exception:<EOL><INDENT>msg = ("<STR_LIT>"<EOL>"<STR_LIT>")<EOL>logger.info(msg, exc_info=True)<EOL><DEDENT>raise<EOL><DEDENT>logged_in = self.create_subject(authc_token=authc_token,<EOL>account_id=account_id,<EOL>existing_subject=subject)<EOL>self.on_successful_login(authc_token, account_id, logged_in)<EOL>return logged_in<EOL>
Login authenticates a user using an AuthenticationToken.  If authentication is
successful AND the Authenticator has determined that authentication is
complete for the account, login constructs a Subject instance representing
the authenticated account's identity. Once a subject instance is constructed,
it is bound to the application for subsequent access before being returned
to the caller.

If login successfully authenticates a token but the Authenticator has
determined that subject's account isn't considered authenticated,
the account is configured for multi-factor authentication.

Sessionless environments must pass all authentication tokens to login
at once.

:param authc_token: the authenticationToken to process for the login attempt
:type authc_token:  authc_abcs.authenticationToken

:returns: a Subject representing the authenticated user
:raises AuthenticationException:  if there is a problem authenticating
                                  the specified authc_token
:raises AdditionalAuthenticationRequired: during multi-factor authentication
                                          when additional tokens are required