Draft: draft-ietf-gnap-resource-servers

Commentary: Yaron : IMO we should specify a minimal , generic format in an appendix , as a non - normative starting point for developers . It would be better than having each implementation make its own mistakes . Fabien : A comment on access token formats : I do n't think we should define our own format , but we can reference other documents such as and the references to macaroons , biscuits . Yaron : I do n't think a reference to an OAuth doc would do , because GNAP makes changes to the AT semantics , e.g. by replacing scopes . See also follow on thread : 
 yes , we can suggest a mapping more relevant , what I had in mind is a basic mapping like clientid < -client scope < -access but it will be better to be more specific , a bit in the spirit of appendix C5 from core 
 For the record , the OAuth draft is : A mapping is possible , I 'm not a great fan though . We will want to have our own attribute , to prevent cross - protocol attacks . And OMG , the OAuth draft is cramming even more claims into the one - and - only Claims IANA registry / cesspool ! 
 You convinced me ;-) A mapping is mostly useful as a guidance document for devs that would like to migrate from OAuth2 to GNAP , but that could be only a wiki . 
 We would like to avoid defining a particular token format , but agree that some advice for developers is useful . Instead , we can define a token " model " , to instruct developers on which fields are useful to keep track of . would be a good place to add this . 
 Frankly there 's very little difference , because most implementers will translate the " model " into a straightforward JWT " format " . But I can live with that . 
 A few questions : if we write Appendix C from the core spec , does this issue still hold here ? should we transfer some of the discussions above ( ex : typ -avoid confusion with id_token for instance ) to ?
