Beamline Groups & Filtering

docs/auth.md

@@ -1,6 +1,4 @@
-# Authentication and authorization
-
-## Authentication
+# Authentication
 
 `py-ispyb` relies on plugins to handle different methods of authenticating users to the system. There are some mechanisms that are implemented natively like LDAP, keycloak and dummy that can be used out-of-the-box. However, it is worth noting that anyone can write his own plugin.
 
@@ -189,33 +187,3 @@ class MyAuthentication(AbstractAuthentication):
 
     ...
 ```
-
-### Authorization dependencies
-
-The following dependencies can be used to manage authentication and authorization rules.
-
-#### `permission_required(operator, [permissions])`
-
-Makes the route only accessible to users with the **specified permissions**.
-
-- `operator` is either
-  - `"any"` User should have **any** of the specified permissions
-  - `"all"` User should have **all** of the specified permissions
-
-#### `proposal_authorisation`
-
-Verifies that the user is **associated to the requested proposal**. To do so, it uses the `proposal_id` parameter.
-User must verify any of the following conditions :
-
-- `Person.personId = Proposal.personId`
-- `Person.personId = ProposalHasPerson.personId and ProposalHasPerson.proposalId = Proposal.proposalId`
-- _has permission_ `all_proposals`
-
-#### `session_authorisation`
-
-Verifies that the user is **associated to the requested session**. To do so, it uses the `session_id` parameter.
-User must verify any of the following conditions :
-
-- `Person.personId = Session_has_Person.personId and Session_has_Person.sessionId = BLSession.sessionId`
-- `BLSession.proposalId = Proposal.proposalId and Person.personId = Proposal.personId`
-- _has permission_ `all_sessions`

docs/authorization.md

@@ -0,0 +1,92 @@
+# Proposal(s), Session(s), and related entities
+
+Authorization is applied to all user facing resources in py-ISPyB and different permissions are available to grant users and staff access to entities related to the core of ISPyB. These include but not limited to:
+
+- Proposal
+- Protein, Crystal, BLSample, Shipping, LabContact
+- BLSession, DataCollectionGroup, DataCollection
+
+etc ...
+
+The authorization rules are applied in four ways:
+
+### Users
+
+- A user can access entities related to a Proposal and the DataCollection(s) in which they are a member of one or more Session(s) [linked via SessionHasPerson]. _This is an intrinsic permission and is the default behaviour if the user has no other permissions._
+- A user can access entities related to all Session(s) in a Proposal [linked via ProposalHasPerson]
+
+### Administrators
+
+- An administrator can view all Sessions on a Proposal for specific beamline(s) via a `BeamLineGroup` permission
+- An administrator can access all Sessions and Proposals via `all_proposals`
+
+## BeamLineGroups
+
+Beamline groups provide a way to grant access to all Proposals, Sessions and related entities to a set of staff members for a particular group of beamlines.
+
+For example:
+
+```json
+"beamLineGroups": [
+    {
+        "groupName": "BL0x",
+        "uiGroup": "mx",
+        "permission": "bl0_admin",
+        "beamlines": [
+            {"beamLineName": "BL01"},
+            {"beamLineName": "BL02"},
+        ],
+    },
+]
+```
+
+A staff member with the `bl0_admin` permission will be able to access Proposal(s) and Session(s) allocated on beamlines `BL01` and `BL02`, but not other beamlines. `uiGroup` specifies how this group should be rendered in the UI.
+
+# Permissions
+
+Routes can require a specific permission by using the `permission` dependency.
+
+```python
+from pyispyb.dependencies import permission
+
+
+@router.get(
+    "/path",
+)
+def get_something(depends: bool = Depends(permission("my_permission"))):
+    ...
+```
+
+# Deprecated Authorization Mechanisms
+
+These functions are deprecated and currently only used in the legacy API resources. They should not be used for new developments.
+
+## Authorization dependencies
+
+The following decorators can be used to manage authentication and authorization rules.
+
+### `permission_required(operator, [permissions])`
+
+Makes the route only accessible to users with the **specified permissions**.
+
+- `operator` is either
+  - `"any"` User should have **any** of the specified permissions
+  - `"all"` User should have **all** of the specified permissions
+
+### `proposal_authorisation`
+
+Verifies that the user is **associated to the requested proposal**. To do so, it uses the `proposal_id` parameter.
+User must verify any of the following conditions :
+
+- `Person.personId = Proposal.personId`
+- `Person.personId = ProposalHasPerson.personId and ProposalHasPerson.proposalId = Proposal.proposalId`
+- _has permission_ `all_proposals`
+
+### `session_authorisation`
+
+Verifies that the user is **associated to the requested session**. To do so, it uses the `session_id` parameter.
+User must verify any of the following conditions :
+
+- `Person.personId = Session_has_Person.personId and Session_has_Person.sessionId = BLSession.sessionId`
+- `BLSession.proposalId = Proposal.proposalId and Person.personId = Proposal.personId`
+- _has permission_ `all_sessions`

mkdocs.yml

@@ -1,11 +1,12 @@
 site_name: py-ISPyB
 nav:
   - Home: index.md
-  - Get started: run.md
+  - Get Started: run.md
   - Tests: tests.md
   - Configuration: conf.md
-  - Authentication and authorization:
-      - Basics: auth.md
+  - Authentication and Authorization:
+      - Authentication: auth.md
+      - Authorization: authorization.md
       - Permissions: permissions.md
   - Routes:
       - About: routes.md

pyispyb/app/extensions/database/definitions.py

@@ -1,3 +1,4 @@
+import logging
 from typing import Optional, Any
 
 import sqlalchemy
@@ -7,6 +8,8 @@
 from pyispyb.app.globals import g
 from pyispyb.app.extensions.database.middleware import db
 
+logger = logging.getLogger(__name__)
+
 _session = sqlalchemy.func.concat(
     models.Proposal.proposalCode,
     models.Proposal.proposalNumber,
@@ -19,38 +22,6 @@
 ).label("proposal")
 
 
-def get_blsession(session: str) -> Optional[models.BLSession]:
-    return (
-        db.session.query(models.BLSession)
-        .join(models.Proposal)
-        .filter(_session == session)
-        .first()
-    )
-
-
-def with_auth_to_session(
-    query: "sqlalchemy.orm.Query[Any]", column: "sqlalchemy.Column[Any]"
-) -> "sqlalchemy.orm.Query[Any]":
-    """Join relevant tables to authorise right through to SessionHasPerson
-
-    in case of not being admin, can be reused"""
-    return (
-        query.join(models.Proposal, column == models.Proposal.proposalId)
-        .join(
-            models.BLSession, models.BLSession.proposalId == models.Proposal.proposalId
-        )
-        .join(
-            models.SessionHasPerson,
-            models.BLSession.sessionId == models.SessionHasPerson.sessionId,
-        )
-        .join(
-            models.Person,
-            models.SessionHasPerson.personId == models.Person.personId,
-        )
-        .filter(models.Person.login == g.login)
-    )
-
-
 def get_current_person(login: str) -> Optional[models.Person]:
     person = (
         db.session.query(models.Person)
@@ -70,3 +41,103 @@ def get_current_person(login: str) -> Optional[models.Person]:
     person._metadata["permissions"] = permissions
 
     return person
+
+
+def with_authorization(
+    query: "sqlalchemy.orm.Query[Any]",
+    includeArchived: bool = False,
+    proposalColumn: "sqlalchemy.Column[Any]" = None,
+    joinBLSession: bool = True,
+) -> "sqlalchemy.orm.Query[Any]":
+    """Apply authorization to a query
+
+    Checks in the following order:
+        * `all_proposals` allowing access to everything
+        * checks if the user is in a beamLineGroup to allow access to all proposals on a beamline
+        * checks ProposalHasPerson
+        * falls back to SessionHasPerson allowing access to entities related to where the
+            user is registered on a session
+
+    Kwargs:
+        includeArchived: whether to exclude archived beamlines
+        proposalColumn: the column used to join to `models.Proposal`, will force a join with `models.Proposal`
+        joinBLSession: whether to join `models.BLSession`
+        joinSessionHasPerson: whether to join `models.SessionHasPerson`
+    """
+    # Avoid circular import
+    from pyispyb.app.main import app
+
+    # `all_proposals`` can access all sessions
+    if "all_proposals" in g.permissions:
+        logger.info("user has `all_proposals`")
+        return query
+
+    # Iterate through users permissions and match them to the relevant groups
+    beamLines = []
+    permissions_applied = []
+    for group in app.db_options.beamLineGroups:
+        if group.permission in g.permissions:
+            permissions_applied.append(group.permission)
+            for beamLine in group.beamLines:
+                if (beamLine.archived and includeArchived) or not includeArchived:
+                    beamLines.append(beamLine.beamLineName)
+
+    if proposalColumn:
+        query = query.join(
+            models.Proposal, models.Proposal.proposalId == proposalColumn
+        )
+
+    if joinBLSession:
+        query = query.outerjoin(
+            models.BLSession, models.BLSession.proposalId == models.Proposal.proposalId
+        )
+
+    conditions = []
+    if beamLines:
+        logger.info(
+            f"filtered to beamlines `{beamLines}` with permissions `{permissions_applied}`"
+        )
+
+        conditions.append(models.BLSession.beamLineName.in_(beamLines))
+
+    # Sessions
+    sessions = db.session.query(models.SessionHasPerson.sessionId).filter(
+        models.SessionHasPerson.personId == g.personId
+    )
+    sessions = [r._asdict()["sessionId"] for r in sessions.all()]
+    conditions.append(models.BLSession.sessionId.in_(sessions if sessions else []))
+
+    # Proposals
+    proposals = db.session.query(models.ProposalHasPerson.proposalId).filter(
+        models.ProposalHasPerson.personId == g.personId
+    )
+    proposals = [r._asdict()["proposalId"] for r in proposals.all()]
+    conditions.append(models.Proposal.proposalId.in_(proposals if proposals else []))
+
+    query = query.filter(sqlalchemy.or_(*conditions))
+    return query
+
+
+def groups_from_beamlines(beamLines: list[str]) -> list[list]:
+    """Get uiGroups from a list of beamlines"""
+    from pyispyb.app.main import app
+
+    groups = []
+    for beamline in beamLines:
+        for group in app.db_options.beamLineGroups:
+            for groupBeamline in group.beamLines:
+                if beamline == groupBeamline.beamLineName:
+                    groups.append(group.uiGroup)
+
+    return list(set(groups))
+
+
+def beamlines_from_group(beamLineGroup: str) -> list[str]:
+    """Get a list of beamlines from a groupName"""
+    from pyispyb.app.main import app
+
+    for group in app.db_options.beamLineGroups:
+        if group.groupName == beamLineGroup:
+            return [beamline.beamLineName for beamline in group.beamLines]
+
+    return []

