medAL-suite documentation

In order to install passport, we had to make slight changes to the laravel version currently used by this server. Originally, the composer.json file had the following version:

json
 "require": {
...
        "laravel/framework": "6.0.*",
...
    },

Which we changed to:

json
"require": {
    ....
        "laravel/framework": "^6.20.26",
    ...
    },

for the passport installation to work properly. After changing the composer.json, run:

composer update
composer require laravel/passport

which will successfully install passport's back-end routes. The routes used for passport are then registered in the AuthServiceProvider.php provider class where we only used the routes necessary for our desired functionality.

In this section, we show how to use the new interface to create health facilities and assign to them devices such as medAL-reader and medAL-hub as well as specific algorithm versions that can fetched by authorized devices.

: new passport feature

To start, login with a user which has the Logistician role (if the database is seeded then there is a default logistician user:
username: logistician@dynamic.com
password: logistician
The main logistician dashboard gives access to the management of health facilities and devices which can be created and edited freely. When creating a medal-hub device, a redirection URL must be specified in order to enroll the device later on. This redirect URL should correspond to the address of the device (+ endpoint TBD) on the local network when registering it.

To assign an existing device to a health facility, head to the health facility management panel and click on the Devices button on the row corresponding to the health facility. A window will open up allowing to assign free devices to this health facility.

Similarly, medAL-*creator* algorithm versions can be assigned to health facilities by clicking the `Algorithms` button on the row corresponding to the health facility. The window will show two dropdown lists where an algorithm and corresponding version can be assigned. When a version is replaced, the older versions will appear in the table below. Note that choosing a version for which a *json* has not been properly generated on the *creator* server will result in an error. <img src=“./assets/assign_versions.png” alt=“ver” style=“zoom:60%;” />

When devices and an algorithm version is assigned to a health facility, devices can request access tokens from the medAL-*data* server in order to authenticate to medAL-*data*'s protected API. The full API is documented in the [Postman Collection](“./device_api.json”)

In order to get a token and a refresh token, the PKCE OAuth flow must be used. For the example above, this can be tested using the postman collection's PKCE request. Head to the Authorization tab in the request and fill out the form such that the urls points to the medAL-*data* server, the Client ID field corresponds to the Auth ID of the device and the Redirect URL should be the same than the one set for the device. To check what redirect URL is assigned to the device, head to the devices tab and click on the `View` button of the corresponding device to show all the details. When the form is filled out in Postman, click on the `Get New Access Token` button to start the PKCE flow which will redirect you to the login page (where you have to login using the user credentials used to create the device). A prompt will ask you to grant access to the device, press `Ok` and then you should receive a token and refresh token.

The protected routes allow devices to: - Upload medical cases (to be integrated still) - Fetch information from the health facility such that the pin code and hub IP - Upload its own device information such as mac address, os etc.. - Fetch the json of the algorithm version that is assigned to this health facility You can try out these routes using the Postman collection replacing the `token` variable with the one received using the PKCE flow.

• medAL-data default logistician user:
  username: logistician@dynamic.com
  password: logistician