Managing Authentication & Authorization
Concepts and Theory

OAuth 2.0 (Open Authorization) is an authorization framework that allows third-party applications to grant access to a user's resources without sharing their credentials. It is widely used for secure delegated access to resources across web applications and APIs.

Check it

Navigate to the interactive documentation at: /docs

You will see something like this:

Authorize

You already have a shiny new "Authorize" button.
And your path operation has a little lock in the top-right corner that you can click.

And if you click it, you have a little authorization form to type a username and password (and other optional fields):

The password flow

The password "flow" is one of the ways ("flows") defined in OAuth2, to handle security and authentication.

OAuth2 was designed so that the backend or API could be independent of the server that authenticates the user.

But in this case, the same application will handle the API and the authentication.

So, let's review it from that simplified point of view:

• The user types the username and password in the frontend, and hits Enter.
• The frontend (running in the user's browser) sends that username and password to a specific URL in our API (declared with tokenUrl="Login").
• The API checks that username and password, and responds with a "token"
  • A "token" is just a string with some content that we can use later to verify this user.
  • Normally, a token is set to expire after some time.
    • So, the user will have to log in again at some point later.
    • And if the token is stolen, the risk is less. It is not like a permanent key that will work forever (in most of the cases).
• The frontend stores that token temporarily somewhere.
• The user clicks in the frontend to go to another section of the frontend web app.
• The frontend needs to fetch some more data from the API.
  • But it needs authentication for that specific endpoint.
  • So, to authenticate with our API, it sends a header Authorization with a value of Bearer plus the token.
    Foe example: if the token contains foobar, the content of the Authorization header would be: Bearer foobar.

SensorThings Roles and Permissions

In istSOS4 users have specific roles which define their access permissions.
Permissions are managed trough database privileges to access specific tables of the Sensorthings schema.
Therefore each role has a set of privileges that define the level of access granted to specific tables in the system.
The following table outlines the different defined roles and their corresponding permissions.

Role	Description	Table Permissions
admin	Have all the privileges	All PRIVILEGES on all tables of sensorthings schema
viewer	Only view capabilities	SELECT privilege on all tables
editor	Can do everything except defining users	SELECT privilege on all tables INSERT, UPDATE, DELETE privileges on all tables (except User table)
obs_manager	Can view everything and manage observations	SELECT privilege on all tables INSERT, UPDATE, DELETE privileges on Observation table INSERT privilege on FeaturesOfInterest table UPDATE privilege on Datastream table
sensor	Can view everything and only insert new observations	SELECT privilege on all tables INSERT privilege on Observation and FeaturesOfInterest tables UPDATE privilege on Datastream table

Authentication

After authenticating in the system, you will see it like:

Create a Thing

Login as a Viewer!

If you do not have the necessary privileges, you will see the following error message:

{
  "code": 401,
  "type": "error",
  "message": "Insufficient privileges."
}

Now logout, login as editor and try again to create a Thing!

Retrieve data (Authorization)

To access the data, navigate to the interactive documentation at: /Things.

If you have sufficient privileges to access this table, you will receive the data, such as:

{
  "@iot.as_of": "2024-12-10T13:36:56Z",
  "value": [
    {
      "@iot.id": 1,
      "@iot.selfLink": "http://localhost:8018/istsos4/v1.1/Things(1)",
      "Locations@iot.navigationLink": "http://localhost:8018/istsos4/v1.1/Things(1)/Locations",
      "HistoricalLocations@iot.navigationLink": "http://localhost:8018/istsos4/v1.1/Things(1)/HistoricalLocations",
      "Datastreams@iot.navigationLink": "http://localhost:8018/istsos4/v1.1/Things(1)/Datastreams",
      "name": "thing name 1",
      "description": "thing 1",
      "properties": {
        "reference": "1"
      },
      "Commit@iot.navigationLink": "http://localhost:8018/istsos4/v1.1/Things(1)/Commit(1)"
    },
  ]
}

If you click the lock icon to log out and attempt the same operation again, you will receive an HTTP 401 error with the following response:

{
  "detail": "Not authenticated"
}