pyispyb/app/extensions/database/utils.py

@@ -1,3 +1,4 @@
+import enum
 import os
 import time
 import logging
@@ -17,45 +18,46 @@
 def order(
     query: "sqlalchemy.orm.Query[Any]",
     sort_map: dict[str, "sqlalchemy.Column[Any]"],
-    order: str,
-    default: Optional[list[str]] = None,
-    order_by: Optional[str] = None,
+    order: Optional[dict[str]],
+    default: Optional[dict[str]] = None,
 ) -> "sqlalchemy.orm.Query[Any]":
-    """Sort a result set by a field
+    """Sort a result set by a column
 
     Args:
         query (sqlalchemy.query): The current query
         sort_map (dict): A mapping of field(str) -> sqlalchemy.Column
-
-    Kwargs:
-        order_by (str): Field to sort by
-        order (Order): Asc or desc
+        order (dict): { order_by: column, order: Asc or desc }
 
     Returns
         query (sqlalchemy.orm.Query): The ordered query
     """
-    if not (order_by and order) and not default:
+    if not (order["order_by"] and order["order"]) and not default:
         return query
 
+    logger.info(f"Ordering by {order['order_by']} {order['order']}")
+
     if default:
-        order_by = default[0]
-        order = default[1]
+        return query.order_by(
+            getattr(sort_map[default["order_by"]], default["order"])()
+        )
 
-    if order_by not in sort_map:
-        logger.warning(f"Unknown order_by {order_by}")
+    if order["order_by"].value not in sort_map:
+        logger.warning(f"Unknown order_by {order['order_by']}")
         return query
 
-    return query.order_by(getattr(sort_map[order_by], str(order))())
+    return query.order_by(
+        getattr(sort_map[order["order_by"].value], order["order"].value)()
+    )
 
 
 def page(
-    query: "sqlalchemy.orm.Query[Any]", skip: int, limit: int
+    query: "sqlalchemy.orm.Query[Any]", *, skip: int, limit: int
 ) -> "sqlalchemy.orm.Query[Any]":
     """Paginate a `Query`
 
     Kwargs:
-        per_page (str): Number of rows per page
-        page (str): Page number to display
+        skip (str): Offset to start at
+        limit(str): Number of items to display
 
     Returns
         query (sqlalchemy.orm.Query): The paginated query
@@ -101,6 +103,17 @@ def with_metadata(
     return parsed
 
 
+def update_model(model: any, values: dict[str, any]):
+    """Update a model with new values including nested models"""
+    for key, value in values.items():
+        if isinstance(value, dict):
+            update_model(getattr(model, key), value)
+        else:
+            if isinstance(value, enum.Enum):
+                value = value.value
+            setattr(model, key, value)
+
+
 ENABLE_DEBUG_LOGGING = False