Merge pull request #11 from benchling/webhook-verification-app-def

Update webhook verification to use new SDK and verify() method

Author: bowenwr

examples/chem-sync-local-flask/README.md

@@ -81,6 +81,7 @@ https://brave-wombats-poke.loca.lt
 2. Ensure you've been granted access to the [Benchling Developer Platform Capability](https://help.benchling.com/hc/en-us/articles/9714802977805-Access-the-Benchling-Developer-Platform).
 3. This example also requires a [Lab Automation](https://www.benchling.com/resources/benchling-lab-automation) license.
 4. [Molecule entities](https://help.benchling.com/hc/en-us/articles/9684254682893-Molecule-entity-overview) will need to be enabled on your tenant.
+5. [Global Apps](https://docs.benchling.com/docs/global-apps-faq) will need to be enabled on your tenant.
 
 ### Upload the App Manifest
 
@@ -158,15 +159,34 @@ Open it in an editor of your choice and set the values with the plaintext client
 for your App. For example:
 
 ```
-CLIENT_ID=42a0cd39-0543-4dd2-af02-a866c97f0c4d
+CLIENT_ID=Ts7jtwPohM
 ```
 
+### Setting App Definition ID
+
+The App definition ID is available from the Developer Console by selecting the App to view.
+
+![image info](./docs/global-app-definition-id.png)
+
+> ℹ️ **Note:** If you do NOT see this ID, please ensure [Global Apps](https://docs.benchling.com/docs/global-apps-faq) are enabled for your tenant.
+
+Add it to your `.env` file with a variable name `APP_DEFINITION_ID`. The contents of your `.env` file should now look something like:
+
+```
+CLIENT_ID=Ts7jtwPohM
+APP_DEFINITION_ID=appdef_Trow4zbR3o
+```
+
+### Restarting the Container to Reflect Environment Changes
+
 Restart the `benchling-app` Docker container to pick up the environment changes.
 
 ```bash
 docker-compose up -d
 ```
 
+### Security Note: Storing App Secrets in Production
+
 > ⚠️ **Security Note:** In production, store the secret with a secure solution such as a secrets store (AWS Secrets Manager, as an example) or, if storing programmatically, encrypted using app-layer encryption. Avoid placing it in plaintext anywhere in code or configuration.
 
 ### Create App Registry Dependencies

examples/chem-sync-local-flask/docker-compose.yaml

@@ -17,6 +17,7 @@ services:
       # Client ID is not sensitive and is the same across all tenants, so could be hard-coded
       # You might choose to have two different Apps for dev vs prod, which would have different client IDs
       - CLIENT_ID
+      - APP_DEFINITION_ID
       # Client secret for the Benchling App, stored somewhere securely in production.
       # Injected here for convenience. Each Client ID will have its own Client secret
       - CLIENT_SECRET_FILE=/run/secrets/app_client_secret

examples/chem-sync-local-flask/docs/global-app-definition-id.png

@@ -1,9 +1,10 @@
 from threading import Thread
 
-from benchling_sdk.apps.helpers.webhook_helpers import verify_app_installation
+from benchling_sdk.apps.helpers.webhook_helpers import verify
 from flask import Flask, request
 
 from local_app.benchling_app.handler import handle_webhook
+from local_app.benchling_app.setup import app_definition_id
 from local_app.lib.logger import get_logger
 
 logger = get_logger()
@@ -20,11 +21,11 @@ def health_check() -> tuple[str, int]:
     @app.route("/1/webhooks/<path:target>", methods=["POST"])
     def receive_webhooks(target: str) -> tuple[str, int]:  # noqa: ARG001
         # For security, don't do anything else without first verifying the webhook
-        app_id = request.json["app"]["id"]  # type: ignore[index]
+        app_def_id = app_definition_id()
 
         # Important! To verify webhooks, we need to pass the body as an unmodified string
         # Flask's request.data is bytes, so decode to string. Passing bytes or JSON won't work
-        verify_app_installation(app_id, request.data.decode("utf-8"), request.headers)
+        verify(app_def_id, request.data.decode("utf-8"), request.headers)
 
         logger.debug("Received webhook message: %s", request.json)
         # Dispatch work and ACK webhook as quickly as possible

examples/chem-sync-local-flask/local_app/app.py

@@ -12,6 +12,20 @@ def init_app_from_webhook(webhook: WebhookEnvelopeV0) -> App:
     return App(webhook.app.id, _benchling_from_webhook(webhook))
 
 
+@cache
+def app_definition_id() -> str:
+    # App definition ID is available to "global" apps. It uniquely identifies the Benchling App
+    # above the tenant context.
+    #
+    # Although it is available via the webhook, for security purposes we choose to supply it with
+    # the App's code to avoid reusing elements of the webhook's data payload as part of its verification.
+    # For ease of setup, we retrieve it from an environment variable.
+    # You could choose to simply leave it in code like `return "appdef_SpzX0d5oDA"`.
+    app_def_id = os.environ.get("APP_DEFINITION_ID")
+    assert app_def_id is not None, "Missing APP_DEFINITION_ID from environment"
+    return app_def_id
+
+
 def _benchling_from_webhook(webhook: WebhookEnvelopeV0) -> Benchling:
     return Benchling(webhook.base_url, _auth_method())
 

examples/chem-sync-local-flask/local_app/benchling_app/setup.py

@@ -3,8 +3,6 @@ manifestVersion: 1
 info:
   name: Sample Sync App
   version: 0.1.0
-settings:
-  lifecycleManagement: MANUAL
 features:
   - name: Sync Step
     id: sync_step

examples/chem-sync-local-flask/manifest.yaml

@@ -1,3 +1,3 @@
-flask~=3.0.0
+flask~=3.0.2
 # Cryptography extra needed for webhook verification
-benchling-sdk[cryptography]==1.10.0
+benchling-sdk[cryptography]==1.11.0

examples/chem-sync-local-flask/requirements.txt

@@ -4,7 +4,7 @@ target-version = "py311"
 line-length = 110
 
 select = ["ALL"]
-ignore = ["D100", "D101", "D103", "D104", "EM101", "EM102", "S101", "TRY003"]
+ignore = ["D100", "D101", "D103", "D104", "EM101", "EM102", "S101", "TRY003", "TRY301"]
 
 [per-file-ignores]
 "**/tests/*" = ["ANN001", "ANN101", "D102", "PLR2004"]

examples/chem-sync-local-flask/ruff.toml

@@ -3,7 +3,7 @@
 import pytest
 from benchling_sdk.apps.framework import App
 
-from local_app.benchling_app.setup import _auth_method, init_app_from_webhook
+from local_app.benchling_app.setup import _auth_method, app_definition_id, init_app_from_webhook
 from tests.helpers import load_webhook_json
 
 _TEST_FILES_PATH = Path(__file__).parent.parent.parent.parent / "files/webhooks"
@@ -13,6 +13,7 @@ class TestBenchlingAppSetup:
 
     def setup_method(self) -> None:
         _auth_method.cache_clear()
+        app_definition_id.cache_clear()
 
     def test_init_app_from_webhook(self, monkeypatch) -> None:
         webhook = load_webhook_json(_TEST_FILES_PATH / "canvas_initialize_webhook.json")
@@ -35,3 +36,14 @@ def test_init_app_from_webhook_missing_client_secret_file(self, monkeypatch) ->
             context.setenv("CLIENT_ID", "clientId")
             with pytest.raises(AssertionError, match="Missing CLIENT_SECRET_FILE from environment"):
                 init_app_from_webhook(webhook)
+
+    def test_app_definition_id(self, monkeypatch) -> None:
+        with monkeypatch.context() as context:
+            context.setenv("APP_DEFINITION_ID", "app_def1234")
+            result = app_definition_id()
+            assert result == "app_def1234"
+
+    def test_app_definition_id_missing_app_definition_id(self, monkeypatch) -> None:
+        with (monkeypatch.context(),
+              pytest.raises(AssertionError, match="Missing APP_DEFINITION_ID from environment")):
+            app_definition_id()

examples/chem-sync-local-flask/tests/unit/local_app/benchling_app/test_setup.py

@@ -28,10 +28,14 @@ def client(app: Flask) -> FlaskClient:
 class TestApp:
 
     @patch("local_app.app._enqueue_work")
-    @patch("local_app.app.verify_app_installation")
-    def test_app_receive_webhook(self, mock_verify_app_installation, mock_enqueue_work, client) -> None:
+    @patch("local_app.app.app_definition_id")
+    @patch("local_app.app.verify")
+    def test_app_receive_webhook(
+            self, mock_verify, mock_app_definition_id, mock_enqueue_work, client,
+    ) -> None:
         webhook = load_webhook_json(_TEST_FILES_PATH / "canvas_initialize_webhook.json")
         response = client.post("1/webhooks/canvas", json=webhook.to_dict())
         assert response.status_code == 200
-        mock_verify_app_installation.assert_called_once()
+        mock_verify.assert_called_once()
+        mock_app_definition_id.assert_called_once()
         mock_enqueue_work.assert_called_once()