Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview :
Paragraph (version A):
server that grants delegated privileges to a particular instance
of client software in the form of access tokens or other
information (such as subject information).
Paragraph (version A):
application that consumes resources from one or several RSs,
possibly requiring access privileges from one or several ASs.  The
client is operated by the end-user or it runs autonomously on
behalf of a resource owner.  Example: a client can be a mobile
application, a web application, etc.  Note: this specification
differentiates between a specific instance (the client instance,
identified by its unique key) and the software running the
instance (the client software).  For some kinds of client
software, there could be many instances of that software, each
instance with a different key.
Paragraph (version A):
server that provides operations on protected resources, where
operations require a valid access token issued by an AS.
Paragraph (version A):
subject 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
organizational rules).
Paragraph (version A):
natural person that operates a client instance.  Note: that
natural person may or may not be the same entity as the RO.
Paragraph (version A):
characteristics related to a subject.
Paragraph (version A):
a data artifact representing a set of rights and/or attributes.
Note: an access token can be first issued to an client instance
(requiring authorization by the RO) and subsequently rotated.
Paragraph (version A):
right or attribute associated with a subject.  Note: the RO
defines and maintains the rights and attributes associated to the
protected resource, and might temporarily delegate some set of
those privileges to an end-user.  This process is refered to as
privilege delegation.
Paragraph (version A):
protected 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.  Note: to avoid complex sentences, the
specification document may simply refer to resource instead of
protected resource.
Paragraph (version A):
ability given to a subject to perform a given operation on a
resource under the control of an RS.
Paragraph (version A):
person, organization or device.  It decides whether and under
which conditions its attributes can be disclosed to other parties.
Paragraph (version A):
statement asserted by an AS about a subject.
Paragraph (version A):
Describes the rights and properties associated with the requested
access token.
Paragraph (version A):
Describes the information about the RO that the client instance is
requesting to be returned directly in the response from the AS.
Paragraph (version A):
Describes the client instance that is making this request,
including the key that the client instance will use to protect
this request and any continuation requests at the AS and any user-
facing information about the client instance used in interactions.
Paragraph (version A):
Identifies the end-user to the AS in a manner that the AS can
verify, either directly or by interacting with the end-user to
determine their status as the RO.
Paragraph (version A):
Describes the modes that the client instance has for allowing the
RO to interact with the AS and modes for the client instance to
receive updates when interaction is complete.
Paragraph (version A):
Describes the rights that the client instance is requesting for
one or more access tokens to be used at RS's.  This field is
REQUIRED.
Paragraph (version A):
A unique name chosen by the client instance to refer to the
resulting access token.  The value of this field is opaque to the
AS.  If this field is included in the request, the AS MUST include
the same label in the response-token.  This field is REQUIRED if
used as part of a request-token-multiple, and is OPTIONAL
otherwise.
Paragraph (version A):
A set of flags that indicate desired attributes or behavior to be
attached to the access token by the AS.  This field is OPTIONAL.
Paragraph (version A):
If this flag is included, the access token being requested is a
bearer token.  If this flag is omitted, the access token is bound
to the key used by the client instance in this request (or that
key's most recent rotation) and the access token MUST be presented
using the same key and proofing method.  Methods for presenting
bound and bearer access tokens are described in use-access-token.
See security-bearer-tokens for additional considerations on the
use of bearer tokens.
Paragraph (version A):
An array of subject identifier subject types requested for the RO,
as defined by I-D.ietf-secevent-subject-identifiers.
Paragraph (version A):
The public key of the client instance to be used in this request
as described in key-format or a reference to a key as described in
key-reference.  This field is REQUIRED.
Paragraph (version A):
An identifier string that the AS can use to identify the client
software comprising this client instance.  The contents and format
of this field are up to the AS.  This field is OPTIONAL.
Paragraph (version A):
An object containing additional information that the AS MAY
display to the RO during interaction, authorization, and
management.  This field is OPTIONAL.
Paragraph (version A):
An array of subject identifiers for the end-user, as defined by I-
D.ietf-secevent-subject-identifiers.
Paragraph (version A):
Indicates how the client instance can start an interaction.
Paragraph (version A):
Indicates how the client instance can receive an indication that
interaction has finished at the AS.
Paragraph (version A):
Provides additional information to inform the interaction process
at the AS.
Paragraph (version A):
Indicates that the client instance can direct the end-user to an
arbitrary URL for interaction.
Paragraph (version A):
Indicates that the client instance can launch an application on
the end-user's device for interaction.
Paragraph (version A):
Indicates that the client instance can communicate a human-
readable short code to the end-user for use with a stable URL.
Paragraph (version A):
Indicates that the client instance can receive a redirect from
the end-user's device after interaction with the RO has
concluded.
Paragraph (version A):
Indicates that the client instance can receive an HTTP POST
request from the AS after interaction with the RO has
concluded.
Paragraph (version A):
REQUIRED.  Indicates the URI that the AS will either send the RO
to after interaction or send an HTTP POST request.  This URI MAY
be unique per request and MUST be hosted by or accessible by the
client instance.  This URI MUST NOT contain any fragment
component.  This URI MUST be protected by HTTPS, be hosted on a
server local to the RO's browser ("localhost"), or use an
application-specific URI scheme.  If the client instance needs any
state information to tie to the front channel interaction
response, it MUST use a unique callback URI to link to that
ongoing state.  The allowable URIs and URI patterns MAY be
restricted by the AS based on the client instance's presented key
information.  The callback URI SHOULD be presented to the RO
during the interaction phase before redirect.
Paragraph (version A):
REQUIRED.  Unique value to be used in the calculation of the
"hash" query parameter sent to the callback URL, must be
sufficiently random to be unguessable by an attacker.  MUST be
generated by the client instance as a unique value for this
request.
Paragraph (version A):
Indicates the end-user's preferred locales that the AS can use
during interaction, particularly before the RO has authenticated.
Paragraph (version A):
Indicates that the client instance can continue the request by
making one or more continuation requests.
Paragraph (version A):
A single access token or set of access tokens that the client
instance can use to call the RS on behalf of the RO.
Paragraph (version A):
Indicates that interaction through some set of defined mechanisms
needs to take place.
Paragraph (version A):
Claims about the RO as known and declared by the AS, as described
in response-subject.
Paragraph (version A):
An identifier this client instance can use to identify itself when
making future requests.
Paragraph (version A):
An error code indicating that something has gone wrong.
Paragraph (version A):
REQUIRED.  The URI at which the client instance can make
continuation requests.  This URI MAY vary per request, or MAY be
stable at the AS.  The client instance MUST use this value exactly
as given when making a continue-request.
Paragraph (version A):
RECOMMENDED.  The amount of time in integer seconds the client
instance SHOULD wait after receiving this continuation handle and
calling the URI.
Paragraph (version A):
REQUIRED.  A unique access token for continuing the request,
called the "continuation access token".  The value of this
property MUST be in the format specified in response-token-single.
This access token MUST be bound to the client instance's key used
in the request and MUST NOT be a bearer token.  As a consequence,
the "flags" array of this access token MUST NOT contain the string
"bearer" and the "key" field MUST be omitted.  The client instance
MUST present the continuation access token in all requests to the
continuation URI as described in use-access-token.
Paragraph (version A):
REQUIRED.  The value of the access token as a string.  The value
is opaque to the client instance.  The value SHOULD be limited to
ASCII characters to facilitate transmission over HTTP headers
within other protocols without requiring additional encoding.
Paragraph (version A):
REQUIRED for multiple access tokens, OPTIONAL for single access
token.  The value of the "label" the client instance provided in
the associated request-token, if present.  If the token has been
split by the AS, the value of the "label" field is chosen by the
AS and the "split" flag is used.
Paragraph (version A):
OPTIONAL.  The management URI for this access token.  If provided,
the client instance MAY manage its access token as described in
token-management.  This management URI is a function of the AS and
is separate from the RS the client instance is requesting access
to.  This URI MUST NOT include the access token value and SHOULD
be different for each access token issued in a request.
Paragraph (version A):
RECOMMENDED.  A description of the rights associated with this
access token, as defined in resource-access-rights.  If included,
this MUST reflect the rights associated with the issued access
token.  These rights MAY vary from what was requested by the
client instance.
Paragraph (version A):
OPTIONAL.  The number of seconds in which the access will expire.
The client instance MUST NOT use the access token past this time.
An RS MUST NOT accept an access token past this time.  Note that
the access token MAY be revoked by the AS or RS at any point prior
to its expiration.
Paragraph (version A):
OPTIONAL.  The key that the token is bound to, if different from
the client instance's presented key.  The key MUST be an object or
string in a format described in key-format.  The client instance
MUST be able to dereference or process the key information in
order to be able to sign the request.
Paragraph (version A):
OPTIONAL.  A set of flags that represent attributes or behaviors
of the access token issued by the AS.
Paragraph (version A):
This flag indicates whether the token is a bearer token, not bound
to a key and proofing mechanism.  If the "bearer" flag is present,
the access token is a bearer token, and the "key" field in this
response MUST be omitted.  If the "bearer" flag is omitted and the
"key" field in this response is omitted, the token is bound the
request-client in its request for access.  If the "bearer" flag is
omitted, and the "key" field is present, the token is bound to the
key and proofing mechanism indicated in the "key" field.  See
security-bearer-tokens for additional considerations on the use of
bearer tokens.
Paragraph (version A):
OPTIONAL.  Flag indicating a hint of AS behavior on token
rotation.  If this flag is present, then the client instance can
expect a previously-issued access token to continue to work after
it has been rotate-access-token or the underlying grant request
has been continue-modify, resulting in the issuance of new access
tokens.  If this flag is omitted, the client instance can
anticipate a given access token will stop working after token
rotation or grant request modification.  Note that a token flagged
as "durable" can still expire or be revoked through any normal
means.
Paragraph (version A):
OPTIONAL.  Flag indicating that this token was generated by
issuing multiple access tokens in response to one of the client
instance's request-token objects.  This behavior MUST NOT be used
unless the client instance has specifically requested it by use of
the "split" flag.
Paragraph (version A):
Redirect to an arbitrary URL.
Paragraph (version A):
Launch of an application URL.
Paragraph (version A):
A nonce used by the client instance to verify the callback after
interaction is completed.
Paragraph (version A):
Display a short user code.
Paragraph (version A):
REQUIRED.  A unique short code that the user can type into an
authorization server.  This string MUST be case-insensitive, MUST
consist of only easily typeable characters (such as letters or
numbers).  The time in which this code will be accepted SHOULD be
short lived, such as several minutes.  It is RECOMMENDED that this
code be no more than eight characters in length.
Paragraph (version A):
RECOMMENDED.  The interaction URL that the client instance will
direct the RO to.  This URL MUST be stable such that client
instances can be statically configured with it.
Paragraph (version A):
An array of subject identifiers for the RO, as defined by I-
D.ietf-secevent-subject-identifiers.
Paragraph (version A):
Timestamp as an ISO8610 date string, indicating when the
identified account was last updated.  The client instance MAY use
this value to determine if it needs to request updated profile
information through an identity API.  The definition of such an
identity API is out of scope for this specification.
Paragraph (version A):
A string value used to represent the information in the "client"
object that the client instance can use in a future request, as
described in request-instance.
Paragraph (version A):
The error code.
Paragraph (version A):
The RO denied the request.
Paragraph (version A):
The client instance did not respect the timeout in the wait
response.
Paragraph (version A):
The request referenced an unknown ongoing access request.
Paragraph (version A):
The form of proof that the client instance will use when
presenting the key.  The valid values of this field and the
processing requirements for each are detailed in binding-keys.
The "proof" field is REQUIRED.
Paragraph (version A):
The public key and its properties represented as a JSON Web Key
RFC7517.  A JWK MUST contain the "alg" (Algorithm) and "kid" (Key
ID) parameters.  The "alg" parameter MUST NOT be "none".  The
"x5c" (X.509 Certificate Chain) parameter MAY be used to provide
the X.509 representation of the provided public key.
Paragraph (version A):
PEM serialized value of the certificate used to sign the request,
with optional internal whitespace per RFC7468.  The PEM header and
footer are optionally removed.
Paragraph (version A):
The certificate thumbprint calculated as per RFC8705 in base64 URL
encoding.  Note that this format does not include the full public
key.
Paragraph (version A):
The Content-Digest or Digest header as defined in I-D.ietf-
httpbis-digest-headers.  When the request message has a body, the
signer MUST calculate this header value and the verifier MUST
validate this field value.  Use of Content-Digest is RECOMMENDED.
Use of content-encoding agnostic digest methods (such as "id-sha-
256") is RECOMMENDED.
Paragraph (version A):
The Authorization header used to present the access token as
discussed in use-access-token.
Paragraph (version A):
The key identifier.  RECOMMENDED.  If the key is presented in JWK
format, this MUST be the value of the "kid" field of the key.
Paragraph (version A):
The algorithm used to sign the request.  REQUIRED.  MUST be
appropriate to the key presented.  If the key is presented as a
JWK, this MUST be equal to the "alg" parameter of the key.  MUST
NOT be "none".
Paragraph (version A):
When a request is bound to an access token, the access token hash
value.  The value MUST be the result of Base64url encoding (with
no padding) the SHA-256 digest of the ASCII encoding of the
associated access token's value.  REQUIRED if the request protects
an access token.
Paragraph (version A):
The type header, value "gnap-binding+jws".
Paragraph (version A):
The HTTP Method used to make this request, as an uppercase ASCII
string.
Paragraph (version A):
The HTTP URI used for this request, including all path and query
components and no fragment component.
Paragraph (version A):
When a request is bound to an access token, the access token hash
value.  The value MUST be the result of Base64url encoding (with
no padding) the SHA-256 digest of the ASCII encoding of the
associated access token's value.
Paragraph (version A):
The type of resource request as a string.  This field MAY define
which other fields are allowed in the request object.  This field
is REQUIRED.
Paragraph (version A):
The types of actions the client instance will take at the RS as an
array of strings.  For example, a client instance asking for a
combination of "read" and "write" access.
Paragraph (version A):
The location of the RS as an array of strings.  These strings are
typically URIs identifying the location of the RS.
Paragraph (version A):
The kinds of data available to the client instance at the RS's API
as an array of strings.  For example, a client instance asking for
access to raw "image" data and "metadata" at a photograph API.
Paragraph (version A):
A string identifier indicating a specific resource at the RS.  For
example, a patient identifier for a medical API or a bank account
number for a financial API.
Paragraph (version A):
The types or levels of privilege being requested at the resource.
For example, a client instance asking for administrative level
access, or access when the resource owner is no longer online.
Paragraph (version A):
REQUIRED.  The location of the AS's grant request endpoint.  The
location MUST be a URL RFC3986 with a scheme component that MUST
be https, a host component, and optionally, port, path and query
components and no fragment components.  This URL MUST match the
URL the client instance used to make the discovery request.
Paragraph (version A):
OPTIONAL.  A list of the AS's interaction start methods.  The
values of this list correspond to the possible values for the
request-interact-start of the request.
Paragraph (version A):
OPTIONAL.  A list of the AS's interaction finish methods.  The
values of this list correspond to the possible values for the
method element of the request-interact-finish of the request.
Paragraph (version A):
OPTIONAL.  A list of the AS's supported key proofing mechanisms.
The values of this list correspond to possible values of the
"proof" field of the key-format of the request.
Paragraph (version A):
OPTIONAL.  A list of the AS's supported subject identifier types.
The values of this list correspond to possible values of the
request-subject of the request.
Paragraph (version A):
OPTIONAL.  A list of the AS's supported assertion formats.  The
values of this list correspond to possible values of the request-
subject of the request.
Paragraph (version B):
The editors would also like to thank the GNAP working group design
team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones,
and Justin Richer, who incorporated elements from the XAuth and XYZ
proposals to create the first version of this document.
Paragraph (version B):
In addition, the editors would like to thank Aaron Parecki and Mike
Jones for insights into how to integrate identity and authentication
systems into the core protocol, and Justin Richer and Dick Hardt for
the use cases, diagrams, and insights provided in the XYZ and XAuth
proposals that have been incorporated here.  The editors would like
to especially thank Mike Varley and the team at SecureKey for
feedback and development of early versions of the XYZ protocol that
fed into this standards work.