Authentication & Authorization

BEdita is a multi-application system: it is designed to handle different client applications requests performed by multiple users on the same project.

For every request application and user roles should be identified: each application may have its own grants, and each user also depending on role assignement.

As a general rule: anonymous read operations are absolutely possibile, for write operations at least the user performing the request must be identified.

To handle these scenarios please have a look at Security configuration and set blockAnonymousUsers or blockAnonymousApps flags accordingly.

Authentication

User authentication

User authentication is performed using JWT standard. You may have a look a the official JWT introduction for a more detailed explanation of the standard.

Basically JWT enables a token based authentication flow using an access token to access resources and an opaque refresh token to renew the access token.

See Authentication /auth endpoint documentation on how you can retrieve the JWT tokens with a standard username and password user authentication. Once the token is retrieved it can be used on every request in the Authorization HTTP header this way:

Authorization: Bearer <token>

Application identification

Client applications instead are identified using a simple API KEY mechanism. Through Administration /admin endpoint it’s possible to set and retrieve an API KEY for each application registered for a project.

On each request you may set the application’s API KEY using the X-Api-Key HTTP header

X-Api-Key: <api-key>

We prefer to talk about application identification instead of authentication because it’s a weak authentication system: web or mobile client applications may expose this api key, or at least secrecy is not guaranteed. This is somehow similar to implicit grant in OAuth2.

The only real authentication is user authentication: you must rely on that for a secure authentication.

Authorization

Once user and application performing a request are identified, also as anonymous, the requested operation may or may not be allowed depending on the outcome of the following checks:

  • anonymous user and application settings: depending on Security configuration anonymous requests can be blocked with 401 or 403 responses

  • endpoint permissions: each endpoint may allow or deny a request from a user using a client application

  • object permissions: at the most granular level a single object may or may not be accessible or modifiable to the requesting user and application

Endpoint permissions

Operation grants on endpoints can be controlled through a set of rules involving roles, applications and permission types.

Possible values for endpoint, role and application in these rules are:

  • endpoint endpoint id or NULL for every endpoint

  • role role id or NULL for every role or anonymous user

  • application application id or NULL for every application

Instead permission type may have four different values for read operations (GET) or write operations (POST, PATCH, DELETE):

  • false (0b00): no permissions granted

  • true (0b11): full permissions granted

  • mine (0b01): permissions granted only on my resources, i.e. resources belonging to the autenticated user

  • block (0b10): no permissions granted, and override all other permissions

The first two bit, starting from right, are for the read operations (GET) and the other two for the write operations (POST, PATCH, DELETE):

  • (0b0000): false for read [characters 00 on the right] and false for write [characters 00 in the middle, shifting by 2 positions]

The relative integer number is used on the permission type column.

To better understand how these rules work an example is given below:

endpoint

role

application

permission

documents

NULL

ios-app

int 5  (0b0101) write: mine - read: mine

documents

manager

backend

int 15 (0b1111) write: true - read: true

payments

app

NULL

int 10 (0b1010) write: block - read: block

events

reader

web-app

int 12 (0b1100) write: true - read: false

  • for every role (NULL) on /documents endpoint through ios-app application only resources belonging to authenticated user may be read and written

  • users with manager role accessing /documents with backend application are able to read and modify write every resource

  • users with app role accessing /payments with every application are not allowed to read or write anything

  • users with reader role on /events usgin web-app application have a read-only access

See Administration /admin endpoint reference on how you may set these permission rules.

Keep in mind that altough powerful these rules must be applied very carefully like firewall network rules: it is quite easy to cause unintended side effects like blocking every operation or allow dangerous ones.

Object permissions

This feature is not yet implemented.

OAuth2

And what about OAuth2? BEdita is an OAuth2 compliant server solution.