# Copyright 2014 - 2016 OpenMarket Ltd # Copyright 2017 Vector Creations Ltd # Copyright 2019 - 2020 The Matrix.org Foundation C.I.C. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. import logging import time import unicodedata import urllib.parse from binascii import crc32 from http import HTTPStatus from typing import ( TYPE_CHECKING, Any, Awaitable, Callable, Dict, Iterable, List, Mapping, Optional, Tuple, Type, Union, cast, ) import attr import bcrypt import pymacaroons import unpaddedbase64 from pymacaroons.exceptions import MacaroonVerificationFailedException from twisted.web.server import Request from synapse.api.constants import LoginType from synapse.api.errors import ( AuthError, Codes, InteractiveAuthIncompleteError, LoginError, StoreError, SynapseError, UserDeactivatedError, ) from synapse.api.ratelimiting import Ratelimiter from synapse.handlers.ui_auth import ( INTERACTIVE_AUTH_CHECKERS, UIAuthSessionDataConstants, ) from synapse.handlers.ui_auth.checkers import UserInteractiveAuthChecker from synapse.http import get_request_user_agent from synapse.http.server import finish_request, respond_with_html from synapse.http.site import SynapseRequest from synapse.logging.context import defer_to_thread from synapse.metrics.background_process_metrics import run_as_background_process from synapse.storage.roommember import ProfileInfo from synapse.types import JsonDict, Requester, UserID from synapse.util import stringutils as stringutils from synapse.util.async_helpers import maybe_awaitable from synapse.util.macaroons import get_value_from_macaroon, satisfy_expiry from synapse.util.msisdn import phone_number_to_msisdn from synapse.util.stringutils import base62_encode from synapse.util.threepids import canonicalise_email if TYPE_CHECKING: from synapse.module_api import ModuleApi from synapse.rest.client.login import LoginResponse from synapse.server import HomeServer logger = logging.getLogger(__name__) def convert_client_dict_legacy_fields_to_identifier( submission: JsonDict, ) -> Dict[str, str]: """ Convert a legacy-formatted login submission to an identifier dict. Legacy login submissions (used in both login and user-interactive authentication) provide user-identifying information at the top-level instead. These are now deprecated and replaced with identifiers: https://matrix.org/docs/spec/client_server/r0.6.1#identifier-types Args: submission: The client dict to convert Returns: The matching identifier dict Raises: SynapseError: If the format of the client dict is invalid """ identifier = submission.get("identifier", {}) # Generate an m.id.user identifier if "user" parameter is present user = submission.get("user") if user: identifier = {"type": "m.id.user", "user": user} # Generate an m.id.thirdparty identifier if "medium" and "address" parameters are present medium = submission.get("medium") address = submission.get("address") if medium and address: identifier = { "type": "m.id.thirdparty", "medium": medium, "address": address, } # We've converted valid, legacy login submissions to an identifier. If the # submission still doesn't have an identifier, it's invalid if not identifier: raise SynapseError(400, "Invalid login submission", Codes.INVALID_PARAM) # Ensure the identifier has a type if "type" not in identifier: raise SynapseError( 400, "'identifier' dict has no key 'type'", errcode=Codes.MISSING_PARAM, ) return identifier def login_id_phone_to_thirdparty(identifier: JsonDict) -> Dict[str, str]: """ Convert a phone login identifier type to a generic threepid identifier. Args: identifier: Login identifier dict of type 'm.id.phone' Returns: An equivalent m.id.thirdparty identifier dict """ if "country" not in identifier or ( # The specification requires a "phone" field, while Synapse used to require a "number" # field. Accept both for backwards compatibility. "phone" not in identifier and "number" not in identifier ): raise SynapseError( 400, "Invalid phone-type identifier", errcode=Codes.INVALID_PARAM ) # Accept both "phone" and "number" as valid keys in m.id.phone phone_number = identifier.get("phone", identifier["number"]) # Convert user-provided phone number to a consistent representation msisdn = phone_number_to_msisdn(identifier["country"], phone_number) return { "type": "m.id.thirdparty", "medium": "msisdn", "address": msisdn, } @attr.s(slots=True, auto_attribs=True) class SsoLoginExtraAttributes: """Data we track about SAML2 sessions""" # time the session was created, in milliseconds creation_time: int extra_attributes: JsonDict @attr.s(slots=True, frozen=True, auto_attribs=True) class LoginTokenAttributes: """Data we store in a short-term login token""" user_id: str auth_provider_id: str """The SSO Identity Provider that the user authenticated with, to get this token.""" auth_provider_session_id: Optional[str] """The session ID advertised by the SSO Identity Provider.""" class AuthHandler: SESSION_EXPIRE_MS = 48 * 60 * 60 * 1000 def __init__(self, hs: "HomeServer"): self.store = hs.get_datastores().main self.auth = hs.get_auth() self.clock = hs.get_clock() self.checkers: Dict[str, UserInteractiveAuthChecker] = {} for auth_checker_class in INTERACTIVE_AUTH_CHECKERS: inst = auth_checker_class(hs) if inst.is_enabled(): self.checkers[inst.AUTH_TYPE] = inst # type: ignore self.bcrypt_rounds = hs.config.registration.bcrypt_rounds self.password_auth_provider = hs.get_password_auth_provider() self.hs = hs # FIXME better possibility to access registrationHandler later? self.macaroon_gen = hs.get_macaroon_generator() self._password_enabled = hs.config.auth.password_enabled self._password_localdb_enabled = hs.config.auth.password_localdb_enabled # Ratelimiter for failed auth during UIA. Uses same ratelimit config # as per `rc_login.failed_attempts`. self._failed_uia_attempts_ratelimiter = Ratelimiter( store=self.store, clock=self.clock, rate_hz=self.hs.config.ratelimiting.rc_login_failed_attempts.per_second, burst_count=self.hs.config.ratelimiting.rc_login_failed_attempts.burst_count, ) # The number of seconds to keep a UI auth session active. self._ui_auth_session_timeout = hs.config.auth.ui_auth_session_timeout # Ratelimitier for failed /login attempts self._failed_login_attempts_ratelimiter = Ratelimiter( store=self.store, clock=hs.get_clock(), rate_hz=self.hs.config.ratelimiting.rc_login_failed_attempts.per_second, burst_count=self.hs.config.ratelimiting.rc_login_failed_attempts.burst_count, ) self._clock = self.hs.get_clock() # Expire old UI auth sessions after a period of time. if hs.config.worker.run_background_tasks: self._clock.looping_call( run_as_background_process, 5 * 60 * 1000, "expire_old_sessions", self._expire_old_sessions, ) # Load the SSO HTML templates. # The following template is shown to the user during a client login via SSO, # after the SSO completes and before redirecting them back to their client. # It notifies the user they are about to give access to their matrix account # to the client. self._sso_redirect_confirm_template = ( hs.config.sso.sso_redirect_confirm_template ) # The following template is shown during user interactive authentication # in the fallback auth scenario. It notifies the user that they are # authenticating for an operation to occur on their account. self._sso_auth_confirm_template = hs.config.sso.sso_auth_confirm_template # The following template is shown during the SSO authentication process if # the account is deactivated. self._sso_account_deactivated_template = ( hs.config.sso.sso_account_deactivated_template ) self._server_name = hs.config.server.server_name # cast to tuple for use with str.startswith self._whitelisted_sso_clients = tuple(hs.config.sso.sso_client_whitelist) # A mapping of user ID to extra attributes to include in the login # response. self._extra_attributes: Dict[str, SsoLoginExtraAttributes] = {} async def validate_user_via_ui_auth( self, requester: Requester, request: SynapseRequest, request_body: Dict[str, Any], description: str, can_skip_ui_auth: bool = False, ) -> Tuple[dict, Optional[str]]: """ Checks that the user is who they claim to be, via a UI auth. This is used for things like device deletion and password reset where the user already has a valid access token, but we want to double-check that it isn't stolen by re-authenticating them. Args: requester: The user, as given by the access token request: The request sent by the client. request_body: The body of the request sent by the client description: A human readable string to be displayed to the user that describes the operation happening on their account. can_skip_ui_auth: True if the UI auth session timeout applies this action. Should be set to False for any "dangerous" actions (e.g. deactivating an account). Returns: A tuple of (params, session_id). 'params' contains the parameters for this request (which may have been given only in a previous call). 'session_id' is the ID of this session, either passed in by the client or assigned by this call. This is None if UI auth was skipped (by re-using a previous validation). Raises: InteractiveAuthIncompleteError if the client has not yet completed any of the permitted login flows AuthError if the client has completed a login flow, and it gives a different user to `requester` LimitExceededError if the ratelimiter's failed request count for this user is too high to proceed """ if not requester.access_token_id: raise ValueError("Cannot validate a user without an access token") if can_skip_ui_auth and self._ui_auth_session_timeout: last_validated = await self.store.get_access_token_last_validated( requester.access_token_id ) if self.clock.time_msec() - last_validated < self._ui_auth_session_timeout: # Return the input parameters, minus the auth key, which matches # the logic in check_ui_auth. request_body.pop("auth", None) return request_body, None requester_user_id = requester.user.to_string() # Check if we should be ratelimited due to too many previous failed attempts await self._failed_uia_attempts_ratelimiter.ratelimit(requester, update=False) # build a list of supported flows supported_ui_auth_types = await self._get_available_ui_auth_types( requester.user ) flows = [[login_type] for login_type in supported_ui_auth_types] def get_new_session_data() -> JsonDict: return {UIAuthSessionDataConstants.REQUEST_USER_ID: requester_user_id} try: result, params, session_id = await self.check_ui_auth( flows, request, request_body, description, get_new_session_data, ) except LoginError: # Update the ratelimiter to say we failed (`can_do_action` doesn't raise). await self._failed_uia_attempts_ratelimiter.can_do_action( requester, ) raise # find the completed login type for login_type in supported_ui_auth_types: if login_type not in result: continue validated_user_id = result[login_type] break else: # this can't happen raise Exception("check_auth returned True but no successful login type") # check that the UI auth matched the access token if validated_user_id != requester_user_id: raise AuthError(403, "Invalid auth") # Note that the access token has been validated. await self.store.update_access_token_last_validated(requester.access_token_id) return params, session_id async def _get_available_ui_auth_types(self, user: UserID) -> Iterable[str]: """Get a list of the authentication types this user can use""" ui_auth_types = set() # if the HS supports password auth, and the user has a non-null password, we # support password auth if self._password_localdb_enabled and self._password_enabled: lookupres = await self._find_user_id_and_pwd_hash(user.to_string()) if lookupres: _, password_hash = lookupres if password_hash: ui_auth_types.add(LoginType.PASSWORD) # also allow auth from password providers for t in self.password_auth_provider.get_supported_login_types().keys(): if t == LoginType.PASSWORD and not self._password_enabled: continue ui_auth_types.add(t) # if sso is enabled, allow the user to log in via SSO iff they have a mapping # from sso to mxid. if await self.hs.get_sso_handler().get_identity_providers_for_user( user.to_string() ): ui_auth_types.add(LoginType.SSO) return ui_auth_types def get_enabled_auth_types(self) -> Iterable[str]: """Return the enabled user-interactive authentication types Returns the UI-Auth types which are supported by the homeserver's current config. """ return self.checkers.keys() async def check_ui_auth( self, flows: List[List[str]], request: SynapseRequest, clientdict: Dict[str, Any], description: str, get_new_session_data: Optional[Callable[[], JsonDict]] = None, ) -> Tuple[dict, dict, str]: """ Takes a dictionary sent by the client in the login / registration protocol and handles the User-Interactive Auth flow. If no auth flows have been completed successfully, raises an InteractiveAuthIncompleteError. To handle this, you can use synapse.rest.client._base.interactive_auth_handler as a decorator. Args: flows: A list of login flows. Each flow is an ordered list of strings representing auth-types. At least one full flow must be completed in order for auth to be successful. request: The request sent by the client. clientdict: The dictionary from the client root level, not the 'auth' key: this method prompts for auth if none is sent. description: A human readable string to be displayed to the user that describes the operation happening on their account. get_new_session_data: an optional callback which will be called when starting a new session. it should return data to be stored as part of the session. The keys of the returned data should be entries in UIAuthSessionDataConstants. Returns: A tuple of (creds, params, session_id). 'creds' contains the authenticated credentials of each stage. 'params' contains the parameters for this request (which may have been given only in a previous call). 'session_id' is the ID of this session, either passed in by the client or assigned by this call Raises: InteractiveAuthIncompleteError if the client has not yet completed all the stages in any of the permitted flows. """ sid: Optional[str] = None authdict = clientdict.pop("auth", {}) if "session" in authdict: sid = authdict["session"] # Convert the URI and method to strings. uri = request.uri.decode("utf-8") # type: ignore method = request.method.decode("utf-8") # If there's no session ID, create a new session. if not sid: new_session_data = get_new_session_data() if get_new_session_data else {} session = await self.store.create_ui_auth_session( clientdict, uri, method, description ) for k, v in new_session_data.items(): await self.set_session_data(session.session_id, k, v) else: try: session = await self.store.get_ui_auth_session(sid) except StoreError: raise SynapseError(400, "Unknown session ID: %s" % (sid,)) # If the client provides parameters, update what is persisted, # otherwise use whatever was last provided. # # This was designed to allow the client to omit the parameters # and just supply the session in subsequent calls so it split # auth between devices by just sharing the session, (eg. so you # could continue registration from your phone having clicked the # email auth link on there). It's probably too open to abuse # because it lets unauthenticated clients store arbitrary objects # on a homeserver. # # Revisit: Assuming the REST APIs do sensible validation, the data # isn't arbitrary. # # Note that the registration endpoint explicitly removes the # "initial_device_display_name" parameter if it is provided # without a "password" parameter. See the changes to # synapse.rest.client.register.RegisterRestServlet.on_POST # in commit 544722bad23fc31056b9240189c3cbbbf0ffd3f9. if not clientdict: clientdict = session.clientdict # Ensure that the queried operation does not vary between stages of # the UI authentication session. This is done by generating a stable # comparator and storing it during the initial query. Subsequent # queries ensure that this comparator has not changed. # # The comparator is based on the requested URI and HTTP method. The # client dict (minus the auth dict) should also be checked, but some # clients are not spec compliant, just warn for now if the client # dict changes. if (session.uri, session.method) != (uri, method): raise SynapseError( 403, "Requested operation has changed during the UI authentication session.", ) if session.clientdict != clientdict: logger.warning( "Requested operation has changed during the UI " "authentication session. A future version of Synapse " "will remove this capability." ) # For backwards compatibility, changes to the client dict are # persisted as clients modify them throughout their user interactive # authentication flow. await self.store.set_ui_auth_clientdict(sid, clientdict) user_agent = get_request_user_agent(request) clientip = request.getClientIP() await self.store.add_user_agent_ip_to_ui_auth_session( session.session_id, user_agent, clientip ) if not authdict: raise InteractiveAuthIncompleteError( session.session_id, self._auth_dict_for_flows(flows, session.session_id) ) # check auth type currently being presented errordict: Dict[str, Any] = {} if "type" in authdict: login_type: str = authdict["type"] try: result = await self._check_auth_dict(authdict, clientip) if result: await self.store.mark_ui_auth_stage_complete( session.session_id, login_type, result ) except LoginError as e: # this step failed. Merge the error dict into the response # so that the client can have another go. errordict = e.error_dict() creds = await self.store.get_completed_ui_auth_stages(session.session_id) for f in flows: # If all the required credentials have been supplied, the user has # successfully completed the UI auth process! if len(set(f) - set(creds)) == 0: # it's very useful to know what args are stored, but this can # include the password in the case of registering, so only log # the keys (confusingly, clientdict may contain a password # param, creds is just what the user authed as for UI auth # and is not sensitive). logger.info( "Auth completed with creds: %r. Client dict has keys: %r", creds, list(clientdict), ) return creds, clientdict, session.session_id ret = self._auth_dict_for_flows(flows, session.session_id) ret["completed"] = list(creds) ret.update(errordict) raise InteractiveAuthIncompleteError(session.session_id, ret) async def add_oob_auth( self, stagetype: str, authdict: Dict[str, Any], clientip: str ) -> None: """ Adds the result of out-of-band authentication into an existing auth session. Currently used for adding the result of fallback auth. Raises: LoginError if the stagetype is unknown or the session is missing. LoginError is raised by check_auth if authentication fails. """ if stagetype not in self.checkers: raise LoginError( 400, f"Unknown UIA stage type: {stagetype}", Codes.INVALID_PARAM ) if "session" not in authdict: raise LoginError(400, "Missing session ID", Codes.MISSING_PARAM) # If authentication fails a LoginError is raised. Otherwise, store # the successful result. result = await self.checkers[stagetype].check_auth(authdict, clientip) await self.store.mark_ui_auth_stage_complete( authdict["session"], stagetype, result ) def get_session_id(self, clientdict: Dict[str, Any]) -> Optional[str]: """ Gets the session ID for a client given the client dictionary Args: clientdict: The dictionary sent by the client in the request Returns: The string session ID the client sent. If the client did not send a session ID, returns None. """ sid = None if clientdict and "auth" in clientdict: authdict = clientdict["auth"] if "session" in authdict: sid = authdict["session"] return sid async def set_session_data(self, session_id: str, key: str, value: Any) -> None: """ Store a key-value pair into the sessions data associated with this request. This data is stored server-side and cannot be modified by the client. Args: session_id: The ID of this session as returned from check_auth key: The key to store the data under. An entry from UIAuthSessionDataConstants. value: The data to store """ try: await self.store.set_ui_auth_session_data(session_id, key, value) except StoreError: raise SynapseError(400, "Unknown session ID: %s" % (session_id,)) async def get_session_data( self, session_id: str, key: str, default: Optional[Any] = None ) -> Any: """ Retrieve data stored with set_session_data Args: session_id: The ID of this session as returned from check_auth key: The key the data was stored under. An entry from UIAuthSessionDataConstants. default: Value to return if the key has not been set """ try: return await self.store.get_ui_auth_session_data(session_id, key, default) except StoreError: raise SynapseError(400, "Unknown session ID: %s" % (session_id,)) async def _expire_old_sessions(self) -> None: """ Invalidate any user interactive authentication sessions that have expired. """ now = self._clock.time_msec() expiration_time = now - self.SESSION_EXPIRE_MS await self.store.delete_old_ui_auth_sessions(expiration_time) async def _check_auth_dict( self, authdict: Dict[str, Any], clientip: str ) -> Union[Dict[str, Any], str]: """Attempt to validate the auth dict provided by a client Args: authdict: auth dict provided by the client clientip: IP address of the client Returns: Result of the stage verification. Raises: StoreError if there was a problem accessing the database SynapseError if there was a problem with the request LoginError if there was an authentication problem. """ login_type = authdict["type"] checker = self.checkers.get(login_type) if checker is not None: res = await checker.check_auth(authdict, clientip=clientip) return res # fall back to the v1 login flow canonical_id, _ = await self.validate_login(authdict) return canonical_id def _get_params_recaptcha(self) -> dict: return {"public_key": self.hs.config.captcha.recaptcha_public_key} def _get_params_terms(self) -> dict: return { "policies": { "privacy_policy": { "version": self.hs.config.consent.user_consent_version, "en": { "name": self.hs.config.consent.user_consent_policy_name, "url": "%s_matrix/consent?v=%s" % ( self.hs.config.server.public_baseurl, self.hs.config.consent.user_consent_version, ), }, } } } def _auth_dict_for_flows( self, flows: List[List[str]], session_id: str, ) -> Dict[str, Any]: public_flows = [] for f in flows: public_flows.append(f) get_params = { LoginType.RECAPTCHA: self._get_params_recaptcha, LoginType.TERMS: self._get_params_terms, } params: Dict[str, Any] = {} for f in public_flows: for stage in f: if stage in get_params and stage not in params: params[stage] = get_params[stage]() return { "session": session_id, "flows": [{"stages": f} for f in public_flows], "params": params, } async def refresh_token( self, refresh_token: str, access_token_valid_until_ms: Optional[int], refresh_token_valid_until_ms: Optional[int], ) -> Tuple[str, str, Optional[int]]: """ Consumes a refresh token and generate both a new access token and a new refresh token from it. The consumed refresh token is considered invalid after the first use of the new access token or the new refresh token. The lifetime of both the access token and refresh token will be capped so that they do not exceed the session's ultimate expiry time, if applicable. Args: refresh_token: The token to consume. access_token_valid_until_ms: The expiration timestamp of the new access token. None if the access token does not expire. refresh_token_valid_until_ms: The expiration timestamp of the new refresh token. None if the refresh token does not expire. Returns: A tuple containing: - the new access token - the new refresh token - the actual expiry time of the access token, which may be earlier than `access_token_valid_until_ms`. """ # Verify the token signature first before looking up the token if not self._verify_refresh_token(refresh_token): raise SynapseError( HTTPStatus.UNAUTHORIZED, "invalid refresh token", Codes.UNKNOWN_TOKEN ) existing_token = await self.store.lookup_refresh_token(refresh_token) if existing_token is None: raise SynapseError( HTTPStatus.UNAUTHORIZED, "refresh token does not exist", Codes.UNKNOWN_TOKEN, ) if ( existing_token.has_next_access_token_been_used or existing_token.has_next_refresh_token_been_refreshed ): raise SynapseError( HTTPStatus.FORBIDDEN, "refresh token isn't valid anymore", Codes.FORBIDDEN, ) now_ms = self._clock.time_msec() if existing_token.expiry_ts is not None and existing_token.expiry_ts < now_ms: raise SynapseError( HTTPStatus.FORBIDDEN, "The supplied refresh token has expired", Codes.FORBIDDEN, ) if existing_token.ultimate_session_expiry_ts is not None: # This session has a bounded lifetime, even across refreshes. if access_token_valid_until_ms is not None: access_token_valid_until_ms = min( access_token_valid_until_ms, existing_token.ultimate_session_expiry_ts, ) else: access_token_valid_until_ms = existing_token.ultimate_session_expiry_ts if refresh_token_valid_until_ms is not None: refresh_token_valid_until_ms = min( refresh_token_valid_until_ms, existing_token.ultimate_session_expiry_ts, ) else: refresh_token_valid_until_ms = existing_token.ultimate_session_expiry_ts if existing_token.ultimate_session_expiry_ts < now_ms: raise SynapseError( HTTPStatus.FORBIDDEN, "The session has expired and can no longer be refreshed", Codes.FORBIDDEN, ) ( new_refresh_token, new_refresh_token_id, ) = await self.create_refresh_token_for_user_id( user_id=existing_token.user_id, device_id=existing_token.device_id, expiry_ts=refresh_token_valid_until_ms, ultimate_session_expiry_ts=existing_token.ultimate_session_expiry_ts, ) access_token = await self.create_access_token_for_user_id( user_id=existing_token.user_id, device_id=existing_token.device_id, valid_until_ms=access_token_valid_until_ms, refresh_token_id=new_refresh_token_id, ) await self.store.replace_refresh_token( existing_token.token_id, new_refresh_token_id ) return access_token, new_refresh_token, access_token_valid_until_ms def _verify_refresh_token(self, token: str) -> bool: """ Verifies the shape of a refresh token. Args: token: The refresh token to verify Returns: Whether the token has the right shape """ parts = token.split("_", maxsplit=4) if len(parts) != 4: return False type, localpart, rand, crc = parts # Refresh tokens are prefixed by "syr_", let's check that if type != "syr": return False # Check the CRC base = f"{type}_{localpart}_{rand}" expected_crc = base62_encode(crc32(base.encode("ascii")), minwidth=6) if crc != expected_crc: return False return True async def create_refresh_token_for_user_id( self, user_id: str, device_id: str, expiry_ts: Optional[int], ultimate_session_expiry_ts: Optional[int], ) -> Tuple[str, int]: """ Creates a new refresh token for the user with the given user ID. Args: user_id: canonical user ID device_id: the device ID to associate with the token. expiry_ts (milliseconds since the epoch): Time after which the refresh token cannot be used. If None, the refresh token never expires until it has been used. ultimate_session_expiry_ts (milliseconds since the epoch): Time at which the session will end and can not be extended any further. If None, the session can be refreshed indefinitely. Returns: The newly created refresh token and its ID in the database """ refresh_token = self.generate_refresh_token(UserID.from_string(user_id)) refresh_token_id = await self.store.add_refresh_token_to_user( user_id=user_id, token=refresh_token, device_id=device_id, expiry_ts=expiry_ts, ultimate_session_expiry_ts=ultimate_session_expiry_ts, ) return refresh_token, refresh_token_id async def create_access_token_for_user_id( self, user_id: str, device_id: Optional[str], valid_until_ms: Optional[int], puppets_user_id: Optional[str] = None, is_appservice_ghost: bool = False, refresh_token_id: Optional[int] = None, ) -> str: """ Creates a new access token for the user with the given user ID. The user is assumed to have been authenticated by some other mechanism (e.g. CAS), and the user_id converted to the canonical case. The device will be recorded in the table if it is not there already. Args: user_id: canonical User ID device_id: the device ID to associate with the tokens. None to leave the tokens unassociated with a device (deprecated: we should always have a device ID) valid_until_ms: when the token is valid until. None for no expiry. is_appservice_ghost: Whether the user is an application ghost user refresh_token_id: the refresh token ID that will be associated with this access token. Returns: The access token for the user's session. Raises: StoreError if there was a problem storing the token. """ fmt_expiry = "" if valid_until_ms is not None: fmt_expiry = time.strftime( " until %Y-%m-%d %H:%M:%S", time.localtime(valid_until_ms / 1000.0) ) if puppets_user_id: logger.info( "Logging in user %s as %s%s", user_id, puppets_user_id, fmt_expiry ) target_user_id_obj = UserID.from_string(puppets_user_id) else: logger.info( "Logging in user %s on device %s%s", user_id, device_id, fmt_expiry ) target_user_id_obj = UserID.from_string(user_id) if ( not is_appservice_ghost or self.hs.config.appservice.track_appservice_user_ips ): await self.auth.check_auth_blocking(user_id) access_token = self.generate_access_token(target_user_id_obj) await self.store.add_access_token_to_user( user_id=user_id, token=access_token, device_id=device_id, valid_until_ms=valid_until_ms, puppets_user_id=puppets_user_id, refresh_token_id=refresh_token_id, ) # the device *should* have been registered before we got here; however, # it's possible we raced against a DELETE operation. The thing we # really don't want is active access_tokens without a record of the # device, so we double-check it here. if device_id is not None: if await self.store.get_device(user_id, device_id) is None: await self.store.delete_access_token(access_token) raise StoreError(400, "Login raced against device deletion") return access_token async def check_user_exists(self, user_id: str) -> Optional[str]: """ Checks to see if a user with the given id exists. Will check case insensitively, but return None if there are multiple inexact matches. Args: user_id: complete @user:id Returns: The canonical_user_id, or None if zero or multiple matches """ res = await self._find_user_id_and_pwd_hash(user_id) if res is not None: return res[0] return None async def _find_user_id_and_pwd_hash( self, user_id: str ) -> Optional[Tuple[str, str]]: """Checks to see if a user with the given id exists. Will check case insensitively, but will return None if there are multiple inexact matches. Returns: A 2-tuple of `(canonical_user_id, password_hash)` or `None` if there is not exactly one match """ user_infos = await self.store.get_users_by_id_case_insensitive(user_id) result = None if not user_infos: logger.warning("Attempted to login as %s but they do not exist", user_id) elif len(user_infos) == 1: # a single match (possibly not exact) result = user_infos.popitem() elif user_id in user_infos: # multiple matches, but one is exact result = (user_id, user_infos[user_id]) else: # multiple matches, none of them exact logger.warning( "Attempted to login as %s but it matches more than one user " "inexactly: %r", user_id, user_infos.keys(), ) return result def can_change_password(self) -> bool: """Get whether users on this server are allowed to change or set a password. Both `config.auth.password_enabled` and `config.auth.password_localdb_enabled` must be true. Note that any account (even SSO accounts) are allowed to add passwords if the above is true. Returns: Whether users on this server are allowed to change or set a password """ return self._password_enabled and self._password_localdb_enabled def get_supported_login_types(self) -> Iterable[str]: """Get a the login types supported for the /login API By default this is just 'm.login.password' (unless password_enabled is False in the config file), but password auth providers can provide other login types. Returns: login types """ # Load any login types registered by modules # This is stored in the password_auth_provider so this doesn't trigger # any callbacks types = list(self.password_auth_provider.get_supported_login_types().keys()) # This list should include PASSWORD if (either _password_localdb_enabled is # true or if one of the modules registered it) AND _password_enabled is true # Also: # Some clients just pick the first type in the list. In this case, we want # them to use PASSWORD (rather than token or whatever), so we want to make sure # that comes first, where it's present. if LoginType.PASSWORD in types: types.remove(LoginType.PASSWORD) if self._password_enabled: types.insert(0, LoginType.PASSWORD) elif self._password_localdb_enabled and self._password_enabled: types.insert(0, LoginType.PASSWORD) return types async def validate_login( self, login_submission: Dict[str, Any], ratelimit: bool = False, ) -> Tuple[str, Optional[Callable[["LoginResponse"], Awaitable[None]]]]: """Authenticates the user for the /login API Also used by the user-interactive auth flow to validate auth types which don't have an explicit UIA handler, including m.password.auth. Args: login_submission: the whole of the login submission (including 'type' and other relevant fields) ratelimit: whether to apply the failed_login_attempt ratelimiter Returns: A tuple of the canonical user id, and optional callback to be called once the access token and device id are issued Raises: StoreError if there was a problem accessing the database SynapseError if there was a problem with the request LoginError if there was an authentication problem. """ login_type = login_submission.get("type") if not isinstance(login_type, str): raise SynapseError(400, "Bad parameter: type", Codes.INVALID_PARAM) # ideally, we wouldn't be checking the identifier unless we know we have a login # method which uses it (https://github.com/matrix-org/synapse/issues/8836) # # But the auth providers' check_auth interface requires a username, so in # practice we can only support login methods which we can map to a username # anyway. # special case to check for "password" for the check_password interface # for the auth providers password = login_submission.get("password") if login_type == LoginType.PASSWORD: if not self._password_enabled: raise SynapseError(400, "Password login has been disabled.") if not isinstance(password, str): raise SynapseError(400, "Bad parameter: password", Codes.INVALID_PARAM) # map old-school login fields into new-school "identifier" fields. identifier_dict = convert_client_dict_legacy_fields_to_identifier( login_submission ) # convert phone type identifiers to generic threepids if identifier_dict["type"] == "m.id.phone": identifier_dict = login_id_phone_to_thirdparty(identifier_dict) # convert threepid identifiers to user IDs if identifier_dict["type"] == "m.id.thirdparty": address = identifier_dict.get("address") medium = identifier_dict.get("medium") if medium is None or address is None: raise SynapseError(400, "Invalid thirdparty identifier") # For emails, canonicalise the address. # We store all email addresses canonicalised in the DB. # (See add_threepid in synapse/handlers/auth.py) if medium == "email": try: address = canonicalise_email(address) except ValueError as e: raise SynapseError(400, str(e)) # We also apply account rate limiting using the 3PID as a key, as # otherwise using 3PID bypasses the ratelimiting based on user ID. if ratelimit: await self._failed_login_attempts_ratelimiter.ratelimit( None, (medium, address), update=False ) # Check for login providers that support 3pid login types if login_type == LoginType.PASSWORD: # we've already checked that there is a (valid) password field assert isinstance(password, str) ( canonical_user_id, callback_3pid, ) = await self.check_password_provider_3pid(medium, address, password) if canonical_user_id: # Authentication through password provider and 3pid succeeded return canonical_user_id, callback_3pid # No password providers were able to handle this 3pid # Check local store user_id = await self.hs.get_datastores().main.get_user_id_by_threepid( medium, address ) if not user_id: logger.warning( "unknown 3pid identifier medium %s, address %r", medium, address ) # We mark that we've failed to log in here, as # `check_password_provider_3pid` might have returned `None` due # to an incorrect password, rather than the account not # existing. # # If it returned None but the 3PID was bound then we won't hit # this code path, which is fine as then the per-user ratelimit # will kick in below. if ratelimit: await self._failed_login_attempts_ratelimiter.can_do_action( None, (medium, address) ) raise LoginError(403, "", errcode=Codes.FORBIDDEN) identifier_dict = {"type": "m.id.user", "user": user_id} # by this point, the identifier should be an m.id.user: if it's anything # else, we haven't understood it. if identifier_dict["type"] != "m.id.user": raise SynapseError(400, "Unknown login identifier type") username = identifier_dict.get("user") if not username: raise SynapseError(400, "User identifier is missing 'user' key") if username.startswith("@"): qualified_user_id = username else: qualified_user_id = UserID(username, self.hs.hostname).to_string() # Check if we've hit the failed ratelimit (but don't update it) if ratelimit: await self._failed_login_attempts_ratelimiter.ratelimit( None, qualified_user_id.lower(), update=False ) try: return await self._validate_userid_login(username, login_submission) except LoginError: # The user has failed to log in, so we need to update the rate # limiter. Using `can_do_action` avoids us raising a ratelimit # exception and masking the LoginError. The actual ratelimiting # should have happened above. if ratelimit: await self._failed_login_attempts_ratelimiter.can_do_action( None, qualified_user_id.lower() ) raise async def _validate_userid_login( self, username: str, login_submission: Dict[str, Any], ) -> Tuple[str, Optional[Callable[["LoginResponse"], Awaitable[None]]]]: """Helper for validate_login Handles login, once we've mapped 3pids onto userids Args: username: the username, from the identifier dict login_submission: the whole of the login submission (including 'type' and other relevant fields) Returns: A tuple of the canonical user id, and optional callback to be called once the access token and device id are issued Raises: StoreError if there was a problem accessing the database SynapseError if there was a problem with the request LoginError if there was an authentication problem. """ if username.startswith("@"): qualified_user_id = username else: qualified_user_id = UserID(username, self.hs.hostname).to_string() login_type = login_submission.get("type") # we already checked that we have a valid login type assert isinstance(login_type, str) known_login_type = False # Check if login_type matches a type registered by one of the modules # We don't need to remove LoginType.PASSWORD from the list if password login is # disabled, since if that were the case then by this point we know that the # login_type is not LoginType.PASSWORD supported_login_types = self.password_auth_provider.get_supported_login_types() # check if the login type being used is supported by a module if login_type in supported_login_types: # Make a note that this login type is supported by the server known_login_type = True # Get all the fields expected for this login types login_fields = supported_login_types[login_type] # go through the login submission and keep track of which required fields are # provided/not provided missing_fields = [] login_dict = {} for f in login_fields: if f not in login_submission: missing_fields.append(f) else: login_dict[f] = login_submission[f] # raise an error if any of the expected fields for that login type weren't provided if missing_fields: raise SynapseError( 400, "Missing parameters for login type %s: %s" % (login_type, missing_fields), ) # call all of the check_auth hooks for that login_type # it will return a result once the first success is found (or None otherwise) result = await self.password_auth_provider.check_auth( username, login_type, login_dict ) if result: return result # if no module managed to authenticate the user, then fallback to built in password based auth if login_type == LoginType.PASSWORD and self._password_localdb_enabled: known_login_type = True # we've already checked that there is a (valid) password field password = login_submission["password"] assert isinstance(password, str) canonical_user_id = await self._check_local_password( qualified_user_id, password ) if canonical_user_id: return canonical_user_id, None if not known_login_type: raise SynapseError(400, "Unknown login type %s" % login_type) # We raise a 403 here, but note that if we're doing user-interactive # login, it turns all LoginErrors into a 401 anyway. raise LoginError(403, "Invalid password", errcode=Codes.FORBIDDEN) async def check_password_provider_3pid( self, medium: str, address: str, password: str ) -> Tuple[Optional[str], Optional[Callable[["LoginResponse"], Awaitable[None]]]]: """Check if a password provider is able to validate a thirdparty login Args: medium: The medium of the 3pid (ex. email). address: The address of the 3pid (ex. jdoe@example.com). password: The password of the user. Returns: A tuple of `(user_id, callback)`. If authentication is successful, `user_id`is the authenticated, canonical user ID. `callback` is then either a function to be later run after the server has completed login/registration, or `None`. If authentication was unsuccessful, `user_id` and `callback` are both `None`. """ # call all of the check_3pid_auth callbacks # Result will be from the first callback that returns something other than None # If all the callbacks return None, then result is also set to None result = await self.password_auth_provider.check_3pid_auth( medium, address, password ) if result: return result # if result is None then return (None, None) return None, None async def _check_local_password(self, user_id: str, password: str) -> Optional[str]: """Authenticate a user against the local password database. user_id is checked case insensitively, but will return None if there are multiple inexact matches. Args: user_id: complete @user:id password: the provided password Returns: The canonical_user_id, or None if unknown user/bad password """ lookupres = await self._find_user_id_and_pwd_hash(user_id) if not lookupres: return None (user_id, password_hash) = lookupres # If the password hash is None, the account has likely been deactivated if not password_hash: deactivated = await self.store.get_user_deactivated_status(user_id) if deactivated: raise UserDeactivatedError("This account has been deactivated") result = await self.validate_hash(password, password_hash) if not result: logger.warning("Failed password login for user %s", user_id) return None return user_id def generate_access_token(self, for_user: UserID) -> str: """Generates an opaque string, for use as an access token""" # we use the following format for access tokens: # syt_<base64 local part>_<random string>_<base62 crc check> b64local = unpaddedbase64.encode_base64(for_user.localpart.encode("utf-8")) random_string = stringutils.random_string(20) base = f"syt_{b64local}_{random_string}" crc = base62_encode(crc32(base.encode("ascii")), minwidth=6) return f"{base}_{crc}" def generate_refresh_token(self, for_user: UserID) -> str: """Generates an opaque string, for use as a refresh token""" # we use the following format for refresh tokens: # syr_<base64 local part>_<random string>_<base62 crc check> b64local = unpaddedbase64.encode_base64(for_user.localpart.encode("utf-8")) random_string = stringutils.random_string(20) base = f"syr_{b64local}_{random_string}" crc = base62_encode(crc32(base.encode("ascii")), minwidth=6) return f"{base}_{crc}" async def validate_short_term_login_token( self, login_token: str ) -> LoginTokenAttributes: try: res = self.macaroon_gen.verify_short_term_login_token(login_token) except Exception: raise AuthError(403, "Invalid login token", errcode=Codes.FORBIDDEN) await self.auth.check_auth_blocking(res.user_id) return res async def delete_access_token(self, access_token: str) -> None: """Invalidate a single access token Args: access_token: access token to be deleted """ user_info = await self.auth.get_user_by_access_token(access_token) await self.store.delete_access_token(access_token) # see if any modules want to know about this await self.password_auth_provider.on_logged_out( user_id=user_info.user_id, device_id=user_info.device_id, access_token=access_token, ) # delete pushers associated with this access token if user_info.token_id is not None: await self.hs.get_pusherpool().remove_pushers_by_access_token( user_info.user_id, (user_info.token_id,) ) async def delete_access_tokens_for_user( self, user_id: str, except_token_id: Optional[int] = None, device_id: Optional[str] = None, ) -> None: """Invalidate access tokens belonging to a user Args: user_id: ID of user the tokens belong to except_token_id: access_token ID which should *not* be deleted device_id: ID of device the tokens are associated with. If None, tokens associated with any device (or no device) will be deleted """ tokens_and_devices = await self.store.user_delete_access_tokens( user_id, except_token_id=except_token_id, device_id=device_id ) # see if any modules want to know about this for token, _, device_id in tokens_and_devices: await self.password_auth_provider.on_logged_out( user_id=user_id, device_id=device_id, access_token=token ) # delete pushers associated with the access tokens await self.hs.get_pusherpool().remove_pushers_by_access_token( user_id, (token_id for _, token_id, _ in tokens_and_devices) ) async def add_threepid( self, user_id: str, medium: str, address: str, validated_at: int ) -> None: # check if medium has a valid value if medium not in ["email", "msisdn"]: raise SynapseError( code=400, msg=("'%s' is not a valid value for 'medium'" % (medium,)), errcode=Codes.INVALID_PARAM, ) # 'Canonicalise' email addresses down to lower case. # We've now moving towards the homeserver being the entity that # is responsible for validating threepids used for resetting passwords # on accounts, so in future Synapse will gain knowledge of specific # types (mediums) of threepid. For now, we still use the existing # infrastructure, but this is the start of synapse gaining knowledge # of specific types of threepid (and fixes the fact that checking # for the presence of an email address during password reset was # case sensitive). if medium == "email": address = canonicalise_email(address) await self.store.user_add_threepid( user_id, medium, address, validated_at, self.hs.get_clock().time_msec() ) async def delete_threepid( self, user_id: str, medium: str, address: str, id_server: Optional[str] = None ) -> bool: """Attempts to unbind the 3pid on the identity servers and deletes it from the local database. Args: user_id: ID of user to remove the 3pid from. medium: The medium of the 3pid being removed: "email" or "msisdn". address: The 3pid address to remove. id_server: Use the given identity server when unbinding any threepids. If None then will attempt to unbind using the identity server specified when binding (if known). Returns: Returns True if successfully unbound the 3pid on the identity server, False if identity server doesn't support the unbind API. """ # 'Canonicalise' email addresses as per above if medium == "email": address = canonicalise_email(address) identity_handler = self.hs.get_identity_handler() result = await identity_handler.try_unbind_threepid( user_id, {"medium": medium, "address": address, "id_server": id_server} ) await self.store.user_delete_threepid(user_id, medium, address) if medium == "email": await self.store.delete_pusher_by_app_id_pushkey_user_id( app_id="m.email", pushkey=address, user_id=user_id ) return result async def hash(self, password: str) -> str: """Computes a secure hash of password. Args: password: Password to hash. Returns: Hashed password. """ def _do_hash() -> str: # Normalise the Unicode in the password pw = unicodedata.normalize("NFKC", password) return bcrypt.hashpw( pw.encode("utf8") + self.hs.config.auth.password_pepper.encode("utf8"), bcrypt.gensalt(self.bcrypt_rounds), ).decode("ascii") return await defer_to_thread(self.hs.get_reactor(), _do_hash) async def validate_hash( self, password: str, stored_hash: Union[bytes, str] ) -> bool: """Validates that self.hash(password) == stored_hash. Args: password: Password to hash. stored_hash: Expected hash value. Returns: Whether self.hash(password) == stored_hash. """ def _do_validate_hash(checked_hash: bytes) -> bool: # Normalise the Unicode in the password pw = unicodedata.normalize("NFKC", password) return bcrypt.checkpw( pw.encode("utf8") + self.hs.config.auth.password_pepper.encode("utf8"), checked_hash, ) if stored_hash: if not isinstance(stored_hash, bytes): stored_hash = stored_hash.encode("ascii") return await defer_to_thread( self.hs.get_reactor(), _do_validate_hash, stored_hash ) else: return False async def start_sso_ui_auth(self, request: SynapseRequest, session_id: str) -> str: """ Get the HTML for the SSO redirect confirmation page. Args: request: The incoming HTTP request session_id: The user interactive authentication session ID. Returns: The HTML to render. """ try: session = await self.store.get_ui_auth_session(session_id) except StoreError: raise SynapseError(400, "Unknown session ID: %s" % (session_id,)) user_id_to_verify: str = await self.get_session_data( session_id, UIAuthSessionDataConstants.REQUEST_USER_ID ) idps = await self.hs.get_sso_handler().get_identity_providers_for_user( user_id_to_verify ) if not idps: # we checked that the user had some remote identities before offering an SSO # flow, so either it's been deleted or the client has requested SSO despite # it not being offered. raise SynapseError(400, "User has no SSO identities") # for now, just pick one idp_id, sso_auth_provider = next(iter(idps.items())) if len(idps) > 0: logger.warning( "User %r has previously logged in with multiple SSO IdPs; arbitrarily " "picking %r", user_id_to_verify, idp_id, ) redirect_url = await sso_auth_provider.handle_redirect_request( request, None, session_id ) return self._sso_auth_confirm_template.render( description=session.description, redirect_url=redirect_url, idp=sso_auth_provider, ) async def complete_sso_login( self, registered_user_id: str, auth_provider_id: str, request: Request, client_redirect_url: str, extra_attributes: Optional[JsonDict] = None, new_user: bool = False, auth_provider_session_id: Optional[str] = None, ) -> None: """Having figured out a mxid for this user, complete the HTTP request Args: registered_user_id: The registered user ID to complete SSO login for. auth_provider_id: The id of the SSO Identity provider that was used for login. This will be stored in the login token for future tracking in prometheus metrics. request: The request to complete. client_redirect_url: The URL to which to redirect the user at the end of the process. extra_attributes: Extra attributes which will be passed to the client during successful login. Must be JSON serializable. new_user: True if we should use wording appropriate to a user who has just registered. auth_provider_session_id: The session ID from the SSO IdP received during login. """ # If the account has been deactivated, do not proceed with the login # flow. deactivated = await self.store.get_user_deactivated_status(registered_user_id) if deactivated: respond_with_html(request, 403, self._sso_account_deactivated_template) return profile = await self.store.get_profileinfo( UserID.from_string(registered_user_id).localpart ) self._complete_sso_login( registered_user_id, auth_provider_id, request, client_redirect_url, extra_attributes, new_user=new_user, user_profile_data=profile, auth_provider_session_id=auth_provider_session_id, ) def _complete_sso_login( self, registered_user_id: str, auth_provider_id: str, request: Request, client_redirect_url: str, extra_attributes: Optional[JsonDict] = None, new_user: bool = False, user_profile_data: Optional[ProfileInfo] = None, auth_provider_session_id: Optional[str] = None, ) -> None: """ The synchronous portion of complete_sso_login. This exists purely for backwards compatibility of synapse.module_api.ModuleApi. """ if user_profile_data is None: user_profile_data = ProfileInfo(None, None) # Store any extra attributes which will be passed in the login response. # Note that this is per-user so it may overwrite a previous value, this # is considered OK since the newest SSO attributes should be most valid. if extra_attributes: self._extra_attributes[registered_user_id] = SsoLoginExtraAttributes( self._clock.time_msec(), extra_attributes, ) # Create a login token login_token = self.macaroon_gen.generate_short_term_login_token( registered_user_id, auth_provider_id=auth_provider_id, auth_provider_session_id=auth_provider_session_id, ) # Append the login token to the original redirect URL (i.e. with its query # parameters kept intact) to build the URL to which the template needs to # redirect the users once they have clicked on the confirmation link. redirect_url = self.add_query_param_to_url( client_redirect_url, "loginToken", login_token ) # if the client is whitelisted, we can redirect straight to it if client_redirect_url.startswith(self._whitelisted_sso_clients): request.redirect(redirect_url) finish_request(request) return # Otherwise, serve the redirect confirmation page. # Remove the query parameters from the redirect URL to get a shorter version of # it. This is only to display a human-readable URL in the template, but not the # URL we redirect users to. url_parts = urllib.parse.urlsplit(client_redirect_url) if url_parts.scheme == "https": # for an https uri, just show the netloc (ie, the hostname. Specifically, # the bit between "//" and "/"; this includes any potential # "username:password@" prefix.) display_url = url_parts.netloc else: # for other uris, strip the query-params (including the login token) and # fragment. display_url = urllib.parse.urlunsplit( (url_parts.scheme, url_parts.netloc, url_parts.path, "", "") ) html = self._sso_redirect_confirm_template.render( display_url=display_url, redirect_url=redirect_url, server_name=self._server_name, new_user=new_user, user_id=registered_user_id, user_profile=user_profile_data, ) respond_with_html(request, 200, html) async def _sso_login_callback(self, login_result: "LoginResponse") -> None: """ A login callback which might add additional attributes to the login response. Args: login_result: The data to be sent to the client. Includes the user ID and access token. """ # Expire attributes before processing. Note that there shouldn't be any # valid logins that still have extra attributes. self._expire_sso_extra_attributes() extra_attributes = self._extra_attributes.get(login_result["user_id"]) if extra_attributes: login_result_dict = cast(Dict[str, Any], login_result) login_result_dict.update(extra_attributes.extra_attributes) def _expire_sso_extra_attributes(self) -> None: """ Iterate through the mapping of user IDs to extra attributes and remove any that are no longer valid. """ # TODO This should match the amount of time the macaroon is valid for. LOGIN_TOKEN_EXPIRATION_TIME = 2 * 60 * 1000 expire_before = self._clock.time_msec() - LOGIN_TOKEN_EXPIRATION_TIME to_expire = set() for user_id, data in self._extra_attributes.items(): if data.creation_time < expire_before: to_expire.add(user_id) for user_id in to_expire: logger.debug("Expiring extra attributes for user %s", user_id) del self._extra_attributes[user_id] @staticmethod def add_query_param_to_url(url: str, param_name: str, param: Any) -> str: url_parts = list(urllib.parse.urlparse(url)) query = urllib.parse.parse_qsl(url_parts[4], keep_blank_values=True) query.append((param_name, param)) url_parts[4] = urllib.parse.urlencode(query) return urllib.parse.urlunparse(url_parts) @attr.s(slots=True, auto_attribs=True) class MacaroonGenerator: hs: "HomeServer" def generate_guest_access_token(self, user_id: str) -> str: macaroon = self._generate_base_macaroon(user_id) macaroon.add_first_party_caveat("type = access") # Include a nonce, to make sure that each login gets a different # access token. macaroon.add_first_party_caveat( "nonce = %s" % (stringutils.random_string_with_symbols(16),) ) macaroon.add_first_party_caveat("guest = true") return macaroon.serialize() def generate_short_term_login_token( self, user_id: str, auth_provider_id: str, auth_provider_session_id: Optional[str] = None, duration_in_ms: int = (2 * 60 * 1000), ) -> str: macaroon = self._generate_base_macaroon(user_id) macaroon.add_first_party_caveat("type = login") now = self.hs.get_clock().time_msec() expiry = now + duration_in_ms macaroon.add_first_party_caveat("time < %d" % (expiry,)) macaroon.add_first_party_caveat("auth_provider_id = %s" % (auth_provider_id,)) if auth_provider_session_id is not None: macaroon.add_first_party_caveat( "auth_provider_session_id = %s" % (auth_provider_session_id,) ) return macaroon.serialize() def verify_short_term_login_token(self, token: str) -> LoginTokenAttributes: """Verify a short-term-login macaroon Checks that the given token is a valid, unexpired short-term-login token minted by this server. Args: token: the login token to verify Returns: the user_id that this token is valid for Raises: MacaroonVerificationFailedException if the verification failed """ macaroon = pymacaroons.Macaroon.deserialize(token) user_id = get_value_from_macaroon(macaroon, "user_id") auth_provider_id = get_value_from_macaroon(macaroon, "auth_provider_id") auth_provider_session_id: Optional[str] = None try: auth_provider_session_id = get_value_from_macaroon( macaroon, "auth_provider_session_id" ) except MacaroonVerificationFailedException: pass v = pymacaroons.Verifier() v.satisfy_exact("gen = 1") v.satisfy_exact("type = login") v.satisfy_general(lambda c: c.startswith("user_id = ")) v.satisfy_general(lambda c: c.startswith("auth_provider_id = ")) v.satisfy_general(lambda c: c.startswith("auth_provider_session_id = ")) satisfy_expiry(v, self.hs.get_clock().time_msec) v.verify(macaroon, self.hs.config.key.macaroon_secret_key) return LoginTokenAttributes( user_id=user_id, auth_provider_id=auth_provider_id, auth_provider_session_id=auth_provider_session_id, ) def generate_delete_pusher_token(self, user_id: str) -> str: macaroon = self._generate_base_macaroon(user_id) macaroon.add_first_party_caveat("type = delete_pusher") return macaroon.serialize() def _generate_base_macaroon(self, user_id: str) -> pymacaroons.Macaroon: macaroon = pymacaroons.Macaroon( location=self.hs.config.server.server_name, identifier="key", key=self.hs.config.key.macaroon_secret_key, ) macaroon.add_first_party_caveat("gen = 1") macaroon.add_first_party_caveat("user_id = %s" % (user_id,)) return macaroon def load_legacy_password_auth_providers(hs: "HomeServer") -> None: module_api = hs.get_module_api() for module, config in hs.config.authproviders.password_providers: load_single_legacy_password_auth_provider( module=module, config=config, api=module_api ) def load_single_legacy_password_auth_provider( module: Type, config: JsonDict, api: "ModuleApi", ) -> None: try: provider = module(config=config, account_handler=api) except Exception as e: logger.error("Error while initializing %r: %s", module, e) raise # All methods that the module provides should be async, but this wasn't enforced # in the old module system, so we wrap them if needed def async_wrapper(f: Optional[Callable]) -> Optional[Callable[..., Awaitable]]: # f might be None if the callback isn't implemented by the module. In this # case we don't want to register a callback at all so we return None. if f is None: return None # We need to wrap check_password because its old form would return a boolean # but we now want it to behave just like check_auth() and return the matrix id of # the user if authentication succeeded or None otherwise if f.__name__ == "check_password": async def wrapped_check_password( username: str, login_type: str, login_dict: JsonDict ) -> Optional[Tuple[str, Optional[Callable]]]: # We've already made sure f is not None above, but mypy doesn't do well # across function boundaries so we need to tell it f is definitely not # None. assert f is not None matrix_user_id = api.get_qualified_user_id(username) password = login_dict["password"] is_valid = await f(matrix_user_id, password) if is_valid: return matrix_user_id, None return None return wrapped_check_password # We need to wrap check_auth as in the old form it could return # just a str, but now it must return Optional[Tuple[str, Optional[Callable]] if f.__name__ == "check_auth": async def wrapped_check_auth( username: str, login_type: str, login_dict: JsonDict ) -> Optional[Tuple[str, Optional[Callable]]]: # We've already made sure f is not None above, but mypy doesn't do well # across function boundaries so we need to tell it f is definitely not # None. assert f is not None result = await f(username, login_type, login_dict) if isinstance(result, str): return result, None return result return wrapped_check_auth # We need to wrap check_3pid_auth as in the old form it could return # just a str, but now it must return Optional[Tuple[str, Optional[Callable]] if f.__name__ == "check_3pid_auth": async def wrapped_check_3pid_auth( medium: str, address: str, password: str ) -> Optional[Tuple[str, Optional[Callable]]]: # We've already made sure f is not None above, but mypy doesn't do well # across function boundaries so we need to tell it f is definitely not # None. assert f is not None result = await f(medium, address, password) if isinstance(result, str): return result, None return result return wrapped_check_3pid_auth def run(*args: Tuple, **kwargs: Dict) -> Awaitable: # mypy doesn't do well across function boundaries so we need to tell it # f is definitely not None. assert f is not None return maybe_awaitable(f(*args, **kwargs)) return run # If the module has these methods implemented, then we pull them out # and register them as hooks. check_3pid_auth_hook: Optional[CHECK_3PID_AUTH_CALLBACK] = async_wrapper( getattr(provider, "check_3pid_auth", None) ) on_logged_out_hook: Optional[ON_LOGGED_OUT_CALLBACK] = async_wrapper( getattr(provider, "on_logged_out", None) ) supported_login_types = {} # call get_supported_login_types and add that to the dict g = getattr(provider, "get_supported_login_types", None) if g is not None: # Note the old module style also called get_supported_login_types at loading time # and it is synchronous supported_login_types.update(g()) auth_checkers = {} # Legacy modules have a check_auth method which expects to be called with one of # the keys returned by get_supported_login_types. New style modules register a # dictionary of login_type->check_auth_method mappings check_auth = async_wrapper(getattr(provider, "check_auth", None)) if check_auth is not None: for login_type, fields in supported_login_types.items(): # need tuple(fields) since fields can be any Iterable type (so may not be hashable) auth_checkers[(login_type, tuple(fields))] = check_auth # if it has a "check_password" method then it should handle all auth checks # with login type of LoginType.PASSWORD check_password = async_wrapper(getattr(provider, "check_password", None)) if check_password is not None: # need to use a tuple here for ("password",) not a list since lists aren't hashable auth_checkers[(LoginType.PASSWORD, ("password",))] = check_password api.register_password_auth_provider_callbacks( check_3pid_auth=check_3pid_auth_hook, on_logged_out=on_logged_out_hook, auth_checkers=auth_checkers, ) CHECK_3PID_AUTH_CALLBACK = Callable[ [str, str, str], Awaitable[ Optional[Tuple[str, Optional[Callable[["LoginResponse"], Awaitable[None]]]]] ], ] ON_LOGGED_OUT_CALLBACK = Callable[[str, Optional[str], str], Awaitable] CHECK_AUTH_CALLBACK = Callable[ [str, str, JsonDict], Awaitable[ Optional[Tuple[str, Optional[Callable[["LoginResponse"], Awaitable[None]]]]] ], ] GET_USERNAME_FOR_REGISTRATION_CALLBACK = Callable[ [JsonDict, JsonDict], Awaitable[Optional[str]], ] GET_DISPLAYNAME_FOR_REGISTRATION_CALLBACK = Callable[ [JsonDict, JsonDict], Awaitable[Optional[str]], ] IS_3PID_ALLOWED_CALLBACK = Callable[[str, str, bool], Awaitable[bool]] class PasswordAuthProvider: """ A class that the AuthHandler calls when authenticating users It allows modules to provide alternative methods for authentication """ def __init__(self) -> None: # lists of callbacks self.check_3pid_auth_callbacks: List[CHECK_3PID_AUTH_CALLBACK] = [] self.on_logged_out_callbacks: List[ON_LOGGED_OUT_CALLBACK] = [] self.get_username_for_registration_callbacks: List[ GET_USERNAME_FOR_REGISTRATION_CALLBACK ] = [] self.get_displayname_for_registration_callbacks: List[ GET_DISPLAYNAME_FOR_REGISTRATION_CALLBACK ] = [] self.is_3pid_allowed_callbacks: List[IS_3PID_ALLOWED_CALLBACK] = [] # Mapping from login type to login parameters self._supported_login_types: Dict[str, Iterable[str]] = {} # Mapping from login type to auth checker callbacks self.auth_checker_callbacks: Dict[str, List[CHECK_AUTH_CALLBACK]] = {} def register_password_auth_provider_callbacks( self, check_3pid_auth: Optional[CHECK_3PID_AUTH_CALLBACK] = None, on_logged_out: Optional[ON_LOGGED_OUT_CALLBACK] = None, is_3pid_allowed: Optional[IS_3PID_ALLOWED_CALLBACK] = None, auth_checkers: Optional[ Dict[Tuple[str, Tuple[str, ...]], CHECK_AUTH_CALLBACK] ] = None, get_username_for_registration: Optional[ GET_USERNAME_FOR_REGISTRATION_CALLBACK ] = None, get_displayname_for_registration: Optional[ GET_DISPLAYNAME_FOR_REGISTRATION_CALLBACK ] = None, ) -> None: # Register check_3pid_auth callback if check_3pid_auth is not None: self.check_3pid_auth_callbacks.append(check_3pid_auth) # register on_logged_out callback if on_logged_out is not None: self.on_logged_out_callbacks.append(on_logged_out) if auth_checkers is not None: # register a new supported login_type # Iterate through all of the types being registered for (login_type, fields), callback in auth_checkers.items(): # Note: fields may be empty here. This would allow a modules auth checker to # be called with just 'login_type' and no password or other secrets # Need to check that all the field names are strings or may get nasty errors later for f in fields: if not isinstance(f, str): raise RuntimeError( "A module tried to register support for login type: %s with parameters %s" " but all parameter names must be strings" % (login_type, fields) ) # 2 modules supporting the same login type must expect the same fields # e.g. 1 can't expect "pass" if the other expects "password" # so throw an exception if that happens if login_type not in self._supported_login_types.get(login_type, []): self._supported_login_types[login_type] = fields else: fields_currently_supported = self._supported_login_types.get( login_type ) if fields_currently_supported != fields: raise RuntimeError( "A module tried to register support for login type: %s with parameters %s" " but another module had already registered support for that type with parameters %s" % (login_type, fields, fields_currently_supported) ) # Add the new method to the list of auth_checker_callbacks for this login type self.auth_checker_callbacks.setdefault(login_type, []).append(callback) if get_username_for_registration is not None: self.get_username_for_registration_callbacks.append( get_username_for_registration, ) if get_displayname_for_registration is not None: self.get_displayname_for_registration_callbacks.append( get_displayname_for_registration, ) if is_3pid_allowed is not None: self.is_3pid_allowed_callbacks.append(is_3pid_allowed) def get_supported_login_types(self) -> Mapping[str, Iterable[str]]: """Get the login types supported by this password provider Returns a map from a login type identifier (such as m.login.password) to an iterable giving the fields which must be provided by the user in the submission to the /login API. """ return self._supported_login_types async def check_auth( self, username: str, login_type: str, login_dict: JsonDict ) -> Optional[Tuple[str, Optional[Callable[["LoginResponse"], Awaitable[None]]]]]: """Check if the user has presented valid login credentials Args: username: user id presented by the client. Either an MXID or an unqualified username. login_type: the login type being attempted - one of the types returned by get_supported_login_types() login_dict: the dictionary of login secrets passed by the client. Returns: (user_id, callback) where `user_id` is the fully-qualified mxid of the user, and `callback` is an optional callback which will be called with the result from the /login call (including access_token, device_id, etc.) """ # Go through all callbacks for the login type until one returns with a value # other than None (i.e. until a callback returns a success) for callback in self.auth_checker_callbacks[login_type]: try: result = await callback(username, login_type, login_dict) except Exception as e: logger.warning("Failed to run module API callback %s: %s", callback, e) continue if result is not None: # Check that the callback returned a Tuple[str, Optional[Callable]] # "type: ignore[unreachable]" is used after some isinstance checks because mypy thinks # result is always the right type, but as it is 3rd party code it might not be if not isinstance(result, tuple) or len(result) != 2: logger.warning( "Wrong type returned by module API callback %s: %s, expected" " Optional[Tuple[str, Optional[Callable]]]", callback, result, ) continue # pull out the two parts of the tuple so we can do type checking str_result, callback_result = result # the 1st item in the tuple should be a str if not isinstance(str_result, str): logger.warning( # type: ignore[unreachable] "Wrong type returned by module API callback %s: %s, expected" " Optional[Tuple[str, Optional[Callable]]]", callback, result, ) continue # the second should be Optional[Callable] if callback_result is not None: if not callable(callback_result): logger.warning( # type: ignore[unreachable] "Wrong type returned by module API callback %s: %s, expected" " Optional[Tuple[str, Optional[Callable]]]", callback, result, ) continue # The result is a (str, Optional[callback]) tuple so return the successful result return result # If this point has been reached then none of the callbacks successfully authenticated # the user so return None return None async def check_3pid_auth( self, medium: str, address: str, password: str ) -> Optional[Tuple[str, Optional[Callable[["LoginResponse"], Awaitable[None]]]]]: # This function is able to return a deferred that either # resolves None, meaning authentication failure, or upon # success, to a str (which is the user_id) or a tuple of # (user_id, callback_func), where callback_func should be run # after we've finished everything else for callback in self.check_3pid_auth_callbacks: try: result = await callback(medium, address, password) except Exception as e: logger.warning("Failed to run module API callback %s: %s", callback, e) continue if result is not None: # Check that the callback returned a Tuple[str, Optional[Callable]] # "type: ignore[unreachable]" is used after some isinstance checks because mypy thinks # result is always the right type, but as it is 3rd party code it might not be if not isinstance(result, tuple) or len(result) != 2: logger.warning( "Wrong type returned by module API callback %s: %s, expected" " Optional[Tuple[str, Optional[Callable]]]", callback, result, ) continue # pull out the two parts of the tuple so we can do type checking str_result, callback_result = result # the 1st item in the tuple should be a str if not isinstance(str_result, str): logger.warning( # type: ignore[unreachable] "Wrong type returned by module API callback %s: %s, expected" " Optional[Tuple[str, Optional[Callable]]]", callback, result, ) continue # the second should be Optional[Callable] if callback_result is not None: if not callable(callback_result): logger.warning( # type: ignore[unreachable] "Wrong type returned by module API callback %s: %s, expected" " Optional[Tuple[str, Optional[Callable]]]", callback, result, ) continue # The result is a (str, Optional[callback]) tuple so return the successful result return result # If this point has been reached then none of the callbacks successfully authenticated # the user so return None return None async def on_logged_out( self, user_id: str, device_id: Optional[str], access_token: str ) -> None: # call all of the on_logged_out callbacks for callback in self.on_logged_out_callbacks: try: await callback(user_id, device_id, access_token) except Exception as e: logger.warning("Failed to run module API callback %s: %s", callback, e) continue async def get_username_for_registration( self, uia_results: JsonDict, params: JsonDict, ) -> Optional[str]: """Defines the username to use when registering the user, using the credentials and parameters provided during the UIA flow. Stops at the first callback that returns a string. Args: uia_results: The credentials provided during the UIA flow. params: The parameters provided by the registration request. Returns: The localpart to use when registering this user, or None if no module returned a localpart. """ for callback in self.get_username_for_registration_callbacks: try: res = await callback(uia_results, params) if isinstance(res, str): return res elif res is not None: # mypy complains that this line is unreachable because it assumes the # data returned by the module fits the expected type. We just want # to make sure this is the case. logger.warning( # type: ignore[unreachable] "Ignoring non-string value returned by" " get_username_for_registration callback %s: %s", callback, res, ) except Exception as e: logger.error( "Module raised an exception in get_username_for_registration: %s", e, ) raise SynapseError(code=500, msg="Internal Server Error") return None async def get_displayname_for_registration( self, uia_results: JsonDict, params: JsonDict, ) -> Optional[str]: """Defines the display name to use when registering the user, using the credentials and parameters provided during the UIA flow. Stops at the first callback that returns a tuple containing at least one string. Args: uia_results: The credentials provided during the UIA flow. params: The parameters provided by the registration request. Returns: A tuple which first element is the display name, and the second is an MXC URL to the user's avatar. """ for callback in self.get_displayname_for_registration_callbacks: try: res = await callback(uia_results, params) if isinstance(res, str): return res elif res is not None: # mypy complains that this line is unreachable because it assumes the # data returned by the module fits the expected type. We just want # to make sure this is the case. logger.warning( # type: ignore[unreachable] "Ignoring non-string value returned by" " get_displayname_for_registration callback %s: %s", callback, res, ) except Exception as e: logger.error( "Module raised an exception in get_displayname_for_registration: %s", e, ) raise SynapseError(code=500, msg="Internal Server Error") return None async def is_3pid_allowed( self, medium: str, address: str, registration: bool, ) -> bool: """Check if the user can be allowed to bind a 3PID on this homeserver. Args: medium: The medium of the 3PID. address: The address of the 3PID. registration: Whether the 3PID is being bound when registering a new user. Returns: Whether the 3PID is allowed to be bound on this homeserver """ for callback in self.is_3pid_allowed_callbacks: try: res = await callback(medium, address, registration) if res is False: return res elif not isinstance(res, bool): # mypy complains that this line is unreachable because it assumes the # data returned by the module fits the expected type. We just want # to make sure this is the case. logger.warning( # type: ignore[unreachable] "Ignoring non-string value returned by" " is_3pid_allowed callback %s: %s", callback, res, ) except Exception as e: logger.error("Module raised an exception in is_3pid_allowed: %s", e) raise SynapseError(code=500, msg="Internal Server Error") return True