Draft: draft-ietf-gnap-core-protocol

Commentary: Addresses 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-259 - -gnap - core - protocol - editors- 
 I would love to see an example , i.e. a full access request that demonstrates whether / how this interacts with other properties of the request . Also note that this is subtly different from the use of the word " privileges " in the Terminology ( twice ) . 
 the editors discussed the need for adding an example that includes this field and decided we 'd target a separate PR where we could clean up the examples more comprehensively instead of just pasting it in . The terminology alignment is noted , do you think the definitions need to be tweaked a little ? 
 Yes . I 'll review the terminology . 
 The chairs have indicated that is possible to re - open an issue , if it is considered that its has been closed too early . This is the case for the issue ( In practice , only rights are supported but attributes should also be supported ) Denisthemalice opened this issue 2 days ago and wrote : commented 2 days ago I do n't understand the sentence : " Attributes can already be supported by the access structure " . The text states : access ( array of objects / strings ) describes the rights that the client ... The text does not state : access ( array of objects / strings ) describes the attributes and the rights that the client Please , provide details on how user attributes can be supported ( and then which kind of attributes can be supported ) . Please do n't close this issue immediately after replying to it . 
 The chairs have indicated that the group can re - open issues when more discussion is needed . Individuals are not to simply re - open issues when they do n't get the answer they want . This is not productive conversation and driving consensus . This issue has been discussed at length . The access structure can be extended with anything , including an field if that makes sense to the RS being protected . Again , closing this issue as it is re - hashing a previously discussed and closed issue . 
 i do n't like this meta discussion about when tickets can be closed or not , I think it comes at the expense of actually addressing the issue . Denis may be nitpicking here , but I agree that Sec . 3.2.1 is not explicit that the access token may be arbitrarily extended , nor more specifically that it can contain client properties . This may be obvious to the authors , but not to all readers . 
 the contents of the access token are expressly opaque and not defined in the core document , what 's being discussed here is instead the kinds of things that can be asked for .  's question is not about properties of the client in the access token , though those could be included ( and this is a discussion for the  document ) . What 's being requested here is that the client be allowed to ask for attributes as part of its access request -- and I have responded to this many times and I have pointed out the specific text in this comment : Therefore I do believe that this issue and should both be closed . 
 Alternatively , may want to provide a small initial list of attributes , and if we have consensus on them , we could add it ( as optional , of course ) to the access request . 
 that was discussed at length in and closed with by adding the field to the access request and extending the discussion around API - specific claims . 
 Privileges are a function of both the client and the resource ( which is true in general for anything in the access request ) , whereas what I 'm hearing requesting is client ( or user ? ) attributes that are not related to any specific resource . But back to my previous comment , I would like to see more concrete examples before we make any changes . 
 Examples of attributes that are not related to any specific resource are : family name , first name , home address , citizenships , country of birth , date of birth , email addresses . Group memberships : e.g ; golf player member from the Saint - Nom la Bretêche golf course with an handicap of X. This kind of information is considered as personal data and should only be released to the RS with the consent of the user , once the user has been able to be informed for which reason each requested attribute is needed and how it will be used by the RS . 
 It would indeed be useful to have a way for the RS to ask specific attributes from the AS , to be included in the token . Depending on the resource being requested , I might need a name , address and phone number ( for instance for a delivery ) , while other resources may require also the dob or age . This could be included in the  document I believe . User consent in that case is pretty simple . Either it accepts to provide those info ( to be issued by the AS ) , or it ca n't use the resource . If I understand  correctly , he 'd like to get one step further , and enable the client request itself to specify what attributes are requested . While that permits a lot of flexibility ( any attribute can be asked and combined ) , it seems very complex for a user ( or its agent ) to know what is really needed . Which probably explains why Denis wants a discovery step with the RS before that , and why he needs a multi - attribute consent decision making . Considering previous architectural choices ( token being opaque to the client ) , I personally believe this further step is not necessary because it adds a fair amount of complexity ( but again , just a personal opinion ) . 
 You summary is rather good . I would add one step : when the client wants to perform a given operation on a given resource ( since it does not already have an access token available ) , it sends a " Discovery request " to the RS indicating to the RS which operation it wants to perform and on which resource . The RS should first respond by offering a choice to the client for the selection of the AS . To draw a parallel with the current situation , when you want to pay on the web , you can choose to to pay using a VISA card , an Amex card , a MasterCard card , a PayPal account , etc ... Once the AS selection has been done by the client or by the user , the RS informs the client whether either rights or a set of attributes is required , depending how access control is being managed by the  ( respectively , either capabilities or ABAC / RBAC ) . It is at this point of time , that the client can request a " User Notice " to the RS that explains the rational for the use of personal attributes , if they are requested . The user may consent or may abort the operation if he is not satisfied with the rational . ( User Consent ) . So it is a global accept or a global deny . I do n't want to go one step further ( This is a reply to the sentence : " If I understand  correctly , he 'd like to get one step further , " ) Then the client has most ( but not yet all ) of the information it needs to prepare an access token request to the AS . If a capability is required , the client will indicate to the AS which operation it is willing to perform on which resource . If a set of attributes is required , the client will indicate to the AS which attributes types ( and optionally values ) are required . The client will also indicate to the AS to which RS the access token should be targeted . Finally depending upon the application context , the client will indicate which type of " bui " ( binding user identifier ) should be included into the Access token . Independently of this flow of operations , once the user has been successfully authenticated , at any time , he can request to the AS to have a view on which attributes types and values are known to the AS . 
 Closing as duplicate of and other previous issues 
 A few questions / suggestions around section 8 ( Resource Access Rights ): type : considering the constraints ( no collision ) , I believe the term namespace would be better suited . Since we explain a URI is prefered in real life scenarii , we might update the examples accordingly locations singular or plural : what 's the rationale for an array of locations ? Do we see that as a common scenario ( with exactly the same parameters ) ? Would n't a single value fit most cases , as it 's always possible to use multiple access tokens ( 2.1.2 ) anyways ? actions : seems ok . Probably we should update the definition of right to ( instead of operation ) datatypes : seems to me that we should refer to an array of resources ( possibly we could then have types and objects inside , but basic strings seem more generic and simpler ) . Depending on the use case , objects could include identifiers , absolute or relative paths , wildcards and specific semantics . we 're currently missing the possibility to request attributes ( cf ) , which would be an array of strings to refer to groups , roles , etc . ( again here , strings are enough I think , an implementer could always distinguish using an appropriate scheme , ex radmin and gclub in the following example if he really wants to ) . Attributes would be optional . ( I 'm not considering here the domain specific extensions , like geolocation , currency , etc . / btw , should n't this be in a dedicated subsection and not in every example ? ) Example of proposed json for the access request : In the second example , we see that attributes could also be useful to the AS to refer to specific parameters ( ex : my currency is euro , etc . ) . So it 's more generic than what is currently described in section 8 with the financial - transaction example ( which would require a specific understanding of " identifier " ( in my example , ' account-42 " ) and " currency " at the base level of the access struct ) . Of course it would be possible to make a more detailed schema within each field , or thanks to the namespace , but I believe namespace / location / actions / attributes / resources should be the base level , so that we know what to expect ( mandatory and optional fields ) . We also see the request includes a withdraw , which is probably not a legal action for the accountant to do , so that it would be refused by the AS . As usual , the AS MUST validate the information provided by the client . Maybe the user is not an accountant at all , and so he should n't be able to check_statement . When preparing its response , the AS may also include any ambient condition it knows about ( ex : ok you 're an accountant , but you can only view amounts below a threshold , or at the end of the month , or made with some specific counterpart , or whatever ) . 
 Thanks for raising these issues -- from an editor 's standpoint , please note that we are trying to sync discussions about this structure with the RAR extension of OAuth2 , including PRs like this : ; we do n't want the two specs to lose sync . This does n't mean we ca n't change them , but we do need to make sure we have that larger conversation if we do want to change . As an individual : I do n't agree with the proposals here in general , but I see where the points coming from . Some thoughts on each bit : To me , is a more clear indicator as to what 's going on here . implies that it 's something that needs to be resolved and understood , like an directive or a JSONLD context that 's meant to be fetched , parsed , and processed by machine code . That 's not what 's we mean by this field . I do think we 'll have enough cases of multiple locations . We ca n't assume that an API will be structured in any specific way -- the location could be a root server , it could include a path , it could include subdomain hosts , etc . I 'd like to hear more from people with more use cases for this . I personally struggled with the label . I think we run the risk of running too close to " identifying the resource server " from  I ca n't think of another label for " the kinds of things that the API has " , though . An analogous scope set would be the OIDC scopes of , each of which describe a kind of data being requested at the userinfo endpoint . The definition feels way too loose to be useful , to me . I do n't think we want to encourage API designers to just put things into a dump bucket , and instead we want to encourage domain - specific fields to describe things like this . Even in the examples above -- are these attributes of the user , the requested transaction , the resulting data access , the client software , something else , all of the above ? Since it is so easy to create API - specific fields to describe things with actual clear semantics , we should avoid such overly - generic buckets , in my opinion . Also , the proposal in is about " placing things into the access token " , which the client instance has no control over since the " contents " of the access token are between the AS and RS . The client has less insight into what the RS needs than the AS does , since the AS needs to communicate it . The request should instead focus on what the client wants to : do : . 
 Thanks for the feedback . RAR alignment aside ( which I agree is a topic in itself ): maybe is n't the best ( I was using it as in " module namespace " in programming environments , i.e. organize code into logical groups and to prevent name collisions that can occur especially when your code base includes multiple libraries ) , but is n't well suited either ;-) Ex in the RAR document , is not exactly intuitive ( that 's not a type , that 's a process ) . Also , since it is advised to use a URI anyways to disambiguate , I 'm not entirely sure this could n't be used ( in some advanced scenarii ) to fetch / parse some context , that could very well be a way to extend the request . Even if that 's called type . if we have good reasons ( i.e. a recurring need ) to get an array for locations , fine . I do n't see many on my side , and there 's the additional complexity of checking the authorizations for several endpoints , or at least we should include guidance on how this gets processed . A dumb example of risk is that I include a dev and a prod environment , and I just read the first location[0 ] ( say the dev ) to process the request , because " it 's same same ( but different ) " . I think better to force to always process access request by access request . The main point being that the array already allows multiple access token requests , so I do n't see a real rationale for a locations array . The cost is to potentially duplicate the request parameters , so if that happens a lot in business cases , there might be something to do ( passing by reference might help ) . the other label I was thinking about was ( instead of resource or datatypes ) regarding attributes , maybe I 've gone too far with the second example ( and anyway , a request would n't have to include all parameters ) but we ca n't limit the request to rights , there are cases where I just want to say , " hey give me an admin token " , and some of the actions might actually derive from that . 
 To the specific push for attributes : To me , the " give me an admin token " is closer to the definition of than anything else , since it 's aligned with " what I want to do " . Maybe instead of it could be or ? Basically , each field ought to be pretty clear in its intended target , and they should all be as orthogonal to each other as possible . 
 IMO : is related to actions / operations ( " I have the right to read , write , etc . " ) is related to attributes ( " I am an admin , I 'm part of a privileged group , etc . " ) The difference I make between the 2 is that anyone can ask for a right ( of course , to be granted or not ) , but a privilege depends on your identity . So a privilege is kind of a reference in itself ( some external system , ex your company , maps your admin privilege ) . was defined as and was defined as ( of course we could change if we need to clarify the target , we could say that an access token represents a set of rights or privileges ) . In that sense , admin would be fine , but currency would n't be an attribute / privilege , to reuse the examples above . 
 I agree that currency is n't an attribute , and that 's what lead me to the conclusion that above was becoming a catch - all bucket . I would rather see someone define instead of having them try to dump something like that into a " whatever bin " . 
 Yes . Ideally I 'd like my parser to know what to expect at the base level of the access request , and so that would require a predetermined structure that can be typed checked ( of course there can be Optional structs and references ) . That generally leaves open the question of how to handle extensions in the data model ( such as currency , identifier , etc . ) . The problem I see in the current example with currency is that I do n't know how to understand the structure . Unless it 's hard coded in some very specific context , but I do n't want to have to compile a different lib for each situation ( I mean probably I could , but I do n't think I should be forced to do it ) . So to avoid the , we should strictly keep to the definitions , the content of the access request refers to rights / privileges of the user . And most of the debate will be on extensions . If that 's just me , I would probably indeed use the / to introspect what is required . But the spec would leave open how that mapping gets done . 
 This is exactly at the heart of many of the discussions in RAR , including ( but not limited to ) this one : Basically we ca n't predict or decide what a given API 's security structure will look like at the security level ( GNAP ) . So if there 's a definition of the access , then an AS will probably need to know how to parse and handle that . Or the AS could be " naive " and leave the final processing up to the RS , which will need to understand it . But note that this applies to any type because an AS would need to understand what a set of values mean when used together or apart , for example . Since the semantics of ALL structures in the object are defined by its , we can either use domain - specific extensions or core parameters with the same level of understanding . 
 +1 for the suggested resolution in RAR , if the AS ca n't understand ` " namespace / type " : " " ( in my previous example ) I would reject the request . 
 Just thinking out loud . What makes me wonder when I see access requests is that why GNAP uses " accesstoken " for access token requests . My best guess is that OAuth uses " accesstoken " because there is also a " refreshtoken " . GNAP does n't have the latter one , hence , the " access " prefix can be omitted and get a shorter " token " . Does it really need to specify this prefix ? 
 I guess it 's now become a very standard term , and it also qualifies what the token is used for 
 I still think it 's really unnecessary to use instead of in the access request for the same reasons you do n't use prefix for other properties in it . As I was saying before , it 's completely understandable why  has / uses it . It is n't that important thing for me though . 
 Switching the meaning of the words back and forth does not al!ow to progress . access token is defined as a data artifact representing a set of rights and/or attributes attribute is defined as characteristics related to a subject . It is the time now to define a data structure able to to request attributes within an access token . 
 What 's most important is that we are consistent . And so we 'd need to keep the notions at the same level ( rights < -actions , privileges < -attributes ) . If we keep to our definition of attributes ( which refer to the subject ) , there 's no real risk of having a bin holder . Otherwise could be called sub_attr if we want to make it more explicit in the label . Then here 's what I suggest : the definition of access token should talk about rights and privileges and the request would include lower level constructs , actions and attributes , that the AS uses as inputs to the access token 
 : What you suggest is rather different from the current definitions . With your proposal , nobody would know anymore what a privilege is . access token is a data artifact representing a set of rights and/or attributes . rights and/or attributes are privileges . Using " subattr " claims is however a nice proposal , since it would be not possible to have confusion with the " sub " _ claim as currently known in OAuth . 
 Cf above for the distinction I made between rights and privileges , which you also find in . Updated proposal : ( I indicate where there are some question marks with ? ) 
 I think the above conversation is confusing what is represented by the access token and what is returned to the client instance , and that 's dangerous . We are n't just talking about protecting APIs that have information about people , and we need to be very careful that we do n't make that assumption . The access token represents rights of access on a protected resource . There might be other aspects of this that the resource server cares about , such as the identity of the subject the resource represents . But also , there might not be a subject at all , or the subject might be irrelevant to the resource being protected ( say it 's something not related to the RO ) . So to me , the kinds of things being described here are n't attributes of the subject at all . They are a kind of additional dimension to the request , but not attributes . 
 Ok , but this stems from your remark that were too broad . I can understand that now it 's the opposite , but we have to choose . Note also that this array would be optional ( in case it 's irrelevant to the specific request ) . To me they really are attributes , as part of the access request ( whatever the chosen name would be ) . How else would we be able to deal with roles / groups in the access token ? 
 If we wanted to define something for " roles " or " groups " , we could do that explicitly . Or more properly , an API designer could . The core protocol should n't try to pre - define all the different kinds of dimensions that API designers could use , and we do n't want to give the impression that API designers need to cram their security models into the existing fields . We WANT designers to define their own fields and objects . The question then becomes whether the core protocol defines the field or not . The core protocol should only have things with boundaries that are clearly orthogonal to each other but also re - usable and general - purpose . That 's the rubric for action , datatype , location , and identifier to date . You can understand those in a LOT of different kinds of APIs . They are n't universal , but they do n't really overlap and they are n't overly specific to a style of API . Two things come to mind for this : 1 ) Should we formalize our rubric for including a " general purpose " access field ? 2 ) Given what would go into ( 1 ) , what are the other fields we should add ? Do the ones we have already meet those guidelines ? 
 I have n't described a general purpose field . The case described is for roles / groups , which are very usual use cases , even much more than actions . The extension examples I 've put in example 2 above were directly derived from examples currently in the spec . I personally find currency a fairly strange attribute ( why would I enclose that in an authorization ? ) , but since it was there I tried what that could look like . But that 's not something I would see as mainstream , even for openbanking scenarii . OK with the questions . 
 This may not be the proper place to mention this , but I 'm particularly concerned about the use - case where a Resource Server ' API is mandated by regulation or federation . This is prominent in the US healthcare use - case where both the endpoint standards and the publication of the endpoints themselves is regulated in order to avoid " information blocking " . In this context , how does the RS specify the standards and version supported by an endpoint and do they have a way to list exceptions or exclusions for that part of the standard that they do not support . In other words , I 'm hoping for " type " to state a standard and either a positive or negative subscope of the standard . 
 Here is under the control of the AS , not the RS . Probably this requirement is better suited for the RS part of the document ? 
 what I mean by " general purpose field " is exactly what you 're describing here , so I think we 're actually on the same page -- it 's about a field that 's re - usable across many different kinds of APIs . What I want to avoid is GNAP trying to define apriori all these different dimensions of access , and so what I 'm trying to get at is the question of whether the kind of thing you 're describing here is general - enough to merit definition . At the end of the day , whoever defines gets to define all the fields and their meanings , and that 's fully on purpose . It should n't have to make sense to anyone but those calling the API . RS discovery by the client , particularly versioning and compliance , is very much out of scope for GNAP . That said , I 'd anticipate standard API developers to declare a value that is a stable URL . 
 yes I agree we should only define fields which correspond to a mainstream use case . I believe that 's the case here . 
 I took the final messages of this thread . How they relate to the topic of this thread which is " Refactoring the internals of access request " is unclear to me . I fully agree with you when you write : I also agree with you when you write : Some people might think that all the re - usable attributes across many different kinds of APIs have already been defined , such as by OIDC . Unfortunately , this is not the case . Let us give some examples : The attribute with the type " country of citizenship " may be interesting and the end - user should be able to understand it , so that he can decide whether he is willing to release that attribute type ( and value ) to a RS . The same applies to a " date of birth " or to the " country of residence " . If such attribute types are not defined elsewhere , we should define them . But in such a case , an independent document would be better , because other standards could refer to it , without referring to the whole GNAP . 
 Discussed this with the RAR editors , and here 's where that stands : RAR already exists in deployments , meaning a compelling reason for changing a parameter 's name or syntax would be needed should be kept as it 's descriptive enough for what it does should be kept plural as it being singular would limit its use only to a more strict audience restriction , and the strict use is still possible in the current structure adding a new field for level of access makes sense , I propose we call this and propose text for both GNAP and RAR 
 Seems fine to me . 
 and You appear now to understand each other which is fine . The four lines from jricher are a bit obscure for me , but seem to be a way forward . I would be interested to see some text with some examples that explain how groups or roles can be supported , as well as examples where attributes like " country of citizenship " , " date of birth " or " country of residence " can be supported . 
 and would fit into ( based on strings ) . suggested attributes do n't fit very well into that model , because you 'd need both an attribute label ( ex : " country of residence " ) and an attribute value ( ex : " france " ) . If I just give a country or a date , it 's impossible to know the intended use . That said , you could create residence_france as a kind of group if you really want to . But Justin 's argument is to not create a field where people will put everything in it , which is understandable . 
 Right , or you could just define or within your API 's definition , if does n't fit well for what you 're doing . I would be happy to have additional examples with API - specific terms in them . What we have right now was pulled largely from the financial examples in RAR and modified from there . So we could easily do something like : And so on . This would not define or as general - purpose parameters but it would be a good example of how things can work for API designers looking to apply this . If you have some cohesive examples to add , please suggest them either here or in a PR . 
 Yes , that 's always a possibility . Of course the AS and RS will need to agree also on what that specific means . There are lots of such attributes that APIs could use at one point . 
 How would this work in cases where the RS API is based on a regulated standard data model like FHIR R4 ? 
 The AS and RS would always need to agree on waht a specific means though . If they do n't agree then they do n't connect . You would want to have a formal definition of what value to use , what fields it can have , and what those fields mean . A structured data model like FHIR lends itself really well to that , and so you 'd see a profile like HEART had previously defined for OAuth and UMA . 
 Is there any way we could avoid the profiling issue ? ( I was a co - founder of HEART and it had the US regulator and the chair of UMA as co - chairs . I thought we were all set . But nothing useful happened after almost 5 years . ) My point ( from a human rights perspective ) is that the ( US or EU ) regulator interacts with the industry standards group ( HL7 in this case ) as they both do a regulatory capture dance . GNAP should sit out the dance because GNAP is not building anything specific to healthcare vs. finance , etc ... Saying that there will be a profiling group like HEART is , in my experience , a non - starter because it just distracts from the regulator - industry " romance " . 
 Ideally the definition would be handled by the designers of the API , HL7 in this case . That way the data model , API , and security model all can be defined in an intertwined way . For that to happen , HL7 needs to want to target GNAP as part of its security solution . At the time we founded HEART , the FHIR community had not yet landed on OAuth as part of the security layer , and suggesting to do so was seen as novel and frightening to many . I agree that GNAP should stay out of that dance for any specific industry , and the best thing it can do is provide a structure to hang those definitions on . 
 Then the best is probably to avoid industry specific examples ( unlike what RAR is doing ) , and just explain how types can be used to plug extensible datamodels . 
 In issue you wrote : However the title of this issue was : Capabilities only ( i.e. actions ) are supported . ACLs ( i.e. attributes associated with a subject ) should also be supported This goal should not be forgotten . answered to : I have a problem with the always since there exists cases where such an agreement is not needed . An RS would be able to tell to a client that if needs one or more attributes types ( and optionally values ) and/or some capability and if the end - user first accepts to request them to a given AS and if AS is able to provide them , then the access token can be generated and is very likely to be accepted by the RS . No agreement between them would then be necessary . As proposed as examples : The types ctz and dob and much more could be standardized . They are not business specific . For example , a RS could indicate that in order to accept a method , it needs the type ctz or a type with a value : ctz=250 . 
 Closing following the
Paragraph (version B):
The types or levels of privilege being requested at the resource.
For example, a client instance asking for administrative level
access, or access when the resource owner is no longer online.