idnits 2.17.1 draft-pinkas-gnap-core-protocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (19 August 2021) is 981 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7525 (ref. 'BCP195') (Obsoleted by RFC 9325) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 D. Pinkas 3 Internet-Draft DP Security Consulting 4 Intended status: Standards Track 5 Expires: 20 February 2022 19 August 2021 7 Grant Negotiation and Authorization Protocol 8 draft-pinkas-gnap-core-protocol-00 10 Abstract 12 This protocol enables an Authorization Server (AS) to issue access 13 tokens to permit an end-user using a client software to perform 14 operations on a protected resource hosted by a Resource Server (RS). 15 These access tokens allow to support capabilities and/or user 16 attributes. 18 The protocol includes means of specifying how the end-user can 19 potentially be involved in an interactive fashion during the 20 process. The client and/or the RS will use these interaction 21 mechanisms to involve the end-user, as necessary, to take decisions. 23 The protocol uses HTTPS for all communications between the client 24 and the AS, as well as between the client and the RS. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six 37 months and may be updated, replaced, or obsoleted by other documents 38 at any time. It is inappropriate to use Internet-Drafts as 39 reference material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on 20 February 2022. 43 Copyright Notice 45 Copyright (c) 2021 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your 52 rights and restrictions with respect to this document. Code 53 Components extracted from this document must include Simplified BSD 54 License text as described in Section 4.e of the Trust Legal 55 Provisions and are provided without warranty as described in the 56 Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . .3 62 1.2. Vocabulary . . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.3. Abbreviations . . . . . . . . . . . . . . . . . . . . . . .4 64 1.4. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . .4 65 1.5. Trust relationships . . . . . . . . . . . . . . . . . . . .6 66 1.6. Prior arrangements before the protocols can be used . . . .8 67 1.7. Short term and long term user accounts . . . . . . . . . . 8 68 1.8. Structure of an access token . . . . . . . . . . . . . . . 8 69 1.8.1. Signed part of an access token . . . . . . . . . . . . 9 70 1.8.2. Unsigned part of an access token . . . . . . . . . . 10 71 1.9. Mandatory checks to be done by a RS on an access token . .11 72 2. An overview of the protocols . . . . . . . . . . . . . . . . .12 73 2.1. RS and AS Discovery APIs . . . . . . . . . . . . . . . . .13 74 2.1.1. RS Discovery API . . . . . . . . . . . . . . . . . . .13 75 2.1.2. AS Discovery API . . . . . . . . . . . . . . . . . . .14 76 2.2. Queries from an end-user to an AS . . . . . . . . . . . . 14 77 2.3. Creation a long-term user account on a RS . . . . . . . . 15 78 2.3.1. The RS already "knows" the end-user . . . . . . . . . 15 79 2.3.2. The RS does not already "know" the user . . . . . . . 18 80 2.4. Creation a short-term user account on a RS . . . . . . . .19 81 2.5. Operation on a resource hosted by a RS . . . . . . . . . .20 82 2.5.1. Operation on a resource without an access token . . . 20 83 2.5.2. Operation on a resource using an access token . . . . 22 84 2.5.2.1. Dialogue between the end-user and his client . . .22 85 2.5.2.2. Dialogue between the end-user and the RS . . . . 23 86 2.5.2.3. The access token request . . . . . . . . . . . . .24 87 2.5.2.4. The access token response . . . . . . . . . . . . 26 88 2.6. Flow of operations for one access . . . . . . . . . . . . 26 89 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 90 4. Security Considerations . . . . . . . . . . . . . . . . . . . 27 91 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . .28 92 5.1. Privacy Considerations for both ABAC and CABC . . . . . . 29 93 5.1.1. Privacy Considerations for ABAC . . . . . . . . . . . 30 94 5.1.2. Privacy Considerations for CBAC . . . . . . . . . . . 30 95 5.2. Privacy Considerations between RSs . . . . . . . . . . . .31 96 5.3. Privacy Considerations between the end-user and the AS . .31 97 5.3.1. Transparency . . . . . . . . . . . . . . . . . . . . . .31 98 5.3.2. Hiding to the AS the URL of the RS and its use . . . . .31 99 6. References . . . . . . . . . . . . . . . . . . . . . . . . . .32 100 6.1. Normative References . . . . . . . . . . . . . . . . . . .32 101 6.2. Informative References . . . . . . . . . . . . . . . . . .33 103 1. Introduction 105 This protocol allows end-users to interact with a piece of software, 106 the client instance, to request access tokens to Authorization 107 Servers (ASs) to perform operations either on protected resources 108 hosted by a Resource Server (RS) or on the RS itself to create a 109 user account. 111 The protocol also allows end-users to collect from an AS information 112 about themselves. 114 When an end-user is willing to perform an operation on a protected 115 resource hosted by a RS or on the RS itself to create a user 116 account, the end-user operating the client interacts with the RS to 117 assert his consent, authenticates to the AS and then requests an 118 access token from the AS. 120 The protocol allows to support Attribute Based Access Control 121 (ABAC), as well as Capability Based Access Control (CBAC), where a 122 capability is an authorization to perform an operation on a 123 resource. 125 This specification also discusses discovery mechanisms for the 126 client instance to discover the access token formats supported by a 127 RS or an AS and whether attributes (for ABAC) and/or capabilities 128 (for CBAC) are needed in order to perform a given operation on a 129 resource or a registration on a RS. 131 The focus of this protocol is to provide interoperability between 132 the different parties acting in each role, but is not to specify 133 implementation details of each. However the structure of access 134 tokens is detailed, but the syntax of the access tokens is left 135 open. The security of the protocol relies on the presence and on 136 the verification by the RS of some of the fields that must be 137 present in an access token. 139 The protocol takes into consideration the ease of use for the 140 end-user: an end-user can use any number of clients without the 141 burden to manage them (as long as he can trust the client instance). 142 The protocol also take into consideration some privacy laws and 143 recent regulations (e.g. the EU General Data Protection Regulation) 144 [GDPR] in order to allow the RSs to comply with the legislation. 146 Direct communications between an AS and a RS are not necessary for 147 the execution of this protocol. The means for an AS and a RS to 148 interoperate directly are not discussed in this document. 150 1.1. Terminology 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 154 "OPTIONAL" in this document are to be interpreted as described in 155 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 156 capitals, as shown here. 158 1.2. Vocabulary 160 attribute : characteristics related to an end-user 162 right : ability given to an end-user to perform a given operation on 163 a protected resource under the control of a RS 165 Note: a "right" is denoted as a "capability" in the security 166 literature. 168 access token : data artifact representing a set of rights and/or 169 attributes 171 grant (verb) : to permit an instance of client software to receive 172 some attributes at a specific time and valid for a specific 173 duration and/or to exercise some set of delegated rights to 174 access a protected resource 176 grant (noun) : the act of granting 178 privilege : right or attribute associated with an end-user 180 protected resource : API (Application Programming Interface) served 181 by an RS and that can be accessed by a client, if and only 182 if a valid access token is provided. 184 1.3. Abbreviations 186 ABAC Attribute Based Access Control 188 CBAC Capability Based Access Control 190 1.4. Roles 192 The parties in GNAP perform actions under different roles. 193 Roles are defined by the actions taken and the expectations 194 leveraged on the role by the overall protocol. 196 Resource Server (RS) : server that provides operations on resources, 197 where operations on resources protected by GNAP require a valid 198 access token issued by an Authorization Server (AS) 200 Authorization Server (AS) : server that grants delegated privileges 201 to a particular instance of client software in the form of access 202 tokens 204 Client : application operated by an end-user that consumes resources 205 from one or several RSs, possibly requiring access tokens from 206 one or several ASs 208 End-user : natural person that operates a client instance 209 Example: a client can be a mobile application, a web application, 210 etc. 212 Resource Owner (RO) entity that may grant or deny operations 213 on resources it has authority upon 215 Note: the act of granting or denying an operation may be manual 216 (i.e. through an interaction with a physical person) or automatic 217 (i.e. through predefined rules). 219 The following Figure 1 illustrates the relationships between the 220 different roles 222 +---------------+ 223 | | 224 | Authorization | 225 +---------->| Server | 226 | | | 227 | +---------------+ 228 | ~ 229 | ~ When CBAC is supported 230 | ~ 231 +----------+ +---------------+ 232 +----------+ | | | | 233 | End-user |+ + +| Client | | Resource | 234 +----------+ | Instance | | Owner | 235 | | | | 236 +----------+ +---------------+ 237 | ~ 238 | ~ When ABAC is supported 239 | ~ 240 | +---------------+ 241 | | | 242 +---------> | Resource | 243 | Server | 244 | | 245 +---------------+ 247 Legend 249 + + + indicates an interaction between a human and computer 250 ----- indicates an interaction between two pieces of software 251 ~ ~ ~ indicates a possible interaction between two roles 253 Figure 1: Relationships between the different roles 255 When a resource hosted by the RS is access control protected using 256 attributes (ABAC), then the RO interfaces with the RS. 258 When a resource hosted by the RS is access control protected using 259 capabilities (CBAC), then the RO interfaces with the AS. 261 A RS may host protected resources where some of them are access 262 control protected using attributes and while some others are access 263 control protected using capabilities. A same resource can even be 264 protected using attributes and capabilities. 266 1.5. Trust relationships 268 All the exchanges between a Client and a RS SHALL be protected using 269 HTTPS, i.e. HTTP [RFC7231] over TLS [RFC8446]. The verification of 270 the identity of the RS shall be done according to RFC 6125 271 [RFC6125]. 273 All the exchanges between a Client and an AS SHALL be protected 274 using HTTPS, i.e. HTTP [RFC7231] over TLS [RFC8446]. This includes 275 the authentication exchange between an end-user and an AS. The 276 verification of the identity of the AS shall be done according to 277 RFC 6125 [RFC6125]. 279 In order to trust an AS public key certificate or a RS public key 280 certificate, a client SHALL install and use a trust anchor that 281 allows to verify each AS or RS public key certificate. The overall 282 certification scheme SHALL allow each client to test the revocation 283 status of each AS or RS public key certificate using CRLs [RFC5280] 284 or OCSP [RFC6960]. 286 In order to trust an AS public key certificate, a RS SHALL install 287 and use a trust anchor that allows to verify each AS public key 288 certificate. The overall certification scheme SHALL allow each RS 289 to test the revocation status of each AS public key certificate. 291 In order to allow for the revocation of the public key certificate 292 of an AS or a RS, the public key that allows to verify that public 293 certificate SHALL itself be certified using a public key certificate 294 issued by an upper CA. 296 The end-user is trusting his client to manage the interactions with 297 the AS and with the RS, whether these interactions are performed 298 using APIs or using a User Interface (UI). 300 The end-user is trusting the AS to manage his attributes and, upon 301 request, to disclose them to his client. 303 In order to allow the checking of the integrity and the authenticity 304 of the content of an access token, each AS SHALL sign its access 305 tokens using a private key certified by a CA (Certification 306 Authority). 308 For the delivery of either rights or attributes in an access token, 309 a RS may trust one or more ASs. 311 The remaining trust conditions are different whether rights or 312 attributes are supported by the RS to allow performing operations on 313 a given resource under the control of an RS. 315 Rights 317 An access control scheme where rights are supported by the RS to 318 perform operations on a resource is usually known in the security 319 literature as a system using capabilities. When rights are 320 supported by a RS to allow performing operations on a resource under 321 the control access token. 323 In such a case, an of the RS, the RS may trust one or more ASs for 324 the delivery of rights in arrangement needs to be established 325 between each AS/RS pair: the RS MUST designate to the AS a RO that 326 will be responsible to deliver rights which will be placed into 327 access tokens. 329 For each resource protected using capabilities and for each 330 authenticated user, the responsible RO is able to indicate to the AS 331 which operations may be permitted on the resource by an 332 authenticated end-user. 334 A RS may decide to accept from a given RO only a reduced set of 335 operations on some resources. 337 By default and in order to allow interoperability tests, all the 338 resources placed under the control of one RS SHOULD be managed by a 339 single RO. Using private arrangements between the RS and the AS, 340 finer or coarser granularities may override the default behavior. 342 Attributes 344 An access control scheme where attributes are supported by the RS to 345 perform operations on a resource is usually known in the security 346 literature under the acronym of ABAC (Attribute Based Access 347 Control). When attributes are supported by a RS to allow performing 348 operations on a resource under the control of a RS, the RS may trust 349 one or more ASs for the delivery of attribute types and/or attribute 350 values in access tokens. 352 For each resource protected using attributes, the responsible RO is 353 able to indicate to the RS which operations may be permitted on the 354 resource, when a proper set of attribute types and attribute values 355 are present in an access token. 357 In such a case, the RS may globally indicate which attribute types 358 and/or attribute values in access token will be accepted from a 359 given AS. 361 Note: It should be observed that when attributes are being used the 362 AS does not need to perform any kind of pre-arrangement with the 363 RSs. 365 1.6. Prior arrangements before the protocols can be used 367 The following arrangements are supported using out-of-bands means 368 that are outside the scope of the protocol. 370 Every end-user MUST have an account opened with at least one AS. 371 When the account is settled between the end-user and the AS, a user 372 identifier and an authentication method SHALL be agreed. The end- 373 user MUST receive information that allows him to perform a first 374 authentication exchange with success. 376 When capabilities are supported by a RS, that RS SHALL designate a 377 RO that will interface with at least one AS. 379 1.7. Short term and long term user accounts 381 Two types of accesses may be proposed by a RS to allow an end-user 382 to use: 383 - short-term user accounts, or 384 - long-term user accounts. 386 In the first case, the user may be willing to remain anonymous 387 towards the RS by either using a capability or disclosing a set of 388 attributes that will be insufficient to identify him unambiguously. 389 Once the session will be closed, the RS will not maintain 390 information about the session, except in his audit trail. 392 In the second case, the user may be willing to retrieve some data, 393 to deposit some data or to modify some data that will be saved by 394 the RS. A typical example, is an access to a bank account. 396 1.8. Structure of an access token 398 This section describes the structure of an access token by 399 enumerating both required and optional fields. 401 For each field, it prescribes both its semantics and the processing 402 that SHALL be done on it, but it does not prescribe its syntax. In 403 the future, additional documents may define detailed access token 404 formats including their encoding. 406 An access token is composed of two parts: a signed part and an 407 unsigned part which is optional. 409 Before accepting an access token, a RS SHALL check the mandatory 410 fields of the access token. 412 1.8.1. Signed part of an access token 414 This part contains: 416 - a required field (called "valid") that indicates the validity 417 period of the access token using the UTC time. The start of 418 the validity period is the time at which the access token was 419 issued. 421 - a required field (called "as_pkc") that allows to identify the 422 issuer of the access token, i.e. the AS. Either the PKC 423 (Public Key Certificate) [RFC5280] of the AS SHALL be included 424 or, if the corresponding certificate is placed in the unsigned 425 part of the access token, a hash value of that certificate 426 SHALL be included. 428 - an optional field (called "hash_algo") that indicates the 429 identifier of the hash algorithm used to compute the digital 430 signature of the access token. 432 - one of the two following optional fields, i.e. "rs_url" or 433 "hidden_url", SHALL be present: 435 - an optional field (called "rs_url") that allows a RS to 436 make sure that the access token is indeed intended for 437 itself. That field SHALL contain at least one URL of a RS. 439 - an optional field (called "hidden_url") that allows a RS 440 to make sure that the access token is intended for itself. 441 That field SHALL contain at least one value that MUST be 442 combined with a field ("reveal_url") from the unsigned part 443 of the access token to recover the real value of the target 444 URL of a RS. 446 - a required field (called "buid") which is a "binding user 447 identifier" that allows a RS to verify that the access token is 448 associated with the right (short-term or long-term) user 449 account. This field allows to detect the inappropriate use of 450 an access token by a malicious user, including in the case of 451 a collusion between users. This field is composed of a type 452 chosen by the client and of a value chosen by the AS. Five 453 different types may be requested by the client : 455 The first four types are used in the context of long-term user 456 accounts managed by the RS, while the last type is used in the 457 context of short-term user accounts managed by the RS. 459 The four types used in the context of long-term user accounts 460 managed by a RS are: 462 (1) a unique user identifier used to identify a user for each 463 User/ RS pair, or 464 Note: this option cannot be implemented in the context of 465 a "software-only" solution. It requires the use, by the 466 end-user, of a secure element with specific security 467 properties. [This option is not detailed any further at 468 the moment]. 470 (2) a unique user identifier used to identify a user for each 471 AS / RS pair, or 473 (3) a locally unique user identifier used to identify a user 474 whatever RS is being involved, or 476 (4) a globally unique user identifier. 478 The last type used in the context of short-term user accounts 479 managed by a RS is: 481 (5) a short-term user unique identifier. 483 Note: The four first types are used when a long-term user account is 484 being used on a RS. The last and fifth type is used when a 485 short-term user account is being used on a RS. 487 - at least one of the two following optional fields, i.e. "attrs" 488 or "rights", SHALL be present (both may be present): 490 - an optional field (called "attrs") that contains one or more 491 attributes that are associated with the end-user. This field 492 is an array where each element of the array is composed of 493 the identifier of an attribute type and of the associated 494 attribute value. 496 - an optional field (called "rights") that contains one or more 497 rights (i.e. capabilities) that have been granted to the user 498 by a RO hosted by the AS and which is associated with the RS 499 protecting the resource. This field is an array where each 500 element of the array is composed of one or more methods and 501 of the URL of a resource. 503 - an optional field (called "at_uid") that contains a unique 504 identifier for the access token. The identifier value MUST be 505 assigned by the AS in a manner that ensures that there is a 506 negligible probability that the same value will be accidentally 507 assigned twice. This field may be useful for audit purposes. 509 1.8.2. Unsigned part of an access token 511 This part contains: 513 - the signature value (called "sign") of the access token. 515 - an optional field (called "path") that contains a certification 516 path [RFC5280], starting with the PKC of the AS. 518 - an optional field (called "reveal_url") that allows to retrieve 519 the true value(s) of the URL(s) of RS(s) that has (have) been 520 hidden to the AS. 522 This field is an array where each element of the array is 523 composed of a random value called "rnd_value" and a method 524 identifier. If the field "hidden_url" is present in the signed 525 part of the access token, then the field "reveal_url" MUST be 526 present. This field MUST be used by the RS to combine the 527 "hidden_url" value with the appropriate "rnd_value" to verify 528 that the end result matches with its own URL value. 530 A one way hash function (OWHF) SHALL be used by the client to 531 compute the "hidden_url" to be placed into the access token, by 532 first choosing a large random number for the "reveal_url" value 533 and combining it with the base URL of the RS using the following 534 formula: "hidden_url" = OWHF ("reveal_url", RS_URL). When the 535 client receives the access token from the AS and before 536 communicating it to the RS, the "reveal_url" value SHALL be 537 inserted by the client into the unsigned part of the access 538 token. 540 1.9. Mandatory checks to be done by a RS on an access token 542 When a resource is protected using GNAP, several checks need to be 543 done. 545 The ordering of the following checks is not mandated as long as all 546 the checks are performed. 548 However, the following list has been established taking into 549 consideration that an invalid access token should be rejected as 550 soon as possible which means that the fastest checks should be done 551 before. 553 When receiving an access token, the RS SHALL check that: 555 - it is well-formed, 557 - it contains an "attrs" field if the RS supports attributes and it 558 contains a "rights" field if the server supports capabilities. 559 If a RS supports both, one of these two fields SHALL be present. 561 - the access token is currently within its validity period by using 562 the "valid" field and the UTC time. The start of the validity 563 period cannot be sooner than the current time expressed using the 564 UTC time. A time skew of a dozen of seconds SHOULD be allowed. 565 The validity period of the access token SHOULD NOT exceed 25 566 hours. 568 - that the access token is indeed targeted to itself by using either 569 the "rs_url" field or the "hidden_url" field, and in the later 570 case also the "reveal_url" field. 572 When the RS receives an access token that contains both an 573 "hidden_url" and a "reveal_url" field, it SHALL verify that the 574 access token is targeted to itself, by using its RS_URL and then 575 computing the value: OWHF (reveal_url, RS_URL) and finally verify 576 that it matches with the value contained in the "hidden_url" field. 578 - that the access token is apparently coming from one of the ASs 579 trusted by the RS using the DN (Distinguished Name) of the AS that 580 is present in the AS's PKC. 582 In order to perform that check, the AS's PKC SHALL be retrieved 583 either directly from the "as_pkc" field or using the hash value 584 of that PKC if present in the "as_pkc" field to retrieve it from 585 the "path" field. The validity period of that PKC [RFC5280] SHALL 586 be verified. 588 - that the signature of the access token is valid. In order to 589 perform this verification, the RS SHALL first construct a 590 certification path between an appropriate trust anchor and the 591 RS's PKC [RFC5280]. If present, the field "path" SHOULD be used 592 to construct that certification path. Once the certification path 593 has been verified as being valid (taking in consideration the 594 revocation status of each PKC from the certification path) the 595 certified key SHALL be extracted from the PKC and used to verify 596 the field "sign" of the access token [RFC5280]. Depending upon 597 the public key algorithm being used, the field "hash_algo", if 598 present, SHALL also be used. 600 Note: additional checks depend whether the resource is protected 601 using attributes or capabilities. 603 2. An overview of the protocols 605 Different protocols can be used for different purposes: 607 (1) to discover the main features supported either by a RS or 608 an AS; 610 (2) to allow an end-user to query which of his attributes are 611 known by an AS; 613 (3) to create a long-term user account on a RS (that will last 614 between different sessions) using an access token; 616 (4) to create a short-term user account on a RS (that will last 617 during the duration of a single session) using an access 618 token; 620 (5) to perform an operation on a resource hosted by a RS. 622 2.1. RS and AS Discovery APIs 624 2.1.1. RS Discovery API 626 A GNAP RS can publish its features on a well-known discovery 627 document using the URL ".well-known/gnap-rs" appended to the 628 base URL of the RS. 630 The discovery response is a JSON document [RFC8259] consisting of a 631 single JSON object with the following fields: 633 trusted_AS (array) : REQUIRED: A list of the ASs trusted by the RS. 635 The array contains an enumeration of ASs and for each AS, the 636 following information SHALL be present : 638 - the base URL of the AS, and 639 - one AS PKC. 641 It is RECOMMENDED to include an image within the AS certificate 642 according to RFC 6170 (Internet X.509 Public Key Infrastructure 643 Certificate Image). The purpose of the certificate image is to 644 aid human interpretation of a certificate by providing meaningful 645 visual information to a user interface (UI). 647 In addition it is RECOMMENDED to publish the next AS PKC, when it 648 has already been issued by the responsible CA. 650 Note: the ordering of these ASs is important. See section 5.1. 652 user_interaction_endpoint (string): REQUIRED. The location of 653 the RS's user interaction endpoint, used by the client to conduct 654 a dialogue between the end-user and the RS. 656 The goal of this dialogue is to present one or more options to 657 the end-user, so that, after being informed of the consequences 658 of these options, he may provide its consent to the RS. 660 The location MUST be a URL [RFC3986] with a scheme component 661 that MUST be https, a host component, and optionally, port, path 662 query components and no fragment components. 664 RS_token_formats_&_syntaxes_supported (array of strings) OPTIONAL: 665 A list of token formats and syntaxes supported by the RS. 667 long_term_user_account (Boolean) OPTIONAL: indicates whether 668 long-term user accounts are supported by the RS. 670 short_term_user_account (Boolean) OPTIONAL: indicates whether 671 short-term user accounts are supported by the RS. 673 Note : either the long_term_user_account flag or the 674 short_term_user_account flag MUST be present and set to TRUE. 676 user_registration_endpoint (string): OPTIONAL. The RS's user 677 registration endpoint, used by the client to create either a 678 short-term user account or a long-term user account. 680 rs_cert_path (array): OPTIONAL. A set of CA certificates that may 681 help a client to built a certification path between a RS 682 certificate and a trust anchor. 684 2.1.2. AS Discovery API 686 A GNAP AS can publish its features on a well-known discovery 687 document using the URL ".well-known/gnap-as" appended to the 688 base URL of the AS. 690 The discovery response is a JSON document [RFC8259] consisting of a 691 single JSON object with the following fields: 693 attributes_supported (Boolean) OPTIONAL: indicates whether 694 attributes requested by the end-user may be included into 695 an access token. 697 capabilities_supported (Boolean) OPTIONAL: indicates whether 698 capabilities requested by the end-user may be included into 699 an access token. 701 Note : either the attributes_supported Boolean or the 702 capabilities_supported Boolean MUST be present and set to TRUE. 704 AS_token_formats_&_syntaxes_supported (array of strings) OPTIONAL: 705 A list of token formats and syntaxes supported by the AS. 707 grant_request_endpoint (string): REQUIRED. The location of the 708 AS's grant request endpoint, used by the client to request access 709 tokens. The location MUST be a URL [RFC3986] with a scheme 710 component that MUST be https, a host component, and optionally, 711 port, path query components and no fragment components. 713 as_cert_path (array): OPTIONAL. A set of CA certificates that may 714 help a client to built a certification path between an AS 715 certificate and a trust anchor. 717 2.2 Queries from an end-user to an AS 719 Before making this query, the client SHALL establish an HTTPS 720 connection with the AS. The client SHOULD be able to communicate 721 to the AS the preferred language(s) of the end-user. The end-user 722 SHALL successfully authenticate with the AS. 724 Any kind of authentication method can be used, e.g. using asymmetric 725 cryptography, symmetric cryptography or even using end-user 726 identifiers associated with (long) passwords, since the connection 727 is both integrity and confidentiality protected using HTTPS. 729 Since the AS knows some attributes that belong to the end-user, they 730 will be returned in the response to this query. Each attribute has 731 a type and a value. These attributes are considered as personal 732 data and, as such, the end-user SHALL be able to have access to 733 them. In some cases, it may be allowed to correct some of them or 734 to propose corrections to them. 736 Note: In this case, no access token will be returned. 738 2.3. Creation a long-term user account on a RS 740 Two different cases needs to be considered, whether the RS already 741 "knows" the end-user or not. The client SHOULD first make sure that 742 the RS has set the long_term_user_account flag, otherwise no long- 743 term user account can be created. 745 2.3.1. The RS already "knows" the end-user 747 The RS may already "know" the end-user because it already holds some 748 information about him and the end-user is already identified by the 749 RS under a user account number. 751 The user would like now to like to get on on-line access to perform 752 some operations on some information associated with his user 753 account. 755 The client performs a RS Discovery operation to know which ASs are 756 trusted by the RS. If the user has an account on one of these ASs, 757 the end-user (or the client) may select one of these ASs. 759 The RS asks the client to provide some user attributes types already 760 known by the AS that has been selected by the client. The dialogue 761 with the end-user SHALL be handled using the 762 user_interaction_endpoint. 764 The RS allows the user to know the reason(s) why such attribute 765 types are being requested (User Notice). The user may agree or deny 766 to provide them (User choice and User Consent) and, if he agrees, 767 the client will request to the AS an access token that should 768 contain these attribute types. 770 For example, the attribute types may be: first name, family name, 771 birth date and birth location. 773 In order to detect a possible replay or use of a delivered access 774 token by an AS for a given RS by another client, the client 775 indicates that the access token should be protected under, e.g. : 777 (1) a unique user identifier used to identify a user for each 778 User/ RS pair; 780 (2) a unique user identifier issued by the AS to identify the 781 end-user for each AS / RS pair (e.g. a different pseudonym 782 for each AS / RS pair), or 784 (3) a locally unique user identifier used by the AS to identify 785 the user, whatever server is involved (e.g. a single 786 pseudonym used for all the servers), or 788 (4) a globally unique user identifier (e.g. a personal email 789 address, a social security number including the issuing 790 country, a passport number including the issuing country, 791 a driving license including the issuing state or country). 793 In order to detect the replay of the access token by a RS towards 794 another RS, the client indicates the identifier of the intended RS. 795 The fields "rs_url" or "hidden_url" of the access token may be used 796 to allow such a detection. 798 The returned access token will include some attributes. These 799 attributes are placed in the "attrs" field of the access token. 801 The returned access token will then include in the "binding user 802 identifier" field ("buid") of the access token, the type of the 803 binding unique user identifier requested and a value assigned by 804 the AS. 806 If the attribute types and values contained in the access token 807 match with the already known attribute types and values, the 808 operation will be granted. 810 It should be observed that, when using the choice (2), it is not 811 possible to hide to the AS the URL of the RS, since this value is 812 needed to generate a different pseudonym for each AS / RS pair. 814 It may be observed that, when using the choice (3), it is possible 815 to hide to the AS the URL of the RS, since this value is not needed 816 to generate a single pseudonym used for all the servers. However, 817 in this case, all the RSs receiving access tokens from the same AS 818 are able to link their user accounts. 820 It may be observed that, when using the choice (4), it is possible 821 to hide to the AS the URL of the RS, since this value is not needed 822 to generate a globally unique user identifier. However, in this 823 case, not only all the RSs receiving access tokens from the same AS 824 will be able to link their user accounts, but also other servers 825 using the same globally unique user identifier. 827 The choice (4) should be avoided, unless all the RSs issuing 828 attributes or rights are managed by the same organization that is 829 managing the AS and that organization is purposely willing to link 830 all the user accounts of its RSs. At the moment, the "best" choices 831 in the Internet environment are be restricted between the choices 832 (2) and (3) and will be a compromise between two privacy properties, 833 where each of these two choices has an advantage and a drawback : 835 - the choice (2) does not allow to hide to the AS the URL of the 836 RS, but prevents the RSs receiving access tokens from the same 837 AS to link their user accounts, while 839 - the choice (3) allows to hide to the AS the URL of the RS, but 840 allows the RSs receiving access tokens from the same AS to link 841 their user accounts. 843 That choice will be left to the end-user (or to the client). 845 Note: the choice (1) would allow both to hide to the AS the URL 846 of the RS and to prevent the RSs to perform a linkage between 847 their user accounts. 849 Later on, if the client requests another access token, the client 850 or the end-user should remember its original choice, e.g. (2) 851 or (3), for the same RS, otherwise the access token will be rejected 852 by the RS. 854 It is recommended that each client locally manages for each end-user 855 a "privacy preference profile" to associate a choice value with the 856 base URL of each RS. 858 In order to detect the replay of the access token by a RS towards 859 another RS, the client indicates the identifier of the intended RS 860 using either the "rs_url" field for the choice (2) or the 861 "hidden_url" field for the choice (3) of the access token. 863 The returned access token will then include some attributes in the 864 field "attrs" of the access token and the binding user identifier 865 issued by the AS in the field "buid" of the access token. 867 Before presenting this access token to the RS, the end-user SHALL 868 establish an HTTPS connection with the RS. Then after, the access 869 token SHALL be send to the user_registration_endpoint of the RS. 870 Once the RS has verified that the access token is valid, it 871 memorizes the "binding user identifier" field ("buid") of the access 872 token. All subsequent access tokens issued by that AS SHALL contain 873 the same value, otherwise they will be rejected. 875 It is recommended that each client locally manages for each end-user 876 a "privacy preference profile" to associate a choice value with the 877 base URL of each RS. 879 2.3.2. The RS does not already "know" the user 881 The RS does not yet "know" the user: he has no user account for the 882 end-user on that RS. The end-user wants to create a user account. 884 The client performs a RS Discovery operation to know which ASs are 885 trusted by the RS. If the user has an account on one of these ASs, 886 the end-user (or the client) may select one of these ASs. 888 In order to create a RS user account, a RS will likely ask for both 889 claimed attributes and certified attributes (i.e. attributes 890 contained in an access token delivered by an AS trusted by the RS). 891 Claimed attributes are simply attributes declared by the user. 893 The user_interaction_endpoint of the RS will be used to conduct a 894 dialogue between the RS and the end-user in order to request both 895 claimed attributes and certified attributes. During that dialogue, 896 the end-user has the ability to know the reason(s) an/or the 897 rational for the collection of each attribute type and which kind of 898 treatment will be made of it. 900 Once the end-user has agreed to request some attributes types to the 901 selected AS, the client requests to that AS an access token that 902 contains some attribute types known by that AS. 904 As in the previous case, in order to detect a possible replay or use 905 of a delivered access token by an AS for a given RS by another 906 client, the client indicates that the access token should be 907 protected under, e.g. : 909 (1) a unique user identifier used to identify a user for each 910 User/ RS pair; 912 Note: this option is only possible when the end-user is 913 using a specific secure element. 915 (2) a unique user identifier issued by the AS to identify the 916 user for each AS / RS pair (e.g. a different pseudonym for 917 each AS / RS pair), or 919 (3) a locally unique user identifier used by the AS to 920 identify the user, whatever server is involved (e.g. a 921 single pseudonym used for all the servers), or 923 (4) a globally unique user identifier (e.g. a personal email 924 address, a social security number including the issuing 925 country, a passport number including the issuing country, 926 a driving license including the issuing state or country). 928 The choice (4) should be avoided. At the moment, the "best" choices 929 will be restricted between the choices (2) and (3) and will be a 930 compromise between two privacy properties, since each of these two 931 choices has an advantage and a drawback : 933 - the choice (2) does not allow to hide to the AS the URL of the 934 RS, but prevents the RSs receiving access tokens from the same 935 AS to link their user accounts, while 937 - the choice (3) allows to hide to the AS the URL of the RS, but 938 allows the RSs receiving access tokens from the same AS to 939 link their user accounts. 941 If the attribute types and values contained in the access token 942 match with the expected attribute types and if the requested claimed 943 attributes are also received, some verifications will be done by the 944 RS. Such verifications introduce some delay. 946 This is why the final response about the creation of the user 947 account on the RS is asynchronous. 949 Later on, if the client requests another access token, the client 950 or the end-user should remember its original choice, e.g. (2) or 951 (3), for the same RS, otherwise the access token will be rejected by 952 the RS. 954 It is recommended that each client locally manages for each end-user 955 a "privacy preference profile" to associate a choice value with the 956 base URL of each RS. 958 In order to detect the replay of the access token by a RS towards 959 another RS, the client indicates the identifier of the intended RS 960 using either the "rs_url" field for the choice (2) or the 961 "hidden_url" field for the choice (3) of the access token. 963 The returned access token will then include some attributes in the 964 field "attrs" of the access token and the binding user identifier 965 issued by the AS. 967 Before presenting this access token to the RS, the end-user SHALL 968 establish an HTTPS connection with the RS. Then after, the access 969 token SHALL be send to the user_registration_endpoint of the RS. 970 Once the RS has verified that the access token is valid, it 971 memorizes the "binding user identifier" field ("buid") of the access 972 token. All subsequent access tokens issued by that AS SHALL contain 973 the same value, otherwise they will be rejected. 975 2.4. Creation a short-term user account on a RS 977 The client performs a RS Discovery operation to make sure that the 978 RS has set the short_term_user_account flag, otherwise no short-term 979 user account can be created. 981 The client performs a RS Discovery operation to know which ASs are 982 trusted by the RS. If the user has an account on one of these ASs, 983 the end-user (or the client) may select one of these ASs. 985 In order to detect a possible replay or use of a delivered access 986 token by an AS for a given RS by another client, the client 987 indicates that the access token SHALL be protected using a short- 988 term user unique identifier. 990 The client (or the end-user) has then two options: either to hide or 991 to reveal the URL of the RS. If it wants to hide the URL of the RS, 992 it can only use one session. For this purpose, it SHALL use the 993 "hidden_url" field of the access token. In order to connect with 994 another RS, it SHALL explicitly release that session. If it agrees 995 to reveal the URL of the RS, it SHALL use the "rs_url" field of the 996 access token. It can then use multiple short-term sessions with 997 different RSs in parallel. The two choices are exclusive. 999 The returned access token will then include in the "binding user 1000 identifier" field ("buid") of the access token, the type of the 1001 binding user identifier requested and a value assigned by the AS. 1002 This value assigned by the AS SHOULD be a large pseudo-random 1003 number. 1005 In order to detect the replay of the access token by a RS towards 1006 another RS, the client indicates the identifier of the target RS. 1007 The fields "rs_url" or "hidden_url" of the access token may be used 1008 to allow such detection. 1010 Note: none of the two optional fields "attrs" and "rights" needs 1011 to be present in this access token. 1013 Before presenting this access token to the RS, the end-user SHALL 1014 establish an HTTPS connection with the RS. Then after, the access 1015 token SHALL be send to the user_registration_endpoint of the RS. 1016 Once the RS has verified that the access token is valid, it 1017 memorizes the "binding user identifier" field ("buid") of the access 1018 token. 1020 All subsequent access tokens issued by that AS SHALL contain the 1021 same value, otherwise they will be rejected. 1023 2.5. Operation on a resource hosted by a RS 1025 2.5.1. Operation on a resource without an access token 1027 The client does not necessarily know in advance, whether the 1028 resource is or is not protected. If the resource is unprotected and 1029 if the API is well formed, then the access will be granted. 1031 When a client instance calls an RS without an access token, or with 1032 an invalid access token, if the resource is protected and if the API 1033 is well formed, then different HTTP errors types may be returned, in 1034 particular: 1036 401 "Unauthorized" which indicates an authentication error. It 1037 always includes a WWW-Authenticate header that describes how to 1038 authenticate. 1040 In this particular case, the RS SHALL respond with a header field 1041 that contains one challenge for the "GNAPv1" scheme and two 1042 additional parameters "attrs" and "rights" to indicate whether the 1043 RS supports attributes and/or rights for that resource. 1045 After each parameter (i.e. "attrs" and "rights") follows a pointer 1046 to the AS(s) trusted by the RS as enumerated in the "trusted_AS" 1047 field from the RS Discovery API. 1049 For example: WWW-Authenticate: GNAPv1 attrs= 1,3,4 rights= 2,3 1051 In this example, both attributes and rights are supported. AS 1 1052 and AS 4 support attributes only, AS 3 supports both attributes and 1053 capabilities (i.e. rights) while AS 2 supports capabilities (i.e. 1054 rights) only. 1056 If either attributes or rights are not supported, the following 1057 values SHALL be used respectively: "attrs= 0" or "rights= 0". 1059 The client SHOULD then use the "RS Discovery API" to find out which 1060 are the ASs trusted by the RS. 1062 403 "Forbidden" which indicates that the server understood the 1063 request but that the client instance does not have permission to 1064 access this resource, even if it has been authenticated. A server 1065 that wishes to make public why the request has been forbidden can 1066 describe that reason in the response payload (if any). 1068 When the request is recognized by the server but sent "without an 1069 access token or with an invalid access token", the HTTP status 403 1070 Forbidden SHOULD be used. If the server wants to make known why a 1071 request is forbidden, it can provide the reason in the payload. 1073 Note 1: 403 "Forbidden" is dedicated to authorization errors, 1074 whereas 401 "Unauthorized" is dedicated to authentication errors. 1076 Note 2: A server that wishes to hide the existence of a forbidden 1077 target resource MAY instead respond with a status code of 404 1078 (Not Found). 1080 404 "Not Found" which indicates either that the server did not find 1081 a current representation for the target resource or that the server 1082 is not willing to disclose that one exists. 1084 405 "Method not allowed" which indicates that the method received in 1085 the request-line is known by the server but not supported by the 1086 target resource. In that case, the server MUST generate an Allow 1087 header field containing a list of the target resource's currently 1088 supported methods. 1090 Note: If the method is incorrect, 405 "Method not allowed" SHALL 1091 have precedence over 403 "Forbidden". 1093 Note: These error codes are defined in RFC 7231 [RFC7231]and 1094 RFC 7235 [RFC7235] as follows: 1096 - 400 Bad Request . . . . . . Section 6.5.1 of RFC 7231 1097 - 401 Unauthorized . . . . . . Section 3.1 of RFC 7235 1098 - 403 Forbidden . . . . . . . Section 6.5.3 of RFC 7231 1099 - 404 Not Found . . . . . . . Section 6.5.4 of RFC 7231 1100 - 405 Method Not Allowed . . . Section 6.5.5 of RFC 7231 1101 - 406 Not Acceptable . . . . . Section 6.5.6 of RFC 7231 1103 2.5.2. Operation on a resource using an access token 1105 The client instance determines which operation on a resource is 1106 needed and which RS to approach for access. 1108 Unless the client already knows from a previous experience what kind 1109 of additional data needs to be presented, the client has the 1110 possibility to query the RS to know which kind of protection is 1111 being used by the RS for that resource. 1113 It requests on operation on the intended resource and voluntarily 1114 omits to send any access token. It will then get an 401 1115 "Unauthorized" error that indicates that GNAPv1 is supported and 1116 whether attributes and/or rights should be presented in an access 1117 token. 1119 It will also know which ASs, if any, are trusted by the RS to 1120 deliver attributes in an access token and which ASs, if any, are 1121 trusted by the RS to deliver capabilities in an access token. 1123 The client instance determines that the RS supports GNAP and the 1124 process may continue. 1126 2.5.2.1. Dialogue between the end-user and his client 1128 The client may be configured by the end-user with the URLs of the 1129 ASs where he has an AS user account. It may then propose to select 1130 one or more ASs showing at the same time, if capabilities or 1131 attributes may be requested on these ASs to be included into an 1132 access token. 1134 If some choices remain, then the client SHOULD ask the end-user to 1135 make these choices. The client then knows which AS has been chosen 1136 and whether attributes (ABAC) or capabilities (CBAC) will later on 1137 be requested to that AS. 1139 The client SHALL determine whether the end-user is willing to make 1140 an access to the RS using a short-term user account or a long-term 1141 user account. Usually, it should know it from the context of the 1142 operation. However, if it doesn't know, it SHALL ask the end-user 1143 to make that choice. 1145 If the client used by the end-user has recently opened a short-term 1146 user account, it SHOULD be usable if it has not been closed, 1147 otherwise a new short-term user account SHOULD be created. 1149 If the access to the RS should be done using a long-term user 1150 account, the same choice as originally made by the end-user for the 1151 binding user identifier when opening his user account on the RS 1152 should be done. If the client locally manages for each end-user a 1153 "privacy preference profile" that associates a choice value with the 1154 base URL of each RS, it should re-use the same choice. Otherwise, 1155 the question should be raised again to the end-user. 1157 2.5.2.2. Dialogue between the end-user and the RS 1159 When using ABAC, a dialogue needs to be established between the end- 1160 user and the RS. Such dialogue needs to be supported using a port 1161 able to support a User Interface (UI). The address of this port 1162 SHALL be published by the RS and made available using the RS 1163 Discovery API. It SHALL be a URL hosted by the RS. 1165 When initiating the dialogue on the UI port of the RS, the client 1166 communicates to the RS which AS has been selected by the end-user. 1168 The RS indicates to the end-user which attribute types and 1169 optionally attribute values should be present in an access token 1170 issued by that AS. 1172 Before making a call to that AS, the end-user may wish to be 1173 informed of the treatments or usages that will be done by the RS 1174 with each requested attribute type, including a possible disclosure 1175 to other third parties. Such information is usually present in a 1176 User Notice. A simple click or a selection of an attribute type 1177 should be sufficient to disclose the terms of this User Notice. 1179 The UI SHALL clearly ask the end-user whether it accepts to request 1180 these attribute types and SHALL require an action or a gesture from 1181 the end-user to indicate its acceptance. 1183 At this point of time, the choice made by the end-user SHOULD be 1184 memorized by the RS and also by the client. 1186 The memorization done by the RS is not for technical reasons, but 1187 to comply with some laws or regulations. 1189 As an example, the General Data Protection Regulation [GDPR] from 1190 the EU indicates in Article 7(1) : 1192 "Where processing is based on consent, the controller SHALL 1193 be able to demonstrate that the data subject has consented 1194 to processing of his or her personal data. " 1196 The memorization done by the client is for technical reasons: the 1197 client SHALL use the choice made by the end-user to request an 1198 access token to the AS that SHOULD include the attribute types 1199 selected by the end-user. 1201 A markup language such as XML needs to be used in order to delineate 1202 the meaning of each field and its value, when present. 1204 Note: when the RS supports CBAC for a protected resource, no 1205 dialogue is needed between the end-user and the RS. 1207 2.5.2.3. The access token request 1209 The client knows whether the access token will be used for a short- 1210 term RS user account or a long-term RS user account. 1212 If a long-term user account is being used, the client SHOULD already 1213 know the privacy preference of the user since they have been chosen 1214 when creating the long-term user account (see section 3). If the 1215 user is using a new client (i.e. device), then the new client SHOULD 1216 inquire it again. 1218 The client already knows whether the resource is protected using 1219 attributes and/or rights (see section 5.1). If it is protected 1220 using attributes, it already knows which types of attributes should 1221 be requested to the AS, and optionally which attribute values. 1223 The request MUST be sent as a JSON object in the body of the HTTP 1224 POST request with Content-Type "application/json". 1226 Each field placed in the body of the HTTP POST request is described 1227 below: 1229 at_format : REQUIRED. The format of the access token. 1231 at_crypto : REQUIRED. The asymmetric crypto algorithm and the one 1232 way hash function to be used for computing the digital signature 1233 of the access token. 1235 val_period (string) OPTIONAL. It is the desired validity period of 1236 the access token expressed in hours and minutes. The AS may 1237 override this value. 1239 buid_type (integer) : REQUIRED. The binding user identifier type 1240 to be used with the RS. The allowed values are 1 to 5. 1242 target_rs (string) : either a "rs_url" value or a 1243 "hidden_url" value that SHALL be placed into the access token. 1245 Note : if the buid_type is set to 2, then a "hidden_url" value 1246 SHALL NOT be accepted. 1248 operations (array of string) : REQUIRED when capabilities are 1249 requested. It is a list of capabilities, where each capability 1250 consists of : 1251 - one or more methods and 1252 - the URL of the protected resource. 1254 attrs_types (array of string) : REQUIRED when attributes are 1255 requested. It is a list of attribute types. These attributes 1256 may be static or computed from a static attribute. As an example, 1257 an age categorization attribute would be a computed attribute 1258 composed of one or two values, like "over 12" and "under 18" 1259 (see min-age and max-age). 1261 The naming and the definitions used in Table 1 (Registered Member 1262 Definitions) from the "OpenID Connect Core 1.0 specification" 1263 [OIDC_1.0] are re-used in this document. 1265 See : https://openid.net/specs/openid-connect-core- 1266 1_0.html#Claims 1268 As a consequence, the following attributes types are defined: 1270 name, given_name, family_name, middle_name, nickname, 1271 preferred_username, profile, picture, website, email, 1272 email_verified, gender, birthdate, zoneinfo, locale, 1273 phone_number, phone_number_verified, address. 1275 In addition, subsets of the previous fields may be returned. 1276 For example, for an address, the country and region only may 1277 be requested. This leads to recognize the following attribute 1278 types: street_address, locality, region, postal_code, country. 1280 In addition, the following attribute types may also be useful: 1281 shipping_address, payment_info, eye_color, max_age, min_age. 1283 In order to support group memberships, the two following 1284 attribute types are also defined: hierarchical_group and 1285 functional_group. 1287 Since a user may belong to more than one functional group, the 1288 value(s) that should be placed into the access token should be 1289 indicated in the request, otherwise all the functional groups 1290 will be returned. 1292 The end-user is able to know which values have been affected to 1293 this attribute type by sending a query to the AS (see section 1294 2.2). As a consequence, the client is able to specify which 1295 attribute value(s) should be returned for the functional_group 1296 attribute type. 1298 2.5.2.4. The access token response 1300 The response MUST be sent as a JSON object in the body of the HTTP 1301 POST request with Content-Type "application/json". It is an access 1302 token. Its semantics and structure are described in section 1.7. 1304 2.6. Flow of operations for one access 1306 Once either a short-term user account or a long-term user account 1307 has been created on a RS, the flow of operations is illustrated 1308 hereafter: 1310 +---------------+ 1311 +------------->| | 1312 |(5) | Authorization | 1313 | | Server | 1314 | +-------| | 1315 | |(6) +---------------+ 1316 | | ~ 1317 | | ~ 1318 +----------+ +---------------+ 1319 | | | | 1320 +----------+ (3) | Client | | Resource | 1321 | End-user |+ + +| Instance | | Owner | 1322 +----------+ | | | | 1323 ^ +----------+ +---------------+ 1324 | ^ ^ | ~ 1325 | | | | ~ 1326 | | | |(7) +---------------+ 1327 | | | +------>| | 1328 | | |(2) | | 1329 | | +---------->| Resource | 1330 | |(1) | Server | 1331 |(4 Opt.) +-------------->| | 1332 +--------------------------->| | 1333 User Interface +---------------+ 1335 Figure 2: Flow of operations for one access 1337 (1) RS Discovery 1338 (2) Operation on a resource hosted by a RS without an access token 1339 (3) Dialogue between the end-user and the client 1340 (4) Optional dialogue between the end-user and RS 1341 when the RS requests attributes 1342 (5) Access Token request to AS 1343 (6) Access Token response from AS 1344 (7) Access Token presentation to RS 1345 Note: The creation of RS user accounts is not illustrated 1346 on Figure 2. 1348 3. IANA Considerations 1350 This specification will require the registration of the various 1351 attributes types defined in section 5.2.3: 1353 name, given_name, family_name, middle_name, nickname, 1354 preferred_username, profile, picture, website, email, 1355 email_verified, gender, birthdate, zoneinfo, locale, 1356 phone_number, phone_number_verified, address, 1358 street_address, locality, region, postal_code, country, 1360 shipping_address, payment_info, eye_color, max_age, min_age. 1362 4. Security Considerations 1364 Since HTTPS is used between the client and the RS and between the 1365 client and the AS, the client can be confident that the information 1366 it receives is indeed coming from the intended RS and from the 1367 intended AS. 1369 Since the authentication exchange between the end-user and the AS is 1370 protected by HTTPS, the AS can be confident that the end-user is 1371 using the unknown connected client. Any kind of authentication 1372 exchange can be used, including the simple "id and password" scheme, 1373 since the password is both integrity and confidentiality protected 1374 during its transfer. 1376 The appropriate version (or versions) of TLS will vary over time, 1377 based on the widespread deployment and known security 1378 vulnerabilities. Refer to [BCP195] for up to date recommendations 1379 on transport layer security. 1381 The transmission of an access token obtained by one end-user to 1382 another end-user cannot be prevented, but can be detected by the RS. 1384 In order to detect the transmission of the access token by one 1385 client towards another client, the AS includes in every access token 1386 a binding user identifier ("buid"). 1388 Every access token is bound to a RS user account (either a short- 1389 term user account or a long-term user account). This is done by 1390 including a binding user identifier ("buid") in every access token. 1391 A binding user identifier is composed of a type and of a value. The 1392 client can choose the type of the binding user identifier but not 1393 its value which is only assigned by the AS. 1395 All access tokens that are presented to a RS in the context of a 1396 given RS user account must contain the same binding user identifier. 1398 If an end-user obtains an access token from a collaborative end- 1399 user, he cannot use it on his own user account since it will not 1400 contain the same binding user identifier ("buid"). 1402 Let us use an example to illustrate the topic. 1404 Some goods or activities with some preferred rates are only 1405 disclosed by a town to its residents and if there are over 21. 1406 In such a case, two attribute types and values will be requested 1407 by the RS, e.g. : 1409 Town of residence: Nashville - Tennessee - 840 1410 Age categorization: over 21 1412 Let us assume that Alice has the two following attributes: 1413 Town of residence: Nashville - Tennessee - 840 1414 Age categorization: over 16 1416 while Bob has the two following attributes: 1417 Town of residence: San Francisco - California - 840 1418 Age categorization: over 21 1420 If Alice asks for an access token that only contains: 1421 Town of residence: Nashville - Tennessee - 840 1423 and Bob asks for an access token that only contains: 1424 Age categorization: over 21 1426 if they agree to collaborate, they will not be able to combine their 1427 attributes to perform an operation on the server managed by the town 1428 of Nashville, since they will not contain the same binding user 1429 identifier ("buid"). 1431 It is proposed to use to the wording "binded token" to designate 1432 an access token that contains a binding user identifier. 1434 Note: It should be noted that access tokens do not need to be 1435 "protected" by a private key known by the client. Such a 1436 protection would be illusory, since a collaborative client 1437 could perform all the cryptographic computations that 1438 another collaborative client would need to claim to be the 1439 "owner" of the access token. This can be done even these 1440 private keys are protected using an hardware security 1441 module (HSM). 1443 5. Privacy Considerations 1445 ISO/IEC 29100 (Privacy framework) [ISO29100] lists eleven privacy 1446 principles that are valid in a system with two entities which 1447 correspond in this document to the relationships between one 1448 end-user and one RS. 1450 Note: ISO/IEC 29100 is available from ISO for free. 1452 Among the privacy principles from ISO/IEC 29100 enumerated on page 1453 14 in Table 3, the following privacy principles are particularly 1454 important: 1456 - Individual participation 1457 - Purpose legitimacy and specification, 1458 - Consent and choice, 1459 - Collection limitation, 1460 - Data minimization, 1461 - Use, retention and disclosure limitation, 1462 - Openness, transparency and notice. 1464 Since this document considers two access control schemes: Attribute 1465 Based Access Control (ABAC) and Capability Access Control (CBAC), 1466 the privacy considerations for both of them are first addressed 1467 (section 5.1) followed by the privacy considerations for each of 1468 them (sections 5.2 and 5.3). 1470 However, the current document considers a more complex system with 1471 at least three entities: the end-user, the RS and the AS, where each 1472 of them may exists more than once. 1474 In this environment, some additional privacy properties also need to 1475 be considered, in particular those that apply between RSs (section 1476 5.4) and privacy properties that apply between the end-user and the 1477 AS (section 5.5). 1479 5.1. Privacy Considerations for both ABAC and CABC 1481 Since the AS knows some attributes from the end-user, applying the 1482 "individual participation" principle from ISO/IEC 29100, means 1483 giving to the end-users the ability to access and review their 1484 attributes, provided their identity is first authenticated with an 1485 appropriate level of assurance and using a language which is both 1486 clear and appropriately adapted to the circumstances. 1488 This principle is reached using queries from an end-user to an AS 1489 (see section 2.2) since such a query is performed once the client 1490 has established an HTTPS connection with the AS and the end-user has 1491 successfully authenticated with the AS. 1493 For both ABAC and CABC a user account SHALL be created on the RS. 1494 This account may be either short-term or long-term. For a long-term 1495 user account, at the moment, the end-user needs to choose between 1496 hiding to the AS the URL of the RS or allowing RSs to link their 1497 user accounts. 1499 5.1.1. Privacy Considerations for ABAC 1501 In this access control scheme, end-user attributes need to be 1502 presented to the RS. The end-user SHALL be able to : 1504 - select the AS that will be contacted to deliver attributes, 1506 - know which attribute types and attribute possibly values are 1507 requested by the RS, 1509 - know the reasons and/or the rational for providing these 1510 attribute types and possibly values, 1512 - consent or disagree with the provision of these attributes 1513 from an AS that he has selected. 1515 The previous functionalities are supported by a local dialogue 1516 between the end-user and the client and by another dialogue between 1517 the end-user and the RS. 1519 This allows adhering to the purpose of legitimacy principle: 1520 communicating the purpose(s) to the end-user before the time the 1521 information is collected or used for the first time for a new 1522 purpose. 1524 It is possible for the client to hide to the AS the URL of the RS. 1525 However, at this time, until a secure element is being used, the 1526 price to pay for that feature is to allow RSs to link their user 1527 accounts. So the end-user will have to make a choice between these 1528 two features. 1530 Note: The core principles of ABAC permit to the client to hide 1531 to the AS the method that will be performed on a resource 1532 as well as the URL of that resource. 1534 5.1.2. Privacy Considerations for CBAC 1536 In this access control scheme, capabilities need to be presented to 1537 the RS. The end-user SHALL be able to : 1539 - select the AS that will be contacted to deliver capabilities, 1541 - consent or disagree with the provision of these capabilities 1542 from an AS that he has selected. 1544 The above functionalities are supported by using a local dialogue 1545 between the end-user and the client. 1547 The core principles of CBAC do not permit the end-user to hide to 1548 the AS the URL of the RS, nor to hide to the AS the URL of the 1549 resource, nor to hide to the AS the method that will be performed 1550 on the resource. 1552 5.2. Privacy Considerations between RSs 1554 Two RSs should not be able to link their user accounts, by using the 1555 content of the access tokens they receive from the same AS or from 1556 different ASs. This property may be referred as: Unlinkeability 1557 between RS user accounts. For short-term user accounts, it is 1558 always achieved. However, for long-term user accounts, it may only 1559 be achieved, for the moment, if the client/end-user accepts to 1560 disclose to the AS the URL of the RS. 1562 5.3. Privacy Considerations between the end-user and the AS 1564 5.3.1. Transparency 1566 When a client receives an access token from an AS, it should be able 1567 to verify that the access token contains the requested privileges, 1568 i.e. no more or not less, and, if not, it should be able to prevent 1569 the transmission of the access token to the RS. 1571 This property can be achieved as long as "Token introspection", as 1572 currently described in OAuth, is not being used. It should be 1573 noticed that Token introspection may allow an AS to deliver to the 1574 client more privileges than the ones inserted into an access token. 1576 These two properties are directly related to the "Transparency" of 1577 the system since they allow the end-users to be confident in the 1578 system they are using. 1580 For these reasons, access tokens are not considered to be opaque 1581 to the clients but may be considered to be opaque for the end-users. 1583 5.3.2. Hiding to the AS the URL of the RS and its use 1585 The AS should not be able to know when an issued access token will 1586 be indeed consumed by a RS. This property can be achieved by using 1587 the "hidden_url" field and as long as "Token introspection" is not 1588 being used. 1590 6. References 1592 6.1. Normative References 1594 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1595 Resource Identifier (URI): Generic Syntax", STD 66, 1596 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1597 . 1599 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1600 Housley, R., and W. Polk, "Internet X.509 Public Key 1601 Infrastructure Certificate and Certificate Revocation 1602 List(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, 1603 May 2008. . 1605 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1606 Verification of Domain-Based Application Service Identity 1607 within Internet Public Key Infrastructure Using X.509 1608 (PKIX) Certificates in the Context of Transport Layer 1609 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 1610 2011, . 1612 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, 1613 A., Galperin, S., and C. Adams, "X.509 Internet Public 1614 Key Infrastructure Online Certificate Status Protocol - 1615 OCSP", RFC 6960, DOI 10.17487/RFC6960, June 2013, 1616 . 1618 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 1619 Transfer Protocol (HTTP/1.1): Semantics and Content", 1620 RFC 7231, DOI 10.17487/RFC7231, June 2014, 1621 . 1623 [RFC7235] R. Fielding, J. Reschke, Hypertext Transfer Protocol 1624 (HTTP/1.1): Authentication, June 2014, 1625 1627 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1628 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1629 May 2017, 1631 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) 1632 Data Interchange Format", STD 90, RFC 8259, DOI 1633 10.17487/RFC8259, December 2017, 1634 1636 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) 1637 Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, 1638 August 2018, . 1640 6.2. Informative References 1642 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1643 Requirement Levels", BCP 14, RFC 2119, 1644 DOI 10.17487/RFC2119, March 1997, 1645 . 1647 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 1648 "Recommendations for Secure Use of Transport Layer 1649 Security (TLS) and Datagram Transport Layer Security 1650 (DTLS)", BCP 195, RFC 7525, May 2015. 1651 1653 [OIDC_1.0] OpenID Connect Core 1.0 specification 1654 1656 [ISO29100] Information technology - Security techniques - Privacy 1657 framework. 2011. ISO/IEC 29100 is available for free at: 1658 https://standards.iso.org/ittf/ 1659 PubliclyAvailableStandards/c045123_ISO_IEC_29100_2011.zip 1661 [GDPR] Regulation (EU) 2016/679 of the European Parliament and 1662 of the Council of 27 April 2016 on the protection of 1663 natural persons with regard to the processing of personal 1664 data and on the free movement of such data, and repealing 1665 Directive 95/46/EC (General Data Protection Regulation). 1666 1668 Authors' Address 1670 Denis Pinkas 1671 DP Security Consulting 1673 Email: denis.ietf@free.fr