Clarify resource server terminology

[Elisabeth-Ericsson]

What type of PR is this?

• documentation

What this PR does / why we need it:

The document introduces new terminology and explains what a resource server is all about.
A small addition to the description is needed to avoid confusions of the resource server with a server responsible for authorization of access requests.

Changelog input

should be incorporated into release 0.1

Additional documentation

This section can be blank.

docs

[AxelNennker]

Not sure why this clarification is needed.
"The document introduces new terminology and explains what a resource server is all about"
But adding "to user resources" does not contradict my definition of resource server.

OAuth2

resource owner
      An entity capable of granting access to a protected resource.
      When the resource owner is a person, it is referred to as an
      end-user.

   resource server
      The server hosting the protected resources, capable of accepting
      and responding to protected resource requests using access tokens.

[eric-murray]

A definition for "user resource" is also required.

Without that, the definition of "resource server" is meaningless if it is not understood what a "user resource" is in the context of a network API. The concept of data in a database is straightforward, but many network APIs will not simply be pulling data from a database, and may involve dynamic calculations based on network state.

[hdamker]

should be incorporated into release 0.1

Release 0.1 is out of the door, maybe 0.2 is meant here?
But anyway, the changelog input should be something like "Resource Server definition clarified"

[Elisabeth-Ericsson]

should be incorporated into release 0.1

Release 0.1 is out of the door, maybe 0.2 is meant here? But anyway, the changelog input should be something like "Resource Server definition clarified"

oh yes, correct. this is a typ'o meant to say realease 0.2. and thanks for suggesting the change log input; "Resource Server definition clarified"

[AxelNennker]

A definition for "user resource" is also required.

Without that, the definition of "resource server" is meaningless if it is not understood what a "user resource" is in the context of a network API. The concept of data in a database is straightforward, but many network APIs will not simply be pulling data from a database, and may involve dynamic calculations based on network state.

@eric-murray Please suggest text. Are you OK with this PR and can it be merged and you create a new PR regarding user resource explaining why resource server is meaningless without it? Please review.

I think resource server is a well defined thing in OAuth2.

[eric-murray]

So the RFC 6749 makes the same mistake of defining "resource server" in terms of "resource", without defining what a "resource" is:
Resource Server: The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens

I could replace the term "resource" in the definition with "macguffin" and know as much about what a resource server is as I do now:
Resource Server: The server hosting the protected macguffins, capable of accepting and responding to protected macguffin requests using access tokens

And, I have to say that, in the context of network APIs, I don't really know what a "resource" is for several of the CAMARA APIs, so can't really provide a definition. I was hoping that someone who did know would provide that. Otherwise I will continue to regard the "resource server" as "the furthest point an access token gets within the API provider's network", Depending on the implementation, this is not necessarily where the data is stored at all.

[AxelNennker]

For me the resource server in Camara is the API endpoint the client sends the API request too. What happens after that resource server is not "really" our problem. I think that matches the definition of OAuth2 and what OIDC understands as a resource server. I think from the PoV of ICM that is what we care about. Maybe outside ICM there can be more details on macguffin.

[eric-murray]

@AxelNennker
OK, I'm fine with that definition, and that means we don't need a definition of "user resource", because it doesn't really matter what it is.