Authorization

Introduction

Some operations/requests may be restricted to certain users/applications (henceforth referred to as the client). This is based on properties (also called claims) that the client has been assigned by the identity provider used for authentication. 

Receiving a HTTP response with status code 403 (Forbidden) means that the client making the request is not authorized based on these properties.

For more information regarding the initial configuration of authorization rules please refer to the relevant page here: Configuration WebTSM Services Authorization

Types of Operations

In general, operations are separated in the following groups:

• Read operations - any operation/request which returns existing data
• Write operations - aside from modifying data, this also includes creating new objects such as time series
• Delete operations - any request which permanently removes existing data

Authorization Information and Ownership

The information specifying which types of operations a client is authorized to perform consists of three parts:

1. Owner claim
2. Rule claim
3. The set of operations the rule allows. (Read/Write/Delete)

Owner Claim

Clients (users or applications) with this claim may modify the rule itself.

Rule Claim

This specifies which clients (users or applications) the authorization rule applies to.

Claims

As stated before, authorization is granted to a client based on so called claims or properties assigned to the client when authenticating.

Claims are defined by three properties themselves:

1. The issuer of the claim - usually the unique URL of the identity provider which was used to authenticate the user.
2. The type of the claim - this identifies the type of the property that the claim describes, such as the first name, email address, etc.
3. The value of the claim - the actual value as a string.

Example:

Let's consider a user has been authenticated by signing in using Microsoft AzureAD. The user may then be assigned a claim which looks like this:

In this case, the claim has been issued by Microsofts login service as identified by the URL above. The claim type is "sub" which is short for "subject" and is a common claim type meant to be a unique trait of the identity within the identity provider. In this case, the user is identified by the GUID in the last column.

It is important to note that different identity providers may use different claim types as well as concepts and naming schemes to manage their identities. While there are some very common and often unambiguous claim types such as "sub", "email" or "preferred_username", some claim types may have different meanings to different identity providers. Some may also refer to the same concept by a different name (consider the claim type "group" vs. "role"). Therefore, which claim types to use for authorization depends on the environment, the configured identity providers, etc. and may require some coordination with the WebTSM Services operator.

Let's look at another claim:

In this case, the user was authenticated using the identity provider integrated in the WebTSM Services found under the given URL (please refer to the information on the integrated identity provider under Authentication for details).

The claim type "role" means that the user has been assigned a role by the identity provider, specifically the role "Administrator".

Claim Values and Their Meanings

An important note should be taken that the value of a claim is usually a simple string value with no semantics inherently attached.

Consider the example above where a user has the role "Administrator". While this may imply that the user has specific privileges, it does not inherently do so. The WebTSM Services do not know what an "Administrator" is, what it means or how to translate this into a set of operations the user is allowed to perform. Assuming the identity provider was run by an Italian operator, it may have the value "Amministratore" instead.

The Curious Case of the Claim Type ISS

Note that all authenticated clients have at least one claim with a specific claim type: "iss". This claim basically specifies who authenticated the user and is equal to the issuer of all the other claims. This claim may be used to assign specific authorization to any client authenticated by a specific identity provider.

Authorization and Authentication

It may be helpful to look at the claims a specific user or application has in order to find out why that client is forbidden from performing an operation.

This can be done by accessing

GET /auth/current-id

Which will return something like this:

{
  "sub": "2",
  "preferred_username": "JayDee",
  "family_name": "Doe",
  "given_name": "Jane",
  "email": "jane.doe@example.com",
  "role": ["Administrator","Developers"],
  "aud": "HAKOM WebTSM Services",
  "token_usage": "access_token",
  "jti": "384b27cd-84be-4ff2-8a21-d3bba24e57e7",
  "scope": [
    "openid",
    "email",
    "profile"
  ],
  "azp": "HAKOM WebTSM Services",
  "nbf": 1594983528,
  "exp": 1594987128,
  "iat": 1594983528,
  "iss": "http://localhost:52245/DEV/api"
}

Which is basically the content of the JWT token issued by the identity provider.

This would translate to the following claims:

Any one of these claims may be used to control what Jane is allowed to do. (Some like "iat" may not make much sense, but it could be done nonetheless.)

Managing Authorization

Several endpoints exist to allow or disallow certain clients to perform certain operations.

The way this is done is by creating, modifying or deleting entries stored in each repository which contain

1. claim the rule is owned by
2. claim the rule applies to
3. operations permitted

In JSON format, such an entry would look like this:

{
	"Owner": {
    	"iss": "http://localhost:52245/DEV/api",
    	"type":  "sub", 
    	"value": "2"
    },
    "Claim": {
    	"iss": "http://localhost:52245/DEV/api",
    	"type":  "email", 
        "value": "jane.doe@example.com"
	},
    "Read": true,
    "Write": true,
	"Delete": false
}

Modifying this entry would require the client to have the claim:

Currently, this entry defines that any user with the claim

may perform read or write operations but may not delete anything.

Let's assume there is a second entry that looks like this:

{
	"Owner": {
    	"iss": "http://localhost:52245/DEV/api",
    	"type":  "sub", 
    	"value": "2"
    },
    "Claim": {
    	"iss": "http://localhost:52245/DEV/api",
    	"type":  "preferred_username", 
        "value": "JayDee"
	},
    "Read": true,
    "Write": true,
	"Delete": true
}

Note that the our example user Jane Doe now has two authorization rules apply to her. One allows only reading and writing, the second one also allows deleting data.

In such a case, Jane will be granted read write and delete access. This goes to show that when multiple authorization rules apply to a client, access given by one rule cannot be revoked by another.

For further information regarding the requests for managing authorization rules, please refer to the API reference:  Open API Reference

Restrictions on Repositories

• No access - the client is forbidden from accessing any data in the repository.
• Read only access - the client may read data from the repository but is forbidden from changing it in any way.
• Read/Write access - in addition to reading data from the repository, the client may also write to the repository. Note that this still restricts any ability to delete data.
• Read/Write/Delete access - the client may not only read and modify data but also remove existing items from the repository.

Note that other - less common - combinations are very much possible and may have their own use cases. For example, a simple sensor device could be given write access only.

Managing Authorization on Repositories

This is done by creating, updating or deleting entries under

/authorization/repositories

For details, please refer to the API reference: Open API Reference

Restrictions on Specific Objects

Operations on specific types of objects (i.e. time series, attributes, units) as well as individual items of these types can - as of version 3.8.5 - not be restricted individually. This may change in the future. Feedback is welcome.