Design Guidelines should provide guidance about sinkCredentials in returned/retrieved subscription objects

[hdamker]

Problem description

The Subscription object within the event-subscription-template contains the (optional) attribute sinkCredentials. The CAMARA Design Guidelines do not contain a guidance how to use this attribute if the object is used in responses or retrievals.

The object structure is based on 0.1-wip, which contains the paragraph:

Implementations SHOULD NOT include secrets contained in this map when the subscription object is enumerated or retrieved. Secrets SHOULD be write-only. Tokens, passphrases, and passwords are such secrets and account identifiers might be considered secrets as well.

Expected action

A guidance should be added to the Design Guidelines of CAMARA about the handling of sinkCredentials, potentially even more strict than the above paragraph (e.g. "Secrets MUST be write-only").

Additional context

[jlurien]

This issue is commented also in camaraproject/QualityOnDemand#349, for test definitions: * Should sinkCredential be returned as part of SessionInfo and ProvisioningInfo responses?

The current proposal does not mandate that sinkCredential is returned if provided in the request, but does not fail if returned

[bigludo7]

The current proposal does not mandate that sinkCredential is returned if provided in the request, but does not fail if returned

@jlurien should we craft a SubscriptionOut object (or any other name) in the yaml without the sinkCredential attributes and use this one for POST & GET response?

[patrice-conil]

We can also return a 201 with a reference to the created subscription in the Location header... which is the common way to handle resource creation in REST.
To retrieve all other information, using GET is mandatory and we need a scheme without sinkCredential for this purpose.

[bigludo7]

@jlurien, @hdamker, @PedroDiez, @eric-murray, @shilpa-padgaonkar, other contributors,

2 proposals "on the table"

Proposal 1: In the POST response we send back the 201 as proposed above by @patrice-conil. For the GET response we did not send back the sinkCredential

Proposal 2: In the POST response we send back the 200 and the response did no send back the sink credential. This is this representation that is send back in GET response.

Both work for us - any comment/recommendation from the communities

[PedroDiez]

Let me check during this week @bigludo7

[PedroDiez]

My view on this:

POST /subscriptions:

• SYNC MODE: POST response we send back the 201 with only "id" (required) in response body
• ASYNC MODE: POST response we send back the 202 with only "id" (optional) in response body

Then in GET endpoints provide full subscription resource info, taking out sinkCredentials info (is information generated by API CLIENT so it is their responsability to store and it is stored by API Server -Telco Operator- and its responsability to store and manage accordingly during subscription lifecycle). Therefore with this basis no need to return in GET responses sinkCredentials info

[whut]

+1. Especially with the sinkCredentials of type "access token" and "refresh token". Those tokens you can obtain by executing some OAuth flow, here probably the Client Credential Grant flow. You are not simply given the token, this is not OAuth then, but some sort of twisted API Key.