bocconi-sdk 0.2.0__py3-none-any.whl

bocconi/__init__.py

@@ -0,0 +1,48 @@
+"""Unofficial Python SDK for Bocconi University student services.
+
+One SAML2 SSO login (idp.unibocconi.it) unlocks all subsystems:
+
+  * :mod:`bocconi.youatb`     — yoU@B portal (SignalR widgets, calendar,
+    profile/careers) and the Esse3 "PuntoBlu" student area
+  * :mod:`bocconi.blackboard` — Blackboard Learn Ultra (courses, deadlines,
+    messages, announcements, activity stream)
+
+Quickstart::
+
+    from bocconi import BocconiClient
+
+    with BocconiClient("1234567", "secret") as client:
+        client.login()
+        client.youatb.dashboard()
+        client.blackboard.courses()
+
+Reverse-engineered from the live services; see youatb-docs.md in the
+sibling ``youatb_re`` project for the full protocol write-up. Unofficial,
+not affiliated with Università Bocconi.
+"""
+
+from . import blackboard, youatb
+from .client import BocconiClient
+from .exceptions import (
+    AuthenticationError,
+    InvalidCredentials,
+    SessionExpiredError,
+    SignalRError,
+    WidgetError,
+    YouAtBError,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "BocconiClient",
+    "youatb",
+    "blackboard",
+    # errors
+    "YouAtBError",
+    "AuthenticationError",
+    "InvalidCredentials",
+    "SessionExpiredError",
+    "SignalRError",
+    "WidgetError",
+]

bocconi/auth.py

