:right-sidebar: True AuthDomain =================================================================== .. currentmodule:: gi.repository.Soup .. class:: AuthDomain(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Soup.AuthDomainBasic`, :class:`~gi.repository.Soup.AuthDomainDigest` Server-side authentication. A :obj:`~gi.repository.Soup.AuthDomain` manages authentication for all or part of a :obj:`~gi.repository.Soup.Server`\. To make a server require authentication, first create an appropriate subclass of :obj:`~gi.repository.Soup.AuthDomain`\, and then add it to the server with :obj:`~gi.repository.Server.add_auth_domain`\. In order for an auth domain to have any effect, you must add one or more paths to it (via :obj:`~gi.repository.AuthDomain.add_path`\). To require authentication for all ordinary requests, add the path ``"/"``\. (Note that this does not include the special ``"*"`` URI (eg, "OPTIONS *"), which must be added as a separate path if you want to cover it.) If you need greater control over which requests should and shouldn't be authenticated, add paths covering everything you *might* want authenticated, and then use a filter (:obj:`~gi.repository.AuthDomain.set_filter` to bypass authentication for those requests that don't need it. Methods ------- .. rst-class:: interim-class .. class:: AuthDomain :no-index: .. method:: accepts(msg: ~gi.repository.Soup.ServerMessage) -> str | None Checks if ``msg`` contains appropriate authorization for ``domain`` to accept it. Mirroring :obj:`~gi.repository.AuthDomain.covers`\, this does not check whether or not ``domain`` *cares* if ``msg`` is authorized. This is used by :obj:`~gi.repository.Soup.Server` internally and is probably of no use to anyone else. :param msg: a :obj:`~gi.repository.Soup.ServerMessage` .. method:: add_path(path: str) -> None Adds ``path`` to ``domain``\. Requests under ``path`` on ``domain``\'s server will require authentication (unless overridden by :obj:`~gi.repository.AuthDomain.remove_path` or :obj:`~gi.repository.AuthDomain.set_filter`\). :param path: the path to add to ``domain`` .. method:: challenge(msg: ~gi.repository.Soup.ServerMessage) -> None Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to ``msg``\. It requests that the client authenticate, and sets ``msg``\'s status accordingly. This is used by :obj:`~gi.repository.Soup.Server` internally and is probably of no use to anyone else. :param msg: a :obj:`~gi.repository.Soup.ServerMessage` .. method:: check_password(msg: ~gi.repository.Soup.ServerMessage, username: str, password: str) -> bool Checks if ``msg`` authenticates to ``domain`` via ``username`` and ``password``\. This would normally be called from a [callback``AuthDomainGenericAuthCallback``\]. :param msg: a :obj:`~gi.repository.Soup.ServerMessage` :param username: a username :param password: a password .. method:: covers(msg: ~gi.repository.Soup.ServerMessage) -> bool Checks if ``domain`` requires ``msg`` to be authenticated (according to its paths and filter function). This does not actually look at whether ``msg`` *is* authenticated, merely whether or not it needs to be. This is used by :obj:`~gi.repository.Soup.Server` internally and is probably of no use to anyone else. :param msg: a :obj:`~gi.repository.Soup.ServerMessage` .. method:: do_accepts(self, msg: ~gi.repository.Soup.ServerMessage, header: str) -> str :param msg: :param header: .. method:: do_challenge(self, msg: ~gi.repository.Soup.ServerMessage) -> str :param msg: .. method:: do_check_password(self, msg: ~gi.repository.Soup.ServerMessage, username: str, password: str) -> bool :param msg: :param username: :param password: .. method:: get_realm() -> str Gets the realm name associated with ``domain``\. .. method:: remove_path(path: str) -> None Removes ``path`` from ``domain``\. Requests under ``path`` on ``domain``\'s server will NOT require authentication. This is not simply an undo-er for :obj:`~gi.repository.AuthDomain.add_path`\; it can be used to "carve out" a subtree that does not require authentication inside a hierarchy that does. Note also that unlike with :obj:`~gi.repository.AuthDomain.add_path`\, this cannot be overridden by adding a filter, as filters can only bypass authentication that would otherwise be required, not require it where it would otherwise be unnecessary. :param path: the path to remove from ``domain`` .. method:: set_filter(filter: ~typing.Callable[[~gi.repository.Soup.AuthDomain, ~gi.repository.Soup.ServerMessage, ~typing.Any], bool], filter_data: ~typing.Any = None) -> None Adds ``filter`` as an authentication filter to ``domain``\. The filter gets a chance to bypass authentication for certain requests that would otherwise require it. Eg, it might check the message's path in some way that is too complicated to do via the other methods, or it might check the message's method, and allow GETs but not PUTs. The filter function returns :const:`True` if the request should still require authentication, or :const:`False` if authentication is unnecessary for this request. To help prevent security holes, your filter should return :const:`True` by default, and only return :const:`False` under specifically-tested circumstances, rather than the other way around. Eg, in the example above, where you want to authenticate PUTs but not GETs, you should check if the method is GET and return :const:`False` in that case, and then return :const:`True` for all other methods (rather than returning :const:`True` for PUT and :const:`False` for all other methods). This way if it turned out (now or later) that some paths supported additional methods besides GET and PUT, those methods would default to being NOT allowed for unauthenticated users. You can also set the filter by setting the SoupAuthDomain:filter and :obj:`~gi.repository.Soup.AuthDomain.props.filter_data properties`\, which can also be used to set the filter at construct time. :param filter: the auth filter for ``domain`` :param filter_data: data to pass to ``filter`` .. method:: set_generic_auth_callback(auth_callback: ~typing.Callable[[~gi.repository.Soup.AuthDomain, ~gi.repository.Soup.ServerMessage, str, ~typing.Any], bool], auth_data: ~typing.Any = None) -> None Sets ``auth_callback`` as an authentication-handling callback for ``domain``\. Whenever a request comes in to ``domain`` which cannot be authenticated via a domain-specific auth callback (eg, [callback``AuthDomainDigestAuthCallback``\]), the generic auth callback will be invoked. See [callback``AuthDomainGenericAuthCallback``\] for information on what the callback should do. :param auth_callback: the auth callback :param auth_data: data to pass to ``auth_callback`` Properties ---------- .. rst-class:: interim-class .. class:: AuthDomain :no-index: .. attribute:: props.filter :type: ~typing.Callable[[~gi.repository.Soup.AuthDomain, ~gi.repository.Soup.ServerMessage, ~typing.Any], bool] The type of the None singleton. .. attribute:: props.filter_data :type: ~typing.Any The type of the None singleton. .. attribute:: props.generic_auth_callback :type: ~typing.Callable[[~gi.repository.Soup.AuthDomain, ~gi.repository.Soup.ServerMessage, str, ~typing.Any], bool] The type of the None singleton. .. attribute:: props.generic_auth_data :type: ~typing.Any The type of the None singleton. .. attribute:: props.proxy :type: bool The type of the None singleton. .. attribute:: props.realm :type: str The type of the None singleton. Virtual Methods --------------- .. rst-class:: interim-class .. class:: AuthDomain :no-index: .. method:: do_accepts(msg: ~gi.repository.Soup.ServerMessage, header: str) -> str :param msg: :param header: .. method:: do_challenge(msg: ~gi.repository.Soup.ServerMessage) -> str Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to ``msg``\. It requests that the client authenticate, and sets ``msg``\'s status accordingly. This is used by :obj:`~gi.repository.Soup.Server` internally and is probably of no use to anyone else. :param msg: a :obj:`~gi.repository.Soup.ServerMessage` .. method:: do_check_password(msg: ~gi.repository.Soup.ServerMessage, username: str, password: str) -> bool Checks if ``msg`` authenticates to ``domain`` via ``username`` and ``password``\. This would normally be called from a [callback``AuthDomainGenericAuthCallback``\]. :param msg: a :obj:`~gi.repository.Soup.ServerMessage` :param username: a username :param password: a password Fields ------ .. rst-class:: interim-class .. class:: AuthDomain :no-index: .. attribute:: parent_instance