Tentative proposal for a RS discovery mechanism

[Denisthemalice]

This proposal is related to the two following issues:

• Protected and Public Resources Protected and Public Resources #185,
• The case of a RS trusting more that one AS The case of a RS trusting more that one AS #187.

A Client must first locally know to which RS it wants to talk to. If the Client has never talked to that RS before,
it SHOULD send an HTTP OPTIONS request to the discovery endpoint of the RS to retrieve the server's discovery information.
The RS MUST respond with a JSON document containing the following information:

discovery_endpoint (string)
REQUIRED. The full URL of the RS's discovery endpoint. The client SHALL verify that it matches with the URL used to query the discovery endpoint.

access_endpoint (string)
REQUIRED. The full URL of the RS's access endpoint.

user_consent_endpoint (string)
OPTIONAL. The full URL of the RS's user consent endpoint. NOTE: this data element is optional to address the case of a single AS trusted by the RS.

interact_method
OPTIONAL. A list of the RS's interaction methods. There are two possibilities:

a) a list authentication methods. This list MAY be present when the RS is willing to authenticate the end-user before any access request can be done.

b) a list of allowed operations. This list MAY be present either when the end-user has not already been authenticated by the RS
or once the end-user has been authenticated.

Note: In the later case, the list of allowed operations is likely to be different whether a strong authentication has or has not already taken place.

For each operation that can be performed at a given point of time, the RS indicates to the client the URLs of the ASs that it trusts
and for each AS which access privileges types should be present into an access token granted by that AS.

token_profile (array strings)
OPTIONAL. A list of the RS's supported token formats and key proofing mechanisms for performing an access.

service_list (array of strings)
OPTIONAL. A list of the RS's supported services. This list MAY be present when the server is supporting a service that can be fulfilled by several servers. For each service, the discovery_endpoint of each server supporting that service should be provided.

[fimbault]

I'm not sure it's for GNAP to deal with that. There's no practical way we can ensure RS implementers would do it anyway.
Of course it doesn't preclude anyone from doing it if they think their RS services benefit from it.

[Denisthemalice]

There are four different topics under the above proposal :

1. The user_consent_endpoint in order to support the end-user consent, which is pretty important for privacy reasons.
2. The interact_method-endpoint. Two philosophies are possible: disclose in advance both the authentication mechanisms, if any, and the authorization mechanisms or only inform the client using a trial and error mechanism. In the later case :

• if error 401 is reported, then the list of the possible authentication mechanisms should be advertised,
• if error 403 is reported then the list of the possible authorization mechanisms should be advertised.

3. The token_profile allows the client to advertise to the AS the access token profiles supported by the RS. This is rather important since this does not mandate anymore any prior relationship between ASs and RSs.

4. The service_list in order to support the forwarding of access token within a set of RSs belonging to the same service.

[jricher]

I believe this to be out of scope. Users do not interact with the RS.

[Denisthemalice]

Hi Justin,

I raised above four different topics. I wonder whether your single line comment applies to the first one or to all of them.

For the user_consent_endpoint, when the client code is not screwed to a single AS (which may be able to support the end-user consent), the RS indicates to the client which ASs are being trusted and for which actions. The "user choices and consent" needs to be done by the end-user once the RS has been first contacted by the client and before any AS is being contacted by the client.

Since the user consent needs to be obtained from the end-user (and not from the client), in my proposal above, I considered a different end-point at the RS able to support a UI interface. There could be different alternatives, but the document cannot remain silent when the user consent is not done at the AS.

For the interact_method-endpoint, I wrote that two philosophies are possible: disclose in advance both the authentication mechanisms, if any, and the authorization mechanisms or only inform the client using a trial and error mechanism. I believe that but philosophies should co-exist.

Since the title of this thread is "Tentative proposal for a RS discovery mechanism", it would be adequate to recall in the document that it is possible for a RS to advertise that a REST API is fully discoverable from the root and with no prior knowledge by doing a GET on the root.

As indicated in [(https://softwareengineering.stackexchange.com/questions/170695/what-is-the-need-for-discoverability-in-a-rest-api-when-the-clients-are-not-ad)] : "Discoverability is not just for clients, it's also useful for software developers."

[jricher]

AS-RS discovery is covered in GNAP-RS created by #246

[Denisthemalice]

This issue has been marked "Pending Close", however its content is fundamental.

@justin You wrote:

AS-RS discovery is covered in GNAP-RS created by #246

This topic of this issue is "Tentative proposal for a RS discovery mechanism" which is fully unrelated
with a AS-RS discovery since it applies to a Client-RS discovery protocol

This issue should not be yet closed