@@ -0,0 +1,217 @@
+"""SAML2 Web-SSO login against the Bocconi Shibboleth IdP.
+
+Implements the flow documented in youatb-docs.md §2/§5:
+
+    GET <SP protected URL>            -> 302 chain to idp.unibocconi.it
+    GET  IdP login page               -> form with `execution` webflow token
+    POST j_username/j_password        -> 200 auto-submit form (SAMLResponse)
+    POST SAMLResponse to SP ACS URL   -> 302 back, SP session cookies set
+
+No JavaScript is executed; the auto-submit forms are parsed and replayed.
+"""
+
+from __future__ import annotations
+
+import html as _html
+import logging
+import re
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+from typing import Dict, List, Optional
+from urllib.parse import urljoin
+
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    InvalidCredentials,
+    SessionExpiredError,
+)
+
+log = logging.getLogger(__name__)
+
+IDP_HOST = "idp.unibocconi.it"
+
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36"
+)
+
+_CRED_FAIL_RE = re.compile(
+    r"loginfailed|credentials not recognized|login failed|password.*incorrect",
+    re.IGNORECASE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Minimal HTML form extraction (stdlib only)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HtmlForm:
+    action: str = ""
+    method: str = "get"
+    inputs: Dict[str, str] = field(default_factory=dict)
+
+
+class _FormParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.forms: List[HtmlForm] = []
+        self._current: Optional[HtmlForm] = None
+
+    def handle_starttag(self, tag: str, attrs) -> None:
+        attrs = dict(attrs)
+        if tag == "form":
+            self._current = HtmlForm(
+                action=attrs.get("action", ""),
+                method=attrs.get("method", "get").lower(),
+            )
+        elif tag == "input" and self._current is not None:
+            name = attrs.get("name")
+            if name:
+                self._current.inputs[name] = attrs.get("value", "")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "form" and self._current is not None:
+            self.forms.append(self._current)
+            self._current = None
+
+
+def extract_forms(html_text: str) -> List[HtmlForm]:
+    parser = _FormParser()
+    parser.feed(html_text)
+    return parser.forms
+
+
+def _find_saml_form(html_text: str) -> Optional[HtmlForm]:
+    """Find an auto-submit SAML form.
+
+    Two kinds occur in Bocconi SSO flows:
+      * ``SAMLResponse`` — IdP -> SP (the common case, POST binding response)
+      * ``SAMLRequest``  — SP  -> IdP (POST binding *request*; Blackboard's
+        ``/auth-saml/saml/login`` uses this instead of a 302 redirect)
+    """
+    for form in extract_forms(html_text):
+        if "SAMLResponse" in form.inputs or "SAMLRequest" in form.inputs:
+            return form
+    return None
+
+
+def _find_password_form(html_text: str) -> Optional[HtmlForm]:
+    for form in extract_forms(html_text):
+        if "j_password" in form.inputs or "j_username" in form.inputs:
+            return form
+    return None
+
+
+# ---------------------------------------------------------------------------
+# SAML plumbing
+# ---------------------------------------------------------------------------
+
+def complete_saml_posts(
+    session: requests.Session,
+    response: requests.Response,
+    max_hops: int = 10,
+) -> requests.Response:
+    """Replay auto-submit SAML forms until a real page is reached.
+
+    Handles both directions of the POST binding: IdP->SP ``SAMLResponse``
+    forms (youatb, www.pb, app, ...) and SP->IdP ``SAMLRequest`` forms
+    (Blackboard's ``/auth-saml/saml/login``).
+    """
+    for _ in range(max_hops):
+        form = _find_saml_form(response.text)
+        if form is None:
+            return response
+        action = urljoin(response.url, _html.unescape(form.action))
+        log.debug("SAML POST -> %s", action)
+        response = session.post(action, data=form.inputs, timeout=30)
+    raise AuthenticationError("Too many SAML redirect hops")
+
+
+def has_session_cookie(session: requests.Session) -> bool:
+    """True if the jar holds a session marker of any known Bocconi service."""
+    markers = (".ASPXAUTH", "BbRouter", "samlCookie")
+    return any(
+        c.name in markers or c.name.startswith("_shibsession_")
+        for c in session.cookies
+    )
+
+
+def login(
+    session: requests.Session,
+    entry_url: str,
+    username: str,
+    password: str,
+) -> requests.Response:
+    """Perform a full username/password login starting from any SP entry URL.
+
+    Works for the yoU@B portal (``https://youatb.unibocconi.it/``) as well as
+    for SPs that emit the SAMLRequest via POST binding, e.g. Blackboard
+    (``https://blackboard.unibocconi.it/ultra/institution-page``): the chain
+    eventually reaches the IdP password form either way.
+
+    Returns the final authenticated response.
+
+    Raises:
+        InvalidCredentials: the IdP rejected the credentials.
+        AuthenticationError: any other flow failure.
+    """
+    log.info("Opening %s", entry_url)
+    resp = session.get(entry_url, timeout=30)
+    resp = complete_saml_posts(session, resp)
+
+    pw_form = _find_password_form(resp.text)
+    if pw_form is None:
+        # No login form: either already authenticated (existing IdP session
+        # silently SSO'd us in) or something unexpected happened.
+        if has_session_cookie(session):
+            log.info("Authenticated via existing IdP SSO session")
+            return resp
+        raise AuthenticationError(
+            f"No login form found and no session established (final URL: {resp.url})"
+        )
+
+    action = urljoin(resp.url, _html.unescape(pw_form.action))
+    payload = dict(pw_form.inputs)  # keep any hidden webflow fields
+    payload["j_username"] = username
+    payload["j_password"] = password
+    payload["_eventId_proceed"] = ""
+    log.info("Posting credentials to %s", action)
+    resp = session.post(action, data=payload, timeout=30)
+
+    if "SAMLResponse" not in resp.text:
+        if _CRED_FAIL_RE.search(resp.text) or _find_password_form(resp.text):
+            raise InvalidCredentials("IdP rejected the username/password")
+        raise AuthenticationError(
+            f"Unexpected IdP response (no SAMLResponse, URL: {resp.url})"
+        )
+
+    resp = complete_saml_posts(session, resp)
+
+    if not has_session_cookie(session):
+        raise AuthenticationError(
+            "SAML flow completed but no session cookie was set by the SP"
+        )
+    log.info("Login successful")
+    return resp
+
+
+def ensure_service_session(
+    session: requests.Session,
+    url: str,
+) -> requests.Response:
+    """GET a protected URL on any Bocconi SP, completing SSO if needed.
+
+    With a live IdP session this is silent: the SP bounces us to the IdP and
+    straight back with a fresh SAMLResponse. Raises SessionExpiredError if the
+    IdP asks for credentials again.
+    """
+    resp = session.get(url, timeout=30)
+    resp = complete_saml_posts(session, resp)
+    if IDP_HOST in resp.url and _find_password_form(resp.text):
+        raise SessionExpiredError(
+            "IdP SSO session expired; call YouAtBClient.login() again"
+        )
+    return resp

bocconi/blackboard/__init__.py

@@ -0,0 +1,26 @@
+"""Blackboard Learn Ultra subsystem: courses, deadlines/to-dos, messages,
+announcements, activity stream."""
+
+from .client import (
+    BbAnnouncement,
+    BbCalendar,
+    BbCalendarItem,
+    BbConversation,
+    BbCourse,
+    BbTodo,
+    BbTodoItem,
+    BbUser,
+    BlackboardClient,
+)
+
+__all__ = [
+    "BlackboardClient",
+    "BbUser",
+    "BbCourse",
+    "BbConversation",
+    "BbAnnouncement",
+    "BbCalendarItem",
+    "BbCalendar",
+    "BbTodo",
+    "BbTodoItem",
+]