proposal to improve the documentation

[i-work-at-ait]

The target of FIWARE are developers.
--Carlos Rally

i am part of the team conducting a security audit of the HYPERRIDE project, a project that is using some components of the FIWARE platform.
the researchers responsible for documenting HYPERRIDE's IdM system used a lot of Keyrock's documentation, hence also copied most of the documentation's ambiguities (e.g. HYPERRIDE ICT platform specification, page 24).

i am arguing, that in order to correctly implement a system around such a crucial core component (i.e. IdM), the users/developers must first understand the system's components.
this requires easy to follow documentation.

in my opinion the documentation for the Keyrock component could use some improvements (see below).

looking forward reading from you,
kind regards,

dominik

main entities within Keyrock

Users:

    Have a registered account in Keyrock.

    Can manage organizations and register applications.

Organizations:

    Are group of users that share resources of an application (roles and permissions).

    Users can be members or owners (manage the organization).

Applications:

    has the client role in the OAuth 2.0 architecture and will request protected user data.

    Are able to authenticate users using their Oauth credentials (ID and secret) which unequivocally identify the application

    Define roles and permissions to manage authorization of users and organizations

    Can register Pep Proxy to protect backends.

    Can register IoT Agents.

• what is meant with "resources of an application (roles and permissions)"?
  as i understand it, it's the user's resources that are requested by an application; it's not the application's resources.

• what is meant with "[applications] [a]re able to authenticate users using their Oauth credentials (ID and secret) which unequivocally identify the application"?
  it's not the application's job to authenticate users; this is the responsibility of the IdM.
  the OAuth2 client (i.e. application) has a client ID and secret; why should the user authenticate herself with this set of credentials?

• what is meant with "[applications] [d]efine roles and permissions to manage authorization of users and organizations"?
  only the administrator (or in this case the user herself) should be able to define roles and permissions.

• what is meant with "[applications] [c]an register Pep Proxy to protect backends"?
  does it mean an application can register at the PEP Proxy to gain access to protected backends?

in the meantime i would propose describing the entities within Keyrock as follows:

• User
  • In terms of OAuth2 this is the resource owner.
  • Has an account in Keyrock.
  • Registers applications.
• Organization
  • A group of users that share some resources.
  • A user can be an ordinary member or an owner of an organization.
• Application
  • In terms of OAuth2 this is a client.
  • Requests access to users' protected resources.
  • Registers IoT agents.

authorization vs. authentication

i am missing some words of warning in the documentation section about "Connecting to the IdM with OAuth2.0".

OAuth2 is not an authentication protocol but a framework for authorization.
a relying party (i.e. OAuth2 client), having obtained an access token, has no guarantee about the identity of the user (i.e. OAuth2 resource owner).
an OAuth2 access token solely conveys the following: "some resource owner has authorized me to access her/his resources".

as not all Keyrock users will be aware of the differences between authorization and authentication, i am of the opinion that the documentation should clearly mention this.

security implications when using specific OAuth2 grant types

the documentation describes the different OAuth2 grants Keyrock is supporting.
this includes the Implicit Grant and the Client Credentials Grant.
descriptions for these grant types should inform any potential user/developer about the implications (on the system's as well as the user's security).
in particular, i am missing some words of warning against the use of those grant types in modern applications.

in addition to the missing warning, the wording in the discription of the Implicit Grant (i am aware that this is copied from the RFC), suggest that this might be the only grant type suitable for JavaScript applicaitons (i.e. SPA):

The implicit grant is a simplified authorization code flow optimized for clients implemented in a browser using a scripting language such as JavaScript.

the Client Credential Grant type works by exchanging the client ID and secret with an access token.
how will an access token obtained via this grant type ensure authentication of the user?

Proof Key for Code Exchange by OAuth Public Clients (PKCE)

will Keyrock support PKCE in the future?
looking at the documentation as well as in the code i could not find any references to PKCE.
aparently i'm not alone with this question as this open issue from 2020 shows.