: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` :Constructors: :: AuthDomain(**properties) 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 ``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:: 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[[...], bool], *filter_data: ~typing.Any) -> 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[[...], bool], *auth_data: ~typing.Any) -> 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, ``AuthDomainDigestAuthCallback``), the generic auth callback will be invoked. See ``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[[...], bool] The ``AuthDomainFilter`` for the domain. .. attribute:: props.filter_data :type: None Data to pass to the ``AuthDomainFilter``. .. attribute:: props.generic_auth_callback :type: ~typing.Callable[[...], bool] The ``AuthDomainGenericAuthCallback``. .. attribute:: props.generic_auth_data :type: None The data to pass to the ``AuthDomainGenericAuthCallback``. .. attribute:: props.proxy :type: bool Whether or not this is a proxy auth domain. .. attribute:: props.realm :type: str The realm of this auth domain. 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 ``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