lms.backend.blackboard.backend

  1# pylint: disable=abstract-method
  2
  3import typing
  4
  5import edq.net.request
  6
  7import lms.backend.blackboard.model
  8import lms.model.backend
  9import lms.model.constants
 10import lms.model.courses
 11import lms.model.users
 12import lms.util.net
 13import lms.util.parse
 14
 15class BlackboardBackend(lms.model.backend.APIBackend):
 16    """ An API backend for the Blackboard Learn LMS. """
 17
 18    def __init__(self,
 19            **kwargs: typing.Any) -> None:
 20        super().__init__(**kwargs)
 21
 22        assert(self.config.backend_type == lms.model.constants.BackendType.BLACKBOARD)
 23
 24        if (self.config.auth_user is None):
 25            raise ValueError("Blackboard backends require a username.")
 26
 27        self.auth_user: str = self.config.auth_user
 28        """
 29        The user to authenticate with.
 30        This is set in config and compied for type checking.
 31        """
 32
 33        if (self.config.auth_password is None):
 34            raise ValueError("Blackboard backends require a password.")
 35
 36        self.auth_password: str = self.config.auth_password.cleartext
 37        """
 38        The (cleartext) password to authenticate with.
 39        This is set in config and compied for type checking.
 40        """
 41
 42        self._session_headers: typing.Union[typing.Dict[str, typing.Any], None] = None
 43        """ The headers (e.g., cookies) for our logged in Blackboard session. """
 44
 45    def reset_connection(self) -> None:
 46        self._session_headers = None
 47
 48    def get_standard_headers(self, write: bool = False) -> typing.Dict[str, str]:
 49        headers = super().get_standard_headers(write)
 50
 51        if (self._session_headers is not None):
 52            headers.update(self._session_headers)
 53
 54        return headers
 55
 56    def _login(self) -> None:
 57        """ Try to login to the Blackboard server. """
 58
 59        # Check if we are already logged in.
 60        if (self._session_headers is not None):
 61            return
 62
 63        response, _ = edq.net.request.make_get(self.server)
 64        cookies, router_params = self._parse_bb_cookies(response.headers.get('set-cookie', None))
 65
 66        new_cookies = {
 67            'BbRouter': cookies['bbrouter']
 68        }
 69
 70        text_cookies = '; '.join(['='.join(items) for items in new_cookies.items()])
 71
 72        headers = {
 73            'cookie': text_cookies,
 74        }
 75        data = {
 76            'user_id': self.auth_user,
 77            'password': self.auth_password,
 78            'blackboard.platform.security.NonceUtil.nonce.ajax': router_params['xsrf'],
 79        }
 80
 81        response, _ = edq.net.request.make_post(self.server + '/webapps/login/',
 82                headers = headers, data = data,
 83                # Don't store the nonce in exchanges.
 84                params_to_skip = ['blackboard.platform.security.NonceUtil.nonce.ajax'],
 85                allow_redirects = False)
 86
 87        cookies, router_params = self._parse_bb_cookies(response.headers.get('set-cookie', None))
 88        if ('sessionId' not in router_params):
 89            raise ValueError(f"Could not log into Blackboard server ({self.server}) with user '{self.auth_user}'. Is username/password correct?")
 90
 91        self._session_headers = {
 92            'cookie': response.headers.get('set-cookie', None),
 93            'x-blackboard-xsrf': router_params['xsrf'],
 94            # Insert a header to identify the user.
 95            'edq-lms-blackboard-user': self.auth_user,
 96        }
 97
 98    def _parse_bb_cookies(self, text_cookies: typing.Union[str, None]) -> typing.Tuple[typing.Dict[str, typing.Any], typing.Dict[str, str]]:
 99        """
100        Parse out the Blackboard cookies and return two dicts:
101         - All cookies (with lower case keys).
102         - The router params/cookies (specific to Blackboard).
103        """
104
105        cookies: typing.Dict[str, typing.Any] = {}
106        router_params: typing.Dict[str, str] = {}
107
108        # If we are testing, return fake cookies.
109        if (self.is_testing()):
110            cookies['bbrouter'] = 'xsrf:abc,sessionId:9999999'
111            router_params['xsrf'] = 'abc'
112            router_params['sessionId'] = '9999999'
113
114            return cookies, router_params
115
116        cookies = lms.util.net.parse_cookies(text_cookies)
117
118        router_text = cookies.get('bbrouter', None)
119        if (isinstance(router_text, str)):
120            for text in router_text.split(','):
121                key, value = text.split(':', maxsplit = 1)
122                router_params[key] = value
123
124        return cookies, router_params
125
126    def courses_list(self,
127            **kwargs: typing.Any) -> typing.List[lms.model.courses.Course]:
128        self._login()
129
130        url = self.server + '/learn/api/public/v3/courses'
131        data = {
132            'availability.available': 'Yes',
133        }
134        response, _ = edq.net.request.make_get(url, headers = self.get_standard_headers(), data = data)
135
136        courses = []
137        for raw_course in response.json().get('results', []):
138            courses.append(lms.backend.blackboard.model.course(raw_course))
139
140        courses.sort()
141
142        return courses
143
144    def courses_users_list(self,
145            course_id: str,
146            **kwargs: typing.Any) -> typing.List[lms.model.users.CourseUser]:
147        parsed_course_id = lms.util.parse.required_int(course_id, 'course_id')
148
149        self._login()
150
151        url = self.server + '/learn/api/public/v1/courses/{course_id}/users'
152        url = url.format(course_id = lms.backend.blackboard.model.format_id(parsed_course_id))
153
154        data = {
155            'expand': 'user',
156        }
157
158        response, _ = edq.net.request.make_get(url, headers = self.get_standard_headers(), data = data)
159
160        users = []
161        for raw_user in response.json().get('results', []):
162            users.append(lms.backend.blackboard.model.course_user(raw_user))
163
164        users.sort()
165
166        return users