Mailing list commentary: Hi Yaron , A comment on access token formats : I do n't think we should define our own format , but we can reference other documents such as and the references to macaroons , biscuits . The rest I believe makes good issues , most of which should be quick to fix .
Paragraph (version A):
The means of the authorization server issuing the access token to the
client instance and the means of the client instance presenting the
access token to the resource server are the subject of the GNAP core
protocol specification I-D.ietf-gnap-core-protocol.
Paragraph (version B):
The means of the authorization server issuing the access token to the
client instance and the means of the client instance presenting the
access token to the resource server are the subject of the GNAP core
protocol specification GNAP.
Paragraph (version A):
Terminology specific to GNAP is defined in the terminology section of
the core specification I-D.ietf-gnap-core-protocol, and provides
definitions for the protocol roles: Authorization Server (AS),
Client, Resource Server (RS), Resource Owner (RO), End-user; as well
as the protocol elements: Attribute, Access Token, Grant, Privilege,
Protected Resource, Right, Subject, Subject Information.  The same
definitions are used in this document.
Paragraph (version B):
Terminology specific to GNAP is defined in the terminology section of
the core specification GNAP, and provides definitions for the
protocol roles: Authorization Server (AS), Client, Resource Server
(RS), Resource Owner (RO), End-user; as well as the protocol
elements: Attribute, Access Token, Grant, Privilege, Protected
Resource, Right, Subject, Subject Information.  The same definitions
are used in this document.
Paragraph (version B):
Access tokens are a mechanism for an AS to provide a client instance
limited access to an RS.  These access tokens are artifacts
representing a particular set of access rights granted to the client
instance to act on behalf of the RO.  While the format of access
tokens varies in different systems (see discussion in token-format),
the concept of an access token is consistent across all GNAP systems.
Paragraph (version B):
Access tokens represent a common set of aspects across different GNAP
deployments.  This is not intended to be a universal or comprehensive
list, but instead to provide guidance to implementors when developing
data structures and associated systems across a GNAP deployment.
These data structures are communicated between the AS and RS either
by using a structured token or an API-like mechanism like token
introspection.  This general-purpose data model does not assume
either approach, and in fact both can be used together to convey
different pieces of information.  Where possible, mappings to
concrete data fields in common standards understood by the RS are
provided for each item in the model.
Paragraph (version B):
known to the AS and RS, and the other items in this token model are
contained within the token's value in some fashion.  When the token
is unstructured, the values are usually retrieved by the RS using a
service like token introspection described in introspection.
Paragraph (version B):
The access token value is conveyed the "value" field of an
"access_token" response from GNAP.
Paragraph (version B):
The format and content of the access token value is opaque to the
client software.  While the client software needs to be able to carry
and present the access token value, the client software is never
expected nor intended to be able to understand the token value
itself.
Paragraph (version B):
The access token is issued by the AS in a standard GNAP transaction.
The AS will often need to identify itself in order to recognize
tokens that it has issued, particularly in cases where tokens from
multiple different AS's could be presented.
Paragraph (version B):
This information is not usually conveyed directly to the client
instance, since the client instance should know this information
based on where it receives the token from.
Paragraph (version B):
In a JWT formatted token or a token introspection response, this
corresponds to the "iss" claim.
Paragraph (version B):
The access token is intended for use at one or more RS's.  The AS can
identify those RS's to allow each RS to ensure that the token is not
receiving a token intended for someone else.  The AS and RS have to
agree on the nature of any audience identifiers represented by the
token, but the URIs of the RS are a common pattern.
Paragraph (version B):
In a JWT formatted token or token introspection response, this
corresponds to the "aud" claim.
Paragraph (version B):
In cases where more complex access is required, the "location" field
of objects in the "access" array can also convey audience
information.  In such cases, the client instance might need to know
the audience information in order to differentiate between possible
RS's to present the token to.
Paragraph (version B):
Access tokens in GNAP are bound to the client instance's registered
or presented key, except in cases where the access token is a bearer
token.  For all tokens bound to a key, the AS and RS need to be able
to identify which key the token is bound to, otherwise an attacker
could substitute their own key during presentation of the token.  In
the case of an asymmetric algorithm, the model for the AS and RS need
only contain the public key, while the client instance will also need
to know the private key in order to present the token appropriately.
In the case of a symmetric algorithm, all parties will need to either
know or be able to derive the shared key.
Paragraph (version B):
The source of this key information can vary depending on circumstance
and deployment.  For example, an AS could decide that all tokens
issued to a client instance are always bound to that client
instance's current key.  When the key needs to be dereferenced, the
AS looks up the client instance to which the token was issued and
finds the key information there.  The AS could alternatively bind
each token to a specific key that is managed separately from client
instance information.  In such a case, the AS determines the key
information directly.  This approach allows the client instance to
use a different key for each request, or allows the AS to issue a key
for the client instance to use with the particular token.
Paragraph (version B):
In all cases, the key binding also includes a proofing mechanism,
along with any parameters needed for that mechanism such as a signing
or digest algorithm.  If such information is not stored, an attacker
could present a token with a seemingly-valid key using an insecure
and incorrect proofing mechanism.
Paragraph (version B):
This value is conveyed to the client instance in the "key" field of
the "access_token" response in GNAP.  Since the common case is that
the token is bound to the client instance's registered key, this
field can be omitted in this case since the client will be aware of
its own key.
Paragraph (version B):
In a JWT formatted token, this corresponds to the "cnf"
(confirmation) claim.  In a token introspection response, this
corresponds to the "key" claim.
Paragraph (version B):
In the case of a bearer token, all parties need to know that a token
has no key bound to it, and will therefore reject any attempts to use
the bearer token with a key in an undefined way.
Paragraph (version B):
GNAP access tokens can have multiple data flags associated with them
that indicate special processing or considerations for the token.
For example, whether the token is a bearer token, or should be
expected to be durable across grant updates.
Paragraph (version B):
The client can request a set of flags in the "access_token" request
in GNAP.
Paragraph (version B):
These flags are conveyed from the AS to the client in the "flags"
field of the "access_token" response in GNAP.
Paragraph (version B):
For token introspection, flags are returned in the "flags" field of
the response.
Paragraph (version B):
Access tokens are tied to a limited set of access rights.  These
rights specify in some detail what the token can be used for, how,
and where.  The internal structure of access rights are detailed in
GNAP.
Paragraph (version B):
The access rights associated with an access token are calculated from
the rights available to the client instance making the request, the
rights available to be approved by the RO, the rights actually
approved by the RO, and the rights corresponding to the RS in
question.  The rights for a specific access token are a subset of the
overall rights in a grant request.
Paragraph (version B):
These rights are requested by the client instance in the "access"
field of the "access_token" request in GNAP.
Paragraph (version B):
The rights associated with an issued access token are conveyed to the
client instance in the "access" field of the "access_token" response
in GNAP.
Paragraph (version B):
In token introspection responses, this corresponds to the "access"
claim.
Paragraph (version B):
The access token can be limited to a certain time window outside of
which it is no longer valid for use at an RS.  This window can be
explicitly bounded by an expiration time and a not-before time, or it
could be calculated based on the issuance time of the token.  For
example, an RS could decide that it will accept tokens for most calls
within an hour of a token's issuance, but only within five minutes of
the token's issuance for certain high-value calls.
Paragraph (version B):
Since access tokens could be revoked at any time for any reason
outside of a client instance's control, the client instance often
does not know or concern itself with the validity time window of an
access token.  However, this information can be made available to it
using the "expires_in" field of an access token response in GNAP.
Paragraph (version B):
The issuance time of the token is conveyed in the "iat" claim of a
JWT formatted token or a token introspection response.
Paragraph (version B):
The expiration time of a token, after which it is to be rejected, is
conveyed in the "exp" claim of a JWT formatted token or a token
introspection response.
Paragraph (version B):
The starting time of a token's validity window, before which it is to
be rejected, is conveyed in the "nbf" claim of a JWT formatted token
or a token introspection response.
Paragraph (version B):
Individual access tokens often need a unique internal identifier to
allow the AS to differentiate between multiple separate tokens.  This
value of the token can often be used as the identifier, but in some
cases a separate identifier is used.
Paragraph (version B):
This separate identifier can be conveyed in the "jti" claim of a JWT
formatted token or a token introspection response.
Paragraph (version B):
This identifier is not usually exposed to the client instance using
the token, since the client instance only needs to use the token by
value.
Paragraph (version B):
Access tokens are approved on behalf of a resource owner (RO).  The
identity of this RO can be used by the RS to determine exactly which
resource to access, or which kinds of access to allow.  For example,
an access token used to access identity information can hold a user
identifier to allow the RS to determine which profile information to
return.  The nature of this information is subject to agreement by
the AS and RS.
Paragraph (version B):
This corresponds to the "sub" claim of a JWT formatted token or a
token introspection response.
Paragraph (version B):
The RO information is not generally returned to the client instance,
and in many cases returning this information to the client instance
would be a privacy violation on the part of the AS.  Since the access
token represents a specific delegated access, the client instance
needs only to use the token at its target RS.  Following the profile
example, the client instance does not need to know the account
identifier to get specific attributes about the account represented
by the token.
Paragraph (version B):
Access tokens are issued to a specific client instance by the AS.
The identity of this instance can be used by the RS to allow specific
kinds of access, or other attributes about the access token.  For
example, an AS that binds all access tokens issued to a particular
client instance to that client instance's most recent key rotation
would need to be able to look up the client instance in order to find
the key binding detail.
Paragraph (version B):
This corresponds to the "client_id" claim of a JWT formatted token or
the "instance_id" field of a token introspection response.
Paragraph (version B):
The client is not normally informed of this information separately,
since a client instance can usually correctly assume that it is the
client instance to which a token that it receives was issued.
Paragraph (version B):
When multiple access tokens are requested or a client instance uses
token labels, the parties will need to keep track of which labels
were applied to each individual token.  Since labels can be re-used
across different grant requests, the token label alone is not
sufficient to uniquely identify a given access token in a system.
However, within the context of a grant request, these labels are
required to be unique.
Paragraph (version B):
A client instance can request a specific label using the "label"
field of an "access_token" request in GNAP.
Paragraph (version B):
The AS can inform the client instance of a token's label using the
"label" field of an "access_token" response in GNAP.
Paragraph (version B):
This corresponds to the "label" field of a token introspection
response.
Paragraph (version B):
The AS can use this information to tie common information to a
specific token.  For instance, instead of specifying a client
instance for every issued access token for a grant, the AS can store
the client information in the grant itself and look it up by
reference from the access token.
Paragraph (version B):
The AS can also use this information when a grant request is updated.
For example, if the client instance asks for a new access token from
an existing grant, the AS can use this link to revoke older non-
durable access tokens that had been previously issued under the
grant.
Paragraph (version B):
A client instance will have its own model of an ongoing grant
request, especially if that grant request can be continued using the
API defined in GNAP where several pieces of statefulness need to be
kept in hand.  The client instance might need to keep an association
with the grant request that issued the token in case the access token
expires or does not have sufficient access rights, so that the client
instance can get a new access token without having to restart the
grant request process from scratch.
Paragraph (version B):
Since the grant itself does not need to be identified in any of the
protocol messages, GNAP does not define a specific grant identifier
to be conveyed between any parties in the protocol.  Only the AS
needs to keep an explicit connection between an issued access token
and the parent grant that issued it.
Paragraph (version B):
When an access token is used for the grant continuation API defined
in GNAP, the AS needs to be able to separate this access token from
others usable at RS's.  The AS can do this through the use of a flag
on the access token data structure, by using a special internal
access right, or any other means at its disposal.
Paragraph (version B):
A client instance will need to store continuation access tokens
separately from access tokens used at the RS in order to keep them
from being confused with each other and used at the wrong endpoints.
Paragraph (version B):
The client instance is given continuation access tokens only as part
of the "continue" field of the grant response in GNAP.
Paragraph (version B):
An RS should never see a continuation access token, so any attempts
to process one should fail.
Paragraph (version A):
The RS MAY present its keys by reference or by value in a similar
fashion to a client instance calling the AS in the core protocol of
GNAP, described in I-D.ietf-gnap-core-protocol.  In the protocols
defined here, this takes the form of the resource server identifying
itself using a "key" field or by passing an instance identifier
directly.
Paragraph (version B):
The RS MAY present its keys by reference or by value in a similar
fashion to a client instance calling the AS in the core protocol of
GNAP, described in GNAP.  In the protocols defined here, this takes
the form of the resource server identifying itself using a "key"
field or by passing an instance identifier directly.
Paragraph (version B):
When the RS receives an access token, it can call the introspection
endpoint at the AS to get token information.
Paragraph (version A):
The RS signs the request with its own key and sends the access token
as the body of the request.
Paragraph (version A):
If the RS needs to, it can post a set of resources as described in
the Resource Access Rights section of I-D.ietf-gnap-core-protocol to
the AS's resource registration endpoint along with information about
what the RS will need to validate the request.
Paragraph (version B):
If the RS needs to, it can post a set of resources as described in
the Resource Access Rights section of GNAP to the AS's resource
registration endpoint along with information about what the RS will
need to validate the request.
Paragraph (version A):
If the RS needs to derive a token from one presented to it, it can
request one from the AS by making a token request as described in I-
D.ietf-gnap-core-protocol and presenting the existing access token's
value in the "existing_access_token" field.
Paragraph (version A):
The AS responds with a token for the downstream RS2 as described in
I-D.ietf-gnap-core-protocol.  The downstream RS2 could repeat this
process as necessary for calling further RS's.
Paragraph (version B):
If the RS needs to derive a token from one presented to it, it can
request one from the AS by making a token request as described in
GNAP and presenting the existing access token's value in the
"existing_access_token" field.
Paragraph (version B):
The AS responds with a token for the downstream RS2 as described in
GNAP.  The downstream RS2 could repeat this process as necessary for
calling further RS's.
Paragraph (version A):
This specification establishes the GNAP Token Format Registry to
define token formats.
Paragraph (version A):
The table below contains the initial contents of the GNAP Token
Format Registry.
Paragraph (version B):
IANA is requested to create the following registries.
Paragraph (version B):
This document defines a GNAP token format, for which IANA is asked to
create and maintain a new registry titled "GNAP Token Formats".
Initial values for this registry are given in IANA-token-format-
contents.  Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy RFC8126.
Paragraph (version B):
The Designated Expert (DE) is expected to ensure that all
registrations follow the template presented in IANA-token-format-
template.  The DE is expected to ensure that the format's definition
is sufficiently unique from other formats provided by existing
parameters.  The DE is expected to ensure that the format's
definition specifies the format of the access token in sufficient
detail to allow for the AS and RS to be able to communicate the token
information.
Paragraph (version B):
This document defines GNAP token introspection, for which IANA is
asked to create and maintain a new registry titled "GNAP Token
Introspection".  Initial values for this registry are given in IANA-
token-introspection-contents.  Future assignments and modifications
to existing assignment are to be made through the Expert Review
registration policy RFC8126.
Paragraph (version B):
The Designated Expert (DE) is expected to ensure that all
registrations follow the template presented in IANA-token-
introspection-template.  The DE is expected to ensure that the
claim's definition is sufficiently orthogonal to other claims defined
in the registry so as avoid overlapping functionality.  The DE is
expected to ensure that the claim's definition specifies the syntax
and semantics of the claim in sufficient detail to allow for the AS
and RS to be able to communicate the token values.
Paragraph (version B):
The table below contains the initial contents of the GNAP Token
Introspection Registry.
Paragraph (version B):
This document defines a means to register a resource set for a GNAP
AS, for which IANA is asked to create and maintain a new registry
titled "GNAP Resource Set Registration Request Parameters".  Initial
values for this registry are given in IANA-resource-registration-
request-contents.  Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy RFC8126.
Paragraph (version B):
The Designated Expert (DE) is expected to ensure that all
registrations follow the template presented in IANA-resource-
registration-request-template.  The DE is expected to ensure that the
parameter's definition is sufficiently orthogonal to other claims
defined in the registry so as avoid overlapping functionality.  The
DE is expected to ensure that the parameter's definition specifies
the syntax and semantics of the claim in sufficient detail to allow
for the AS and RS to be able to communicate the resource set.
Paragraph (version B):
The table below contains the initial contents of the GNAP Resource
Set Registration Request Parameters Registry.
Paragraph (version B):
This document defines a means to register a resource set for a GNAP
AS, for which IANA is asked to create and maintain a new registry
titled "GNAP Resource Set Registration Response Parameters".  Initial
values for this registry are given in IANA-resource-registration-
response-contents.  Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy RFC8126.
Paragraph (version B):
The Designated Expert (DE) is expected to ensure that all
registrations follow the template presented in IANA-resource-
registration-response-template.  The DE is expected to ensure that
the parameter's definition is sufficiently orthogonal to other claims
defined in the registry so as avoid overlapping functionality.  The
DE is expected to ensure that the parameter's definition specifies
the syntax and semantics of the claim in sufficient detail to allow
for the AS and RS to be able to communicate the resource set.
Paragraph (version B):
The table below contains the initial contents of the GNAP Resource
Set Registration Response Parameters Registry.
Paragraph (version B):
This document defines a means to for a GNAP AS to be discovered by a
GNAP RS, for which IANA is asked to create and maintain a new
registry titled "GNAP RS-Facing Discovery".  Initial values for this
registry are given in IANA-rs-discovery-contents.  Future assignments
and modifications to existing assignment are to be made through the
Expert Review registration policy RFC8126.
Paragraph (version B):
The Designated Expert (DE) is expected to ensure that all
registrations follow the template presented in IANA-rs-discovery-
template.  The DE is expected to ensure that the claim's definition
is sufficiently orthogonal to other claims defined in the registry so
as avoid overlapping functionality.  The DE is expected to ensure
that the claim's definition specifies the syntax and semantics of the
claim in sufficient detail to allow for RS to be able to communicate
with the AS.
Paragraph (version B):
The table below contains the initial contents of the GNAP RS-Facing
Discovery Registry.