Internet DRAFT - draft-pinkas-gnap-core-protocol
draft-pinkas-gnap-core-protocol
D. Pinkas
Internet-Draft DP Security Consulting
Intended status: Standards Track
Expires: 20 February 2022 19 August 2021
Grant Negotiation and Authorization Protocol
draft-pinkas-gnap-core-protocol-00
Abstract
This protocol enables an Authorization Server (AS) to issue access
tokens to permit an end-user using a client software to perform
operations on a protected resource hosted by a Resource Server (RS).
These access tokens allow to support capabilities and/or user
attributes.
The protocol includes means of specifying how the end-user can
potentially be involved in an interactive fashion during the
process. The client and/or the RS will use these interaction
mechanisms to involve the end-user, as necessary, to take decisions.
The protocol uses HTTPS for all communications between the client
and the AS, as well as between the client and the RS.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as
reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on 20 February 2022.
Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved.
Pinkas Expires 20 February 2022 [Page 1]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your
rights and restrictions with respect to this document. Code
Components extracted from this document must include Simplified BSD
License text as described in Section 4.e of the Trust Legal
Provisions and are provided without warranty as described in the
Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . .3
1.2. Vocabulary . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Abbreviations . . . . . . . . . . . . . . . . . . . . . . .4
1.4. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . .4
1.5. Trust relationships . . . . . . . . . . . . . . . . . . . .6
1.6. Prior arrangements before the protocols can be used . . . .8
1.7. Short term and long term user accounts . . . . . . . . . . 8
1.8. Structure of an access token . . . . . . . . . . . . . . . 8
1.8.1. Signed part of an access token . . . . . . . . . . . . 9
1.8.2. Unsigned part of an access token . . . . . . . . . . 10
1.9. Mandatory checks to be done by a RS on an access token . .11
2. An overview of the protocols . . . . . . . . . . . . . . . . .12
2.1. RS and AS Discovery APIs . . . . . . . . . . . . . . . . .13
2.1.1. RS Discovery API . . . . . . . . . . . . . . . . . . .13
2.1.2. AS Discovery API . . . . . . . . . . . . . . . . . . .14
2.2. Queries from an end-user to an AS . . . . . . . . . . . . 14
2.3. Creation a long-term user account on a RS . . . . . . . . 15
2.3.1. The RS already "knows" the end-user . . . . . . . . . 15
2.3.2. The RS does not already "know" the user . . . . . . . 18
2.4. Creation a short-term user account on a RS . . . . . . . .19
2.5. Operation on a resource hosted by a RS . . . . . . . . . .20
2.5.1. Operation on a resource without an access token . . . 20
2.5.2. Operation on a resource using an access token . . . . 22
2.5.2.1. Dialogue between the end-user and his client . . .22
2.5.2.2. Dialogue between the end-user and the RS . . . . 23
2.5.2.3. The access token request . . . . . . . . . . . . .24
2.5.2.4. The access token response . . . . . . . . . . . . 26
2.6. Flow of operations for one access . . . . . . . . . . . . 26
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
4. Security Considerations . . . . . . . . . . . . . . . . . . . 27
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . .28
5.1. Privacy Considerations for both ABAC and CABC . . . . . . 29
5.1.1. Privacy Considerations for ABAC . . . . . . . . . . . 30
5.1.2. Privacy Considerations for CBAC . . . . . . . . . . . 30
5.2. Privacy Considerations between RSs . . . . . . . . . . . .31
5.3. Privacy Considerations between the end-user and the AS . .31
5.3.1. Transparency . . . . . . . . . . . . . . . . . . . . . .31
5.3.2. Hiding to the AS the URL of the RS and its use . . . . .31
6. References . . . . . . . . . . . . . . . . . . . . . . . . . .32
6.1. Normative References . . . . . . . . . . . . . . . . . . .32
6.2. Informative References . . . . . . . . . . . . . . . . . .33
Pinkas Expires 20 February 2022 [Page 2]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
1. Introduction
This protocol allows end-users to interact with a piece of software,
the client instance, to request access tokens to Authorization
Servers (ASs) to perform operations either on protected resources
hosted by a Resource Server (RS) or on the RS itself to create a
user account.
The protocol also allows end-users to collect from an AS information
about themselves.
When an end-user is willing to perform an operation on a protected
resource hosted by a RS or on the RS itself to create a user
account, the end-user operating the client interacts with the RS to
assert his consent, authenticates to the AS and then requests an
access token from the AS.
The protocol allows to support Attribute Based Access Control
(ABAC), as well as Capability Based Access Control (CBAC), where a
capability is an authorization to perform an operation on a
resource.
This specification also discusses discovery mechanisms for the
client instance to discover the access token formats supported by a
RS or an AS and whether attributes (for ABAC) and/or capabilities
(for CBAC) are needed in order to perform a given operation on a
resource or a registration on a RS.
The focus of this protocol is to provide interoperability between
the different parties acting in each role, but is not to specify
implementation details of each. However the structure of access
tokens is detailed, but the syntax of the access tokens is left
open. The security of the protocol relies on the presence and on
the verification by the RS of some of the fields that must be
present in an access token.
The protocol takes into consideration the ease of use for the
end-user: an end-user can use any number of clients without the
burden to manage them (as long as he can trust the client instance).
The protocol also take into consideration some privacy laws and
recent regulations (e.g. the EU General Data Protection Regulation)
[GDPR] in order to allow the RSs to comply with the legislation.
Direct communications between an AS and a RS are not necessary for
the execution of this protocol. The means for an AS and a RS to
interoperate directly are not discussed in this document.
1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Pinkas Expires 20 February 2022 [Page 3]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
1.2. Vocabulary
attribute : characteristics related to an end-user
right : ability given to an end-user to perform a given operation on
a protected resource under the control of a RS
Note: a "right" is denoted as a "capability" in the security
literature.
access token : data artifact representing a set of rights and/or
attributes
grant (verb) : to permit an instance of client software to receive
some attributes at a specific time and valid for a specific
duration and/or to exercise some set of delegated rights to
access a protected resource
grant (noun) : the act of granting
privilege : right or attribute associated with an end-user
protected resource : API (Application Programming Interface) served
by an RS and that can be accessed by a client, if and only
if a valid access token is provided.
1.3. Abbreviations
ABAC Attribute Based Access Control
CBAC Capability Based Access Control
1.4. Roles
The parties in GNAP perform actions under different roles.
Roles are defined by the actions taken and the expectations
leveraged on the role by the overall protocol.
Resource Server (RS) : server that provides operations on resources,
where operations on resources protected by GNAP require a valid
access token issued by an Authorization Server (AS)
Authorization Server (AS) : server that grants delegated privileges
to a particular instance of client software in the form of access
tokens
Client : application operated by an end-user that consumes resources
from one or several RSs, possibly requiring access tokens from
one or several ASs
End-user : natural person that operates a client instance
Pinkas Expires 20 February 2022 [Page 4]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
Example: a client can be a mobile application, a web application,
etc.
Resource Owner (RO) entity that may grant or deny operations
on resources it has authority upon
Note: the act of granting or denying an operation may be manual
(i.e. through an interaction with a physical person) or automatic
(i.e. through predefined rules).
The following Figure 1 illustrates the relationships between the
different roles
+---------------+
| |
| Authorization |
+---------->| Server |
| | |
| +---------------+
| ~
| ~ When CBAC is supported
| ~
+----------+ +---------------+
+----------+ | | | |
| End-user |+ + +| Client | | Resource |
+----------+ | Instance | | Owner |
| | | |
+----------+ +---------------+
| ~
| ~ When ABAC is supported
| ~
| +---------------+
| | |
+---------> | Resource |
| Server |
| |
+---------------+
Legend
+ + + indicates an interaction between a human and computer
----- indicates an interaction between two pieces of software
~ ~ ~ indicates a possible interaction between two roles
Figure 1: Relationships between the different roles
When a resource hosted by the RS is access control protected using
attributes (ABAC), then the RO interfaces with the RS.
When a resource hosted by the RS is access control protected using
capabilities (CBAC), then the RO interfaces with the AS.
Pinkas Expires 20 February 2022 [Page 5]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
A RS may host protected resources where some of them are access
control protected using attributes and while some others are access
control protected using capabilities. A same resource can even be
protected using attributes and capabilities.
1.5. Trust relationships
All the exchanges between a Client and a RS SHALL be protected using
HTTPS, i.e. HTTP [RFC7231] over TLS [RFC8446]. The verification of
the identity of the RS shall be done according to RFC 6125
[RFC6125].
All the exchanges between a Client and an AS SHALL be protected
using HTTPS, i.e. HTTP [RFC7231] over TLS [RFC8446]. This includes
the authentication exchange between an end-user and an AS. The
verification of the identity of the AS shall be done according to
RFC 6125 [RFC6125].
In order to trust an AS public key certificate or a RS public key
certificate, a client SHALL install and use a trust anchor that
allows to verify each AS or RS public key certificate. The overall
certification scheme SHALL allow each client to test the revocation
status of each AS or RS public key certificate using CRLs [RFC5280]
or OCSP [RFC6960].
In order to trust an AS public key certificate, a RS SHALL install
and use a trust anchor that allows to verify each AS public key
certificate. The overall certification scheme SHALL allow each RS
to test the revocation status of each AS public key certificate.
In order to allow for the revocation of the public key certificate
of an AS or a RS, the public key that allows to verify that public
certificate SHALL itself be certified using a public key certificate
issued by an upper CA.
The end-user is trusting his client to manage the interactions with
the AS and with the RS, whether these interactions are performed
using APIs or using a User Interface (UI).
The end-user is trusting the AS to manage his attributes and, upon
request, to disclose them to his client.
In order to allow the checking of the integrity and the authenticity
of the content of an access token, each AS SHALL sign its access
tokens using a private key certified by a CA (Certification
Authority).
For the delivery of either rights or attributes in an access token,
a RS may trust one or more ASs.
The remaining trust conditions are different whether rights or
attributes are supported by the RS to allow performing operations on
a given resource under the control of an RS.
Pinkas Expires 20 February 2022 [Page 6]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
Rights
An access control scheme where rights are supported by the RS to
perform operations on a resource is usually known in the security
literature as a system using capabilities. When rights are
supported by a RS to allow performing operations on a resource under
the control access token.
In such a case, an of the RS, the RS may trust one or more ASs for
the delivery of rights in arrangement needs to be established
between each AS/RS pair: the RS MUST designate to the AS a RO that
will be responsible to deliver rights which will be placed into
access tokens.
For each resource protected using capabilities and for each
authenticated user, the responsible RO is able to indicate to the AS
which operations may be permitted on the resource by an
authenticated end-user.
A RS may decide to accept from a given RO only a reduced set of
operations on some resources.
By default and in order to allow interoperability tests, all the
resources placed under the control of one RS SHOULD be managed by a
single RO. Using private arrangements between the RS and the AS,
finer or coarser granularities may override the default behavior.
Attributes
An access control scheme where attributes are supported by the RS to
perform operations on a resource is usually known in the security
literature under the acronym of ABAC (Attribute Based Access
Control). When attributes are supported by a RS to allow performing
operations on a resource under the control of a RS, the RS may trust
one or more ASs for the delivery of attribute types and/or attribute
values in access tokens.
For each resource protected using attributes, the responsible RO is
able to indicate to the RS which operations may be permitted on the
resource, when a proper set of attribute types and attribute values
are present in an access token.
In such a case, the RS may globally indicate which attribute types
and/or attribute values in access token will be accepted from a
given AS.
Note: It should be observed that when attributes are being used the
AS does not need to perform any kind of pre-arrangement with the
RSs.
Pinkas Expires 20 February 2022 [Page 7]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
1.6. Prior arrangements before the protocols can be used
The following arrangements are supported using out-of-bands means
that are outside the scope of the protocol.
Every end-user MUST have an account opened with at least one AS.
When the account is settled between the end-user and the AS, a user
identifier and an authentication method SHALL be agreed. The end-
user MUST receive information that allows him to perform a first
authentication exchange with success.
When capabilities are supported by a RS, that RS SHALL designate a
RO that will interface with at least one AS.
1.7. Short term and long term user accounts
Two types of accesses may be proposed by a RS to allow an end-user
to use:
- short-term user accounts, or
- long-term user accounts.
In the first case, the user may be willing to remain anonymous
towards the RS by either using a capability or disclosing a set of
attributes that will be insufficient to identify him unambiguously.
Once the session will be closed, the RS will not maintain
information about the session, except in his audit trail.
In the second case, the user may be willing to retrieve some data,
to deposit some data or to modify some data that will be saved by
the RS. A typical example, is an access to a bank account.
1.8. Structure of an access token
This section describes the structure of an access token by
enumerating both required and optional fields.
For each field, it prescribes both its semantics and the processing
that SHALL be done on it, but it does not prescribe its syntax. In
the future, additional documents may define detailed access token
formats including their encoding.
An access token is composed of two parts: a signed part and an
unsigned part which is optional.
Before accepting an access token, a RS SHALL check the mandatory
fields of the access token.
Pinkas Expires 20 February 2022 [Page 8]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
1.8.1. Signed part of an access token
This part contains:
- a required field (called "valid") that indicates the validity
period of the access token using the UTC time. The start of
the validity period is the time at which the access token was
issued.
- a required field (called "as_pkc") that allows to identify the
issuer of the access token, i.e. the AS. Either the PKC
(Public Key Certificate) [RFC5280] of the AS SHALL be included
or, if the corresponding certificate is placed in the unsigned
part of the access token, a hash value of that certificate
SHALL be included.
- an optional field (called "hash_algo") that indicates the
identifier of the hash algorithm used to compute the digital
signature of the access token.
- one of the two following optional fields, i.e. "rs_url" or
"hidden_url", SHALL be present:
- an optional field (called "rs_url") that allows a RS to
make sure that the access token is indeed intended for
itself. That field SHALL contain at least one URL of a RS.
- an optional field (called "hidden_url") that allows a RS
to make sure that the access token is intended for itself.
That field SHALL contain at least one value that MUST be
combined with a field ("reveal_url") from the unsigned part
of the access token to recover the real value of the target
URL of a RS.
- a required field (called "buid") which is a "binding user
identifier" that allows a RS to verify that the access token is
associated with the right (short-term or long-term) user
account. This field allows to detect the inappropriate use of
an access token by a malicious user, including in the case of
a collusion between users. This field is composed of a type
chosen by the client and of a value chosen by the AS. Five
different types may be requested by the client :
The first four types are used in the context of long-term user
accounts managed by the RS, while the last type is used in the
context of short-term user accounts managed by the RS.
The four types used in the context of long-term user accounts
managed by a RS are:
(1) a unique user identifier used to identify a user for each
User/ RS pair, or
Pinkas Expires 20 February 2022 [Page 9]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
Note: this option cannot be implemented in the context of
a "software-only" solution. It requires the use, by the
end-user, of a secure element with specific security
properties. [This option is not detailed any further at
the moment].
(2) a unique user identifier used to identify a user for each
AS / RS pair, or
(3) a locally unique user identifier used to identify a user
whatever RS is being involved, or
(4) a globally unique user identifier.
The last type used in the context of short-term user accounts
managed by a RS is:
(5) a short-term user unique identifier.
Note: The four first types are used when a long-term user account is
being used on a RS. The last and fifth type is used when a
short-term user account is being used on a RS.
- at least one of the two following optional fields, i.e. "attrs"
or "rights", SHALL be present (both may be present):
- an optional field (called "attrs") that contains one or more
attributes that are associated with the end-user. This field
is an array where each element of the array is composed of
the identifier of an attribute type and of the associated
attribute value.
- an optional field (called "rights") that contains one or more
rights (i.e. capabilities) that have been granted to the user
by a RO hosted by the AS and which is associated with the RS
protecting the resource. This field is an array where each
element of the array is composed of one or more methods and
of the URL of a resource.
- an optional field (called "at_uid") that contains a unique
identifier for the access token. The identifier value MUST be
assigned by the AS in a manner that ensures that there is a
negligible probability that the same value will be accidentally
assigned twice. This field may be useful for audit purposes.
1.8.2. Unsigned part of an access token
This part contains:
- the signature value (called "sign") of the access token.
Pinkas Expires 20 February 2022 [Page 10]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
- an optional field (called "path") that contains a certification
path [RFC5280], starting with the PKC of the AS.
- an optional field (called "reveal_url") that allows to retrieve
the true value(s) of the URL(s) of RS(s) that has (have) been
hidden to the AS.
This field is an array where each element of the array is
composed of a random value called "rnd_value" and a method
identifier. If the field "hidden_url" is present in the signed
part of the access token, then the field "reveal_url" MUST be
present. This field MUST be used by the RS to combine the
"hidden_url" value with the appropriate "rnd_value" to verify
that the end result matches with its own URL value.
A one way hash function (OWHF) SHALL be used by the client to
compute the "hidden_url" to be placed into the access token, by
first choosing a large random number for the "reveal_url" value
and combining it with the base URL of the RS using the following
formula: "hidden_url" = OWHF ("reveal_url", RS_URL). When the
client receives the access token from the AS and before
communicating it to the RS, the "reveal_url" value SHALL be
inserted by the client into the unsigned part of the access
token.
1.9. Mandatory checks to be done by a RS on an access token
When a resource is protected using GNAP, several checks need to be
done.
The ordering of the following checks is not mandated as long as all
the checks are performed.
However, the following list has been established taking into
consideration that an invalid access token should be rejected as
soon as possible which means that the fastest checks should be done
before.
When receiving an access token, the RS SHALL check that:
- it is well-formed,
- it contains an "attrs" field if the RS supports attributes and it
contains a "rights" field if the server supports capabilities.
If a RS supports both, one of these two fields SHALL be present.
- the access token is currently within its validity period by using
the "valid" field and the UTC time. The start of the validity
period cannot be sooner than the current time expressed using the
UTC time. A time skew of a dozen of seconds SHOULD be allowed.
The validity period of the access token SHOULD NOT exceed 25
hours.
Pinkas Expires 20 February 2022 [Page 11]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
- that the access token is indeed targeted to itself by using either
the "rs_url" field or the "hidden_url" field, and in the later
case also the "reveal_url" field.
When the RS receives an access token that contains both an
"hidden_url" and a "reveal_url" field, it SHALL verify that the
access token is targeted to itself, by using its RS_URL and then
computing the value: OWHF (reveal_url, RS_URL) and finally verify
that it matches with the value contained in the "hidden_url" field.
- that the access token is apparently coming from one of the ASs
trusted by the RS using the DN (Distinguished Name) of the AS that
is present in the AS's PKC.
In order to perform that check, the AS's PKC SHALL be retrieved
either directly from the "as_pkc" field or using the hash value
of that PKC if present in the "as_pkc" field to retrieve it from
the "path" field. The validity period of that PKC [RFC5280] SHALL
be verified.
- that the signature of the access token is valid. In order to
perform this verification, the RS SHALL first construct a
certification path between an appropriate trust anchor and the
RS's PKC [RFC5280]. If present, the field "path" SHOULD be used
to construct that certification path. Once the certification path
has been verified as being valid (taking in consideration the
revocation status of each PKC from the certification path) the
certified key SHALL be extracted from the PKC and used to verify
the field "sign" of the access token [RFC5280]. Depending upon
the public key algorithm being used, the field "hash_algo", if
present, SHALL also be used.
Note: additional checks depend whether the resource is protected
using attributes or capabilities.
2. An overview of the protocols
Different protocols can be used for different purposes:
(1) to discover the main features supported either by a RS or
an AS;
(2) to allow an end-user to query which of his attributes are
known by an AS;
(3) to create a long-term user account on a RS (that will last
between different sessions) using an access token;
(4) to create a short-term user account on a RS (that will last
during the duration of a single session) using an access
token;
Pinkas Expires 20 February 2022 [Page 12]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
(5) to perform an operation on a resource hosted by a RS.
2.1. RS and AS Discovery APIs
2.1.1. RS Discovery API
A GNAP RS can publish its features on a well-known discovery
document using the URL ".well-known/gnap-rs" appended to the
base URL of the RS.
The discovery response is a JSON document [RFC8259] consisting of a
single JSON object with the following fields:
trusted_AS (array) : REQUIRED: A list of the ASs trusted by the RS.
The array contains an enumeration of ASs and for each AS, the
following information SHALL be present :
- the base URL of the AS, and
- one AS PKC.
It is RECOMMENDED to include an image within the AS certificate
according to RFC 6170 (Internet X.509 Public Key Infrastructure
Certificate Image). The purpose of the certificate image is to
aid human interpretation of a certificate by providing meaningful
visual information to a user interface (UI).
In addition it is RECOMMENDED to publish the next AS PKC, when it
has already been issued by the responsible CA.
Note: the ordering of these ASs is important. See section 5.1.
user_interaction_endpoint (string): REQUIRED. The location of
the RS's user interaction endpoint, used by the client to conduct
a dialogue between the end-user and the RS.
The goal of this dialogue is to present one or more options to
the end-user, so that, after being informed of the consequences
of these options, he may provide its consent to the RS.
The location MUST be a URL [RFC3986] with a scheme component
that MUST be https, a host component, and optionally, port, path
query components and no fragment components.
RS_token_formats_&_syntaxes_supported (array of strings) OPTIONAL:
A list of token formats and syntaxes supported by the RS.
long_term_user_account (Boolean) OPTIONAL: indicates whether
long-term user accounts are supported by the RS.
short_term_user_account (Boolean) OPTIONAL: indicates whether
short-term user accounts are supported by the RS.
Pinkas Expires 20 February 2022 [Page 13]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
Note : either the long_term_user_account flag or the
short_term_user_account flag MUST be present and set to TRUE.
user_registration_endpoint (string): OPTIONAL. The RS's user
registration endpoint, used by the client to create either a
short-term user account or a long-term user account.
rs_cert_path (array): OPTIONAL. A set of CA certificates that may
help a client to built a certification path between a RS
certificate and a trust anchor.
2.1.2. AS Discovery API
A GNAP AS can publish its features on a well-known discovery
document using the URL ".well-known/gnap-as" appended to the
base URL of the AS.
The discovery response is a JSON document [RFC8259] consisting of a
single JSON object with the following fields:
attributes_supported (Boolean) OPTIONAL: indicates whether
attributes requested by the end-user may be included into
an access token.
capabilities_supported (Boolean) OPTIONAL: indicates whether
capabilities requested by the end-user may be included into
an access token.
Note : either the attributes_supported Boolean or the
capabilities_supported Boolean MUST be present and set to TRUE.
AS_token_formats_&_syntaxes_supported (array of strings) OPTIONAL:
A list of token formats and syntaxes supported by the AS.
grant_request_endpoint (string): REQUIRED. The location of the
AS's grant request endpoint, used by the client to request access
tokens. The location MUST be a URL [RFC3986] with a scheme
component that MUST be https, a host component, and optionally,
port, path query components and no fragment components.
as_cert_path (array): OPTIONAL. A set of CA certificates that may
help a client to built a certification path between an AS
certificate and a trust anchor.
2.2 Queries from an end-user to an AS
Before making this query, the client SHALL establish an HTTPS
connection with the AS. The client SHOULD be able to communicate
to the AS the preferred language(s) of the end-user. The end-user
SHALL successfully authenticate with the AS.
Pinkas Expires 20 February 2022 [Page 14]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
Any kind of authentication method can be used, e.g. using asymmetric
cryptography, symmetric cryptography or even using end-user
identifiers associated with (long) passwords, since the connection
is both integrity and confidentiality protected using HTTPS.
Since the AS knows some attributes that belong to the end-user, they
will be returned in the response to this query. Each attribute has
a type and a value. These attributes are considered as personal
data and, as such, the end-user SHALL be able to have access to
them. In some cases, it may be allowed to correct some of them or
to propose corrections to them.
Note: In this case, no access token will be returned.
2.3. Creation a long-term user account on a RS
Two different cases needs to be considered, whether the RS already
"knows" the end-user or not. The client SHOULD first make sure that
the RS has set the long_term_user_account flag, otherwise no long-
term user account can be created.
2.3.1. The RS already "knows" the end-user
The RS may already "know" the end-user because it already holds some
information about him and the end-user is already identified by the
RS under a user account number.
The user would like now to like to get on on-line access to perform
some operations on some information associated with his user
account.
The client performs a RS Discovery operation to know which ASs are
trusted by the RS. If the user has an account on one of these ASs,
the end-user (or the client) may select one of these ASs.
The RS asks the client to provide some user attributes types already
known by the AS that has been selected by the client. The dialogue
with the end-user SHALL be handled using the
user_interaction_endpoint.
The RS allows the user to know the reason(s) why such attribute
types are being requested (User Notice). The user may agree or deny
to provide them (User choice and User Consent) and, if he agrees,
the client will request to the AS an access token that should
contain these attribute types.
For example, the attribute types may be: first name, family name,
birth date and birth location.
Pinkas Expires 20 February 2022 [Page 15]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
In order to detect a possible replay or use of a delivered access
token by an AS for a given RS by another client, the client
indicates that the access token should be protected under, e.g. :
(1) a unique user identifier used to identify a user for each
User/ RS pair;
(2) a unique user identifier issued by the AS to identify the
end-user for each AS / RS pair (e.g. a different pseudonym
for each AS / RS pair), or
(3) a locally unique user identifier used by the AS to identify
the user, whatever server is involved (e.g. a single
pseudonym used for all the servers), or
(4) a globally unique user identifier (e.g. a personal email
address, a social security number including the issuing
country, a passport number including the issuing country,
a driving license including the issuing state or country).
In order to detect the replay of the access token by a RS towards
another RS, the client indicates the identifier of the intended RS.
The fields "rs_url" or "hidden_url" of the access token may be used
to allow such a detection.
The returned access token will include some attributes. These
attributes are placed in the "attrs" field of the access token.
The returned access token will then include in the "binding user
identifier" field ("buid") of the access token, the type of the
binding unique user identifier requested and a value assigned by
the AS.
If the attribute types and values contained in the access token
match with the already known attribute types and values, the
operation will be granted.
It should be observed that, when using the choice (2), it is not
possible to hide to the AS the URL of the RS, since this value is
needed to generate a different pseudonym for each AS / RS pair.
It may be observed that, when using the choice (3), it is possible
to hide to the AS the URL of the RS, since this value is not needed
to generate a single pseudonym used for all the servers. However,
in this case, all the RSs receiving access tokens from the same AS
are able to link their user accounts.
It may be observed that, when using the choice (4), it is possible
to hide to the AS the URL of the RS, since this value is not needed
to generate a globally unique user identifier. However, in this
case, not only all the RSs receiving access tokens from the same AS
will be able to link their user accounts, but also other servers
using the same globally unique user identifier.
Pinkas Expires 20 February 2022 [Page 16]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
The choice (4) should be avoided, unless all the RSs issuing
attributes or rights are managed by the same organization that is
managing the AS and that organization is purposely willing to link
all the user accounts of its RSs. At the moment, the "best" choices
in the Internet environment are be restricted between the choices
(2) and (3) and will be a compromise between two privacy properties,
where each of these two choices has an advantage and a drawback :
- the choice (2) does not allow to hide to the AS the URL of the
RS, but prevents the RSs receiving access tokens from the same
AS to link their user accounts, while
- the choice (3) allows to hide to the AS the URL of the RS, but
allows the RSs receiving access tokens from the same AS to link
their user accounts.
That choice will be left to the end-user (or to the client).
Note: the choice (1) would allow both to hide to the AS the URL
of the RS and to prevent the RSs to perform a linkage between
their user accounts.
Later on, if the client requests another access token, the client
or the end-user should remember its original choice, e.g. (2)
or (3), for the same RS, otherwise the access token will be rejected
by the RS.
It is recommended that each client locally manages for each end-user
a "privacy preference profile" to associate a choice value with the
base URL of each RS.
In order to detect the replay of the access token by a RS towards
another RS, the client indicates the identifier of the intended RS
using either the "rs_url" field for the choice (2) or the
"hidden_url" field for the choice (3) of the access token.
The returned access token will then include some attributes in the
field "attrs" of the access token and the binding user identifier
issued by the AS in the field "buid" of the access token.
Before presenting this access token to the RS, the end-user SHALL
establish an HTTPS connection with the RS. Then after, the access
token SHALL be send to the user_registration_endpoint of the RS.
Once the RS has verified that the access token is valid, it
memorizes the "binding user identifier" field ("buid") of the access
token. All subsequent access tokens issued by that AS SHALL contain
the same value, otherwise they will be rejected.
It is recommended that each client locally manages for each end-user
a "privacy preference profile" to associate a choice value with the
base URL of each RS.
Pinkas Expires 20 February 2022 [Page 17]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
2.3.2. The RS does not already "know" the user
The RS does not yet "know" the user: he has no user account for the
end-user on that RS. The end-user wants to create a user account.
The client performs a RS Discovery operation to know which ASs are
trusted by the RS. If the user has an account on one of these ASs,
the end-user (or the client) may select one of these ASs.
In order to create a RS user account, a RS will likely ask for both
claimed attributes and certified attributes (i.e. attributes
contained in an access token delivered by an AS trusted by the RS).
Claimed attributes are simply attributes declared by the user.
The user_interaction_endpoint of the RS will be used to conduct a
dialogue between the RS and the end-user in order to request both
claimed attributes and certified attributes. During that dialogue,
the end-user has the ability to know the reason(s) an/or the
rational for the collection of each attribute type and which kind of
treatment will be made of it.
Once the end-user has agreed to request some attributes types to the
selected AS, the client requests to that AS an access token that
contains some attribute types known by that AS.
As in the previous case, in order to detect a possible replay or use
of a delivered access token by an AS for a given RS by another
client, the client indicates that the access token should be
protected under, e.g. :
(1) a unique user identifier used to identify a user for each
User/ RS pair;
Note: this option is only possible when the end-user is
using a specific secure element.
(2) a unique user identifier issued by the AS to identify the
user for each AS / RS pair (e.g. a different pseudonym for
each AS / RS pair), or
(3) a locally unique user identifier used by the AS to
identify the user, whatever server is involved (e.g. a
single pseudonym used for all the servers), or
(4) a globally unique user identifier (e.g. a personal email
address, a social security number including the issuing
country, a passport number including the issuing country,
a driving license including the issuing state or country).
The choice (4) should be avoided. At the moment, the "best" choices
will be restricted between the choices (2) and (3) and will be a
compromise between two privacy properties, since each of these two
choices has an advantage and a drawback :
Pinkas Expires 20 February 2022 [Page 18]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
- the choice (2) does not allow to hide to the AS the URL of the
RS, but prevents the RSs receiving access tokens from the same
AS to link their user accounts, while
- the choice (3) allows to hide to the AS the URL of the RS, but
allows the RSs receiving access tokens from the same AS to
link their user accounts.
If the attribute types and values contained in the access token
match with the expected attribute types and if the requested claimed
attributes are also received, some verifications will be done by the
RS. Such verifications introduce some delay.
This is why the final response about the creation of the user
account on the RS is asynchronous.
Later on, if the client requests another access token, the client
or the end-user should remember its original choice, e.g. (2) or
(3), for the same RS, otherwise the access token will be rejected by
the RS.
It is recommended that each client locally manages for each end-user
a "privacy preference profile" to associate a choice value with the
base URL of each RS.
In order to detect the replay of the access token by a RS towards
another RS, the client indicates the identifier of the intended RS
using either the "rs_url" field for the choice (2) or the
"hidden_url" field for the choice (3) of the access token.
The returned access token will then include some attributes in the
field "attrs" of the access token and the binding user identifier
issued by the AS.
Before presenting this access token to the RS, the end-user SHALL
establish an HTTPS connection with the RS. Then after, the access
token SHALL be send to the user_registration_endpoint of the RS.
Once the RS has verified that the access token is valid, it
memorizes the "binding user identifier" field ("buid") of the access
token. All subsequent access tokens issued by that AS SHALL contain
the same value, otherwise they will be rejected.
2.4. Creation a short-term user account on a RS
The client performs a RS Discovery operation to make sure that the
RS has set the short_term_user_account flag, otherwise no short-term
user account can be created.
The client performs a RS Discovery operation to know which ASs are
trusted by the RS. If the user has an account on one of these ASs,
the end-user (or the client) may select one of these ASs.
Pinkas Expires 20 February 2022 [Page 19]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
In order to detect a possible replay or use of a delivered access
token by an AS for a given RS by another client, the client
indicates that the access token SHALL be protected using a short-
term user unique identifier.
The client (or the end-user) has then two options: either to hide or
to reveal the URL of the RS. If it wants to hide the URL of the RS,
it can only use one session. For this purpose, it SHALL use the
"hidden_url" field of the access token. In order to connect with
another RS, it SHALL explicitly release that session. If it agrees
to reveal the URL of the RS, it SHALL use the "rs_url" field of the
access token. It can then use multiple short-term sessions with
different RSs in parallel. The two choices are exclusive.
The returned access token will then include in the "binding user
identifier" field ("buid") of the access token, the type of the
binding user identifier requested and a value assigned by the AS.
This value assigned by the AS SHOULD be a large pseudo-random
number.
In order to detect the replay of the access token by a RS towards
another RS, the client indicates the identifier of the target RS.
The fields "rs_url" or "hidden_url" of the access token may be used
to allow such detection.
Note: none of the two optional fields "attrs" and "rights" needs
to be present in this access token.
Before presenting this access token to the RS, the end-user SHALL
establish an HTTPS connection with the RS. Then after, the access
token SHALL be send to the user_registration_endpoint of the RS.
Once the RS has verified that the access token is valid, it
memorizes the "binding user identifier" field ("buid") of the access
token.
All subsequent access tokens issued by that AS SHALL contain the
same value, otherwise they will be rejected.
2.5. Operation on a resource hosted by a RS
2.5.1. Operation on a resource without an access token
The client does not necessarily know in advance, whether the
resource is or is not protected. If the resource is unprotected and
if the API is well formed, then the access will be granted.
When a client instance calls an RS without an access token, or with
an invalid access token, if the resource is protected and if the API
is well formed, then different HTTP errors types may be returned, in
particular:
Pinkas Expires 20 February 2022 [Page 20]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
401 "Unauthorized" which indicates an authentication error. It
always includes a WWW-Authenticate header that describes how to
authenticate.
In this particular case, the RS SHALL respond with a header field
that contains one challenge for the "GNAPv1" scheme and two
additional parameters "attrs" and "rights" to indicate whether the
RS supports attributes and/or rights for that resource.
After each parameter (i.e. "attrs" and "rights") follows a pointer
to the AS(s) trusted by the RS as enumerated in the "trusted_AS"
field from the RS Discovery API.
For example: WWW-Authenticate: GNAPv1 attrs= 1,3,4 rights= 2,3
In this example, both attributes and rights are supported. AS 1
and AS 4 support attributes only, AS 3 supports both attributes and
capabilities (i.e. rights) while AS 2 supports capabilities (i.e.
rights) only.
If either attributes or rights are not supported, the following
values SHALL be used respectively: "attrs= 0" or "rights= 0".
The client SHOULD then use the "RS Discovery API" to find out which
are the ASs trusted by the RS.
403 "Forbidden" which indicates that the server understood the
request but that the client instance does not have permission to
access this resource, even if it has been authenticated. A server
that wishes to make public why the request has been forbidden can
describe that reason in the response payload (if any).
When the request is recognized by the server but sent "without an
access token or with an invalid access token", the HTTP status 403
Forbidden SHOULD be used. If the server wants to make known why a
request is forbidden, it can provide the reason in the payload.
Note 1: 403 "Forbidden" is dedicated to authorization errors,
whereas 401 "Unauthorized" is dedicated to authentication errors.
Note 2: A server that wishes to hide the existence of a forbidden
target resource MAY instead respond with a status code of 404
(Not Found).
404 "Not Found" which indicates either that the server did not find
a current representation for the target resource or that the server
is not willing to disclose that one exists.
405 "Method not allowed" which indicates that the method received in
the request-line is known by the server but not supported by the
target resource. In that case, the server MUST generate an Allow
header field containing a list of the target resource's currently
supported methods.
Pinkas Expires 20 February 2022 [Page 21]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
Note: If the method is incorrect, 405 "Method not allowed" SHALL
have precedence over 403 "Forbidden".
Note: These error codes are defined in RFC 7231 [RFC7231]and
RFC 7235 [RFC7235] as follows:
- 400 Bad Request . . . . . . Section 6.5.1 of RFC 7231
- 401 Unauthorized . . . . . . Section 3.1 of RFC 7235
- 403 Forbidden . . . . . . . Section 6.5.3 of RFC 7231
- 404 Not Found . . . . . . . Section 6.5.4 of RFC 7231
- 405 Method Not Allowed . . . Section 6.5.5 of RFC 7231
- 406 Not Acceptable . . . . . Section 6.5.6 of RFC 7231
2.5.2. Operation on a resource using an access token
The client instance determines which operation on a resource is
needed and which RS to approach for access.
Unless the client already knows from a previous experience what kind
of additional data needs to be presented, the client has the
possibility to query the RS to know which kind of protection is
being used by the RS for that resource.
It requests on operation on the intended resource and voluntarily
omits to send any access token. It will then get an 401
"Unauthorized" error that indicates that GNAPv1 is supported and
whether attributes and/or rights should be presented in an access
token.
It will also know which ASs, if any, are trusted by the RS to
deliver attributes in an access token and which ASs, if any, are
trusted by the RS to deliver capabilities in an access token.
The client instance determines that the RS supports GNAP and the
process may continue.
2.5.2.1. Dialogue between the end-user and his client
The client may be configured by the end-user with the URLs of the
ASs where he has an AS user account. It may then propose to select
one or more ASs showing at the same time, if capabilities or
attributes may be requested on these ASs to be included into an
access token.
If some choices remain, then the client SHOULD ask the end-user to
make these choices. The client then knows which AS has been chosen
and whether attributes (ABAC) or capabilities (CBAC) will later on
be requested to that AS.
Pinkas Expires 20 February 2022 [Page 22]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
The client SHALL determine whether the end-user is willing to make
an access to the RS using a short-term user account or a long-term
user account. Usually, it should know it from the context of the
operation. However, if it doesn't know, it SHALL ask the end-user
to make that choice.
If the client used by the end-user has recently opened a short-term
user account, it SHOULD be usable if it has not been closed,
otherwise a new short-term user account SHOULD be created.
If the access to the RS should be done using a long-term user
account, the same choice as originally made by the end-user for the
binding user identifier when opening his user account on the RS
should be done. If the client locally manages for each end-user a
"privacy preference profile" that associates a choice value with the
base URL of each RS, it should re-use the same choice. Otherwise,
the question should be raised again to the end-user.
2.5.2.2. Dialogue between the end-user and the RS
When using ABAC, a dialogue needs to be established between the end-
user and the RS. Such dialogue needs to be supported using a port
able to support a User Interface (UI). The address of this port
SHALL be published by the RS and made available using the RS
Discovery API. It SHALL be a URL hosted by the RS.
When initiating the dialogue on the UI port of the RS, the client
communicates to the RS which AS has been selected by the end-user.
The RS indicates to the end-user which attribute types and
optionally attribute values should be present in an access token
issued by that AS.
Before making a call to that AS, the end-user may wish to be
informed of the treatments or usages that will be done by the RS
with each requested attribute type, including a possible disclosure
to other third parties. Such information is usually present in a
User Notice. A simple click or a selection of an attribute type
should be sufficient to disclose the terms of this User Notice.
The UI SHALL clearly ask the end-user whether it accepts to request
these attribute types and SHALL require an action or a gesture from
the end-user to indicate its acceptance.
At this point of time, the choice made by the end-user SHOULD be
memorized by the RS and also by the client.
The memorization done by the RS is not for technical reasons, but
to comply with some laws or regulations.
Pinkas Expires 20 February 2022 [Page 23]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
As an example, the General Data Protection Regulation [GDPR] from
the EU indicates in Article 7(1) :
"Where processing is based on consent, the controller SHALL
be able to demonstrate that the data subject has consented
to processing of his or her personal data. "
The memorization done by the client is for technical reasons: the
client SHALL use the choice made by the end-user to request an
access token to the AS that SHOULD include the attribute types
selected by the end-user.
A markup language such as XML needs to be used in order to delineate
the meaning of each field and its value, when present.
Note: when the RS supports CBAC for a protected resource, no
dialogue is needed between the end-user and the RS.
2.5.2.3. The access token request
The client knows whether the access token will be used for a short-
term RS user account or a long-term RS user account.
If a long-term user account is being used, the client SHOULD already
know the privacy preference of the user since they have been chosen
when creating the long-term user account (see section 3). If the
user is using a new client (i.e. device), then the new client SHOULD
inquire it again.
The client already knows whether the resource is protected using
attributes and/or rights (see section 5.1). If it is protected
using attributes, it already knows which types of attributes should
be requested to the AS, and optionally which attribute values.
The request MUST be sent as a JSON object in the body of the HTTP
POST request with Content-Type "application/json".
Each field placed in the body of the HTTP POST request is described
below:
at_format : REQUIRED. The format of the access token.
at_crypto : REQUIRED. The asymmetric crypto algorithm and the one
way hash function to be used for computing the digital signature
of the access token.
val_period (string) OPTIONAL. It is the desired validity period of
the access token expressed in hours and minutes. The AS may
override this value.
Pinkas Expires 20 February 2022 [Page 24]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
buid_type (integer) : REQUIRED. The binding user identifier type
to be used with the RS. The allowed values are 1 to 5.
target_rs (string) : either a "rs_url" value or a
"hidden_url" value that SHALL be placed into the access token.
Note : if the buid_type is set to 2, then a "hidden_url" value
SHALL NOT be accepted.
operations (array of string) : REQUIRED when capabilities are
requested. It is a list of capabilities, where each capability
consists of :
- one or more methods and
- the URL of the protected resource.
attrs_types (array of string) : REQUIRED when attributes are
requested. It is a list of attribute types. These attributes
may be static or computed from a static attribute. As an example,
an age categorization attribute would be a computed attribute
composed of one or two values, like "over 12" and "under 18"
(see min-age and max-age).
The naming and the definitions used in Table 1 (Registered Member
Definitions) from the "OpenID Connect Core 1.0 specification"
[OIDC_1.0] are re-used in this document.
See : https://openid.net/specs/openid-connect-core-
1_0.html#Claims
As a consequence, the following attributes types are defined:
name, given_name, family_name, middle_name, nickname,
preferred_username, profile, picture, website, email,
email_verified, gender, birthdate, zoneinfo, locale,
phone_number, phone_number_verified, address.
In addition, subsets of the previous fields may be returned.
For example, for an address, the country and region only may
be requested. This leads to recognize the following attribute
types: street_address, locality, region, postal_code, country.
In addition, the following attribute types may also be useful:
shipping_address, payment_info, eye_color, max_age, min_age.
In order to support group memberships, the two following
attribute types are also defined: hierarchical_group and
functional_group.
Since a user may belong to more than one functional group, the
value(s) that should be placed into the access token should be
indicated in the request, otherwise all the functional groups
will be returned.
Pinkas Expires 20 February 2022 [Page 25]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
The end-user is able to know which values have been affected to
this attribute type by sending a query to the AS (see section
2.2). As a consequence, the client is able to specify which
attribute value(s) should be returned for the functional_group
attribute type.
2.5.2.4. The access token response
The response MUST be sent as a JSON object in the body of the HTTP
POST request with Content-Type "application/json". It is an access
token. Its semantics and structure are described in section 1.7.
2.6. Flow of operations for one access
Once either a short-term user account or a long-term user account
has been created on a RS, the flow of operations is illustrated
hereafter:
+---------------+
+------------->| |
|(5) | Authorization |
| | Server |
| +-------| |
| |(6) +---------------+
| | ~
| | ~
+----------+ +---------------+
| | | |
+----------+ (3) | Client | | Resource |
| End-user |+ + +| Instance | | Owner |
+----------+ | | | |
^ +----------+ +---------------+
| ^ ^ | ~
| | | | ~
| | | |(7) +---------------+
| | | +------>| |
| | |(2) | |
| | +---------->| Resource |
| |(1) | Server |
|(4 Opt.) +-------------->| |
+--------------------------->| |
User Interface +---------------+
Figure 2: Flow of operations for one access
(1) RS Discovery
(2) Operation on a resource hosted by a RS without an access token
(3) Dialogue between the end-user and the client
(4) Optional dialogue between the end-user and RS
when the RS requests attributes
(5) Access Token request to AS
(6) Access Token response from AS
(7) Access Token presentation to RS
Pinkas Expires 20 February 2022 [Page 26]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
Note: The creation of RS user accounts is not illustrated
on Figure 2.
3. IANA Considerations
This specification will require the registration of the various
attributes types defined in section 5.2.3:
name, given_name, family_name, middle_name, nickname,
preferred_username, profile, picture, website, email,
email_verified, gender, birthdate, zoneinfo, locale,
phone_number, phone_number_verified, address,
street_address, locality, region, postal_code, country,
shipping_address, payment_info, eye_color, max_age, min_age.
4. Security Considerations
Since HTTPS is used between the client and the RS and between the
client and the AS, the client can be confident that the information
it receives is indeed coming from the intended RS and from the
intended AS.
Since the authentication exchange between the end-user and the AS is
protected by HTTPS, the AS can be confident that the end-user is
using the unknown connected client. Any kind of authentication
exchange can be used, including the simple "id and password" scheme,
since the password is both integrity and confidentiality protected
during its transfer.
The appropriate version (or versions) of TLS will vary over time,
based on the widespread deployment and known security
vulnerabilities. Refer to [BCP195] for up to date recommendations
on transport layer security.
The transmission of an access token obtained by one end-user to
another end-user cannot be prevented, but can be detected by the RS.
In order to detect the transmission of the access token by one
client towards another client, the AS includes in every access token
a binding user identifier ("buid").
Every access token is bound to a RS user account (either a short-
term user account or a long-term user account). This is done by
including a binding user identifier ("buid") in every access token.
A binding user identifier is composed of a type and of a value. The
client can choose the type of the binding user identifier but not
its value which is only assigned by the AS.
All access tokens that are presented to a RS in the context of a
given RS user account must contain the same binding user identifier.
Pinkas Expires 20 February 2022 [Page 27]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
If an end-user obtains an access token from a collaborative end-
user, he cannot use it on his own user account since it will not
contain the same binding user identifier ("buid").
Let us use an example to illustrate the topic.
Some goods or activities with some preferred rates are only
disclosed by a town to its residents and if there are over 21.
In such a case, two attribute types and values will be requested
by the RS, e.g. :
Town of residence: Nashville - Tennessee - 840
Age categorization: over 21
Let us assume that Alice has the two following attributes:
Town of residence: Nashville - Tennessee - 840
Age categorization: over 16
while Bob has the two following attributes:
Town of residence: San Francisco - California - 840
Age categorization: over 21
If Alice asks for an access token that only contains:
Town of residence: Nashville - Tennessee - 840
and Bob asks for an access token that only contains:
Age categorization: over 21
if they agree to collaborate, they will not be able to combine their
attributes to perform an operation on the server managed by the town
of Nashville, since they will not contain the same binding user
identifier ("buid").
It is proposed to use to the wording "binded token" to designate
an access token that contains a binding user identifier.
Note: It should be noted that access tokens do not need to be
"protected" by a private key known by the client. Such a
protection would be illusory, since a collaborative client
could perform all the cryptographic computations that
another collaborative client would need to claim to be the
"owner" of the access token. This can be done even these
private keys are protected using an hardware security
module (HSM).
5. Privacy Considerations
ISO/IEC 29100 (Privacy framework) [ISO29100] lists eleven privacy
principles that are valid in a system with two entities which
correspond in this document to the relationships between one
end-user and one RS.
Note: ISO/IEC 29100 is available from ISO for free.
Pinkas Expires 20 February 2022 [Page 28]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
Among the privacy principles from ISO/IEC 29100 enumerated on page
14 in Table 3, the following privacy principles are particularly
important:
- Individual participation
- Purpose legitimacy and specification,
- Consent and choice,
- Collection limitation,
- Data minimization,
- Use, retention and disclosure limitation,
- Openness, transparency and notice.
Since this document considers two access control schemes: Attribute
Based Access Control (ABAC) and Capability Access Control (CBAC),
the privacy considerations for both of them are first addressed
(section 5.1) followed by the privacy considerations for each of
them (sections 5.2 and 5.3).
However, the current document considers a more complex system with
at least three entities: the end-user, the RS and the AS, where each
of them may exists more than once.
In this environment, some additional privacy properties also need to
be considered, in particular those that apply between RSs (section
5.4) and privacy properties that apply between the end-user and the
AS (section 5.5).
5.1. Privacy Considerations for both ABAC and CABC
Since the AS knows some attributes from the end-user, applying the
"individual participation" principle from ISO/IEC 29100, means
giving to the end-users the ability to access and review their
attributes, provided their identity is first authenticated with an
appropriate level of assurance and using a language which is both
clear and appropriately adapted to the circumstances.
This principle is reached using queries from an end-user to an AS
(see section 2.2) since such a query is performed once the client
has established an HTTPS connection with the AS and the end-user has
successfully authenticated with the AS.
For both ABAC and CABC a user account SHALL be created on the RS.
This account may be either short-term or long-term. For a long-term
user account, at the moment, the end-user needs to choose between
hiding to the AS the URL of the RS or allowing RSs to link their
user accounts.
Pinkas Expires 20 February 2022 [Page 29]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
5.1.1. Privacy Considerations for ABAC
In this access control scheme, end-user attributes need to be
presented to the RS. The end-user SHALL be able to :
- select the AS that will be contacted to deliver attributes,
- know which attribute types and attribute possibly values are
requested by the RS,
- know the reasons and/or the rational for providing these
attribute types and possibly values,
- consent or disagree with the provision of these attributes
from an AS that he has selected.
The previous functionalities are supported by a local dialogue
between the end-user and the client and by another dialogue between
the end-user and the RS.
This allows adhering to the purpose of legitimacy principle:
communicating the purpose(s) to the end-user before the time the
information is collected or used for the first time for a new
purpose.
It is possible for the client to hide to the AS the URL of the RS.
However, at this time, until a secure element is being used, the
price to pay for that feature is to allow RSs to link their user
accounts. So the end-user will have to make a choice between these
two features.
Note: The core principles of ABAC permit to the client to hide
to the AS the method that will be performed on a resource
as well as the URL of that resource.
5.1.2. Privacy Considerations for CBAC
In this access control scheme, capabilities need to be presented to
the RS. The end-user SHALL be able to :
- select the AS that will be contacted to deliver capabilities,
- consent or disagree with the provision of these capabilities
from an AS that he has selected.
The above functionalities are supported by using a local dialogue
between the end-user and the client.
The core principles of CBAC do not permit the end-user to hide to
the AS the URL of the RS, nor to hide to the AS the URL of the
resource, nor to hide to the AS the method that will be performed
on the resource.
Pinkas Expires 20 February 2022 [Page 30]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
5.2. Privacy Considerations between RSs
Two RSs should not be able to link their user accounts, by using the
content of the access tokens they receive from the same AS or from
different ASs. This property may be referred as: Unlinkeability
between RS user accounts. For short-term user accounts, it is
always achieved. However, for long-term user accounts, it may only
be achieved, for the moment, if the client/end-user accepts to
disclose to the AS the URL of the RS.
5.3. Privacy Considerations between the end-user and the AS
5.3.1. Transparency
When a client receives an access token from an AS, it should be able
to verify that the access token contains the requested privileges,
i.e. no more or not less, and, if not, it should be able to prevent
the transmission of the access token to the RS.
This property can be achieved as long as "Token introspection", as
currently described in OAuth, is not being used. It should be
noticed that Token introspection may allow an AS to deliver to the
client more privileges than the ones inserted into an access token.
These two properties are directly related to the "Transparency" of
the system since they allow the end-users to be confident in the
system they are using.
For these reasons, access tokens are not considered to be opaque
to the clients but may be considered to be opaque for the end-users.
5.3.2. Hiding to the AS the URL of the RS and its use
The AS should not be able to know when an issued access token will
be indeed consumed by a RS. This property can be achieved by using
the "hidden_url" field and as long as "Token introspection" is not
being used.
Pinkas Expires 20 February 2022 [Page 31]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
6. References
6.1. Normative References
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation
List(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280,
May 2008. <https://www.rfc-editor.org/info/rfc5280>.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March
2011, <https://www.rfc-editor.org/info/rfc6125>.
[RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani,
A., Galperin, S., and C. Adams, "X.509 Internet Public
Key Infrastructure Online Certificate Status Protocol -
OCSP", RFC 6960, DOI 10.17487/RFC6960, June 2013,
<https://www.rfc-editor.org/info/rfc6960>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
Transfer Protocol (HTTP/1.1): Semantics and Content",
RFC 7231, DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[RFC7235] R. Fielding, J. Reschke, Hypertext Transfer Protocol
(HTTP/1.1): Authentication, June 2014,
<https://www.rfc-editor.org/info/rfc7235>
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON)
Data Interchange Format", STD 90, RFC 8259, DOI
10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS)
Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446,
August 2018, <https://www.rfc-editor.org/info/rfc8446>.
Pinkas Expires 20 February 2022 [Page 32]
Internet-Draft Grant Negotiation and Authorization Protocol August 2021
6.2. Informative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, May 2015.
<https://www.rfc-editor.org/info/bcp195>
[OIDC_1.0] OpenID Connect Core 1.0 specification
<ttps://openid.net/specs/openid-connect-core-1_0.html>
[ISO29100] Information technology - Security techniques - Privacy
framework. 2011. ISO/IEC 29100 is available for free at:
https://standards.iso.org/ittf/
PubliclyAvailableStandards/c045123_ISO_IEC_29100_2011.zip
[GDPR] Regulation (EU) 2016/679 of the European Parliament and
of the Council of 27 April 2016 on the protection of
natural persons with regard to the processing of personal
data and on the free movement of such data, and repealing
Directive 95/46/EC (General Data Protection Regulation).
<https://eur-lex.europa.eu/eli/reg/2016/679/oj>
Authors' Address
Denis Pinkas
DP Security Consulting
Email: denis.ietf@free.fr
Pinkas Expires 20 February 2022 [Page 33]
