[GNAP] draft-hardt-xauth-protocol-14 update - reworked introduction

[Dick Hardt <[e-mail]>]

Hello

I just pushed an updated version of XAuth:

https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html

Highlights:

   - renamed Client -> Grant Client
   - Introduced Client Owner, Grant Server Owner as new entities
   - renamed Authorizations -> Access
   - An Access contains an array of RAR objects now
   - Reworked diagram an intro to focus on Grant, and separate protocol
   roles from human interactions.

New introduction included below for your convenience

/Dick

   -

1.  <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1>
Introduction
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#name-introduction>

*EDITOR NOTE*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-1>

*This document captures a number of concepts that may be adopted by the
proposed GNAP working group. Please refer to this document as:*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-2>

*XAuth*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-3>

*The use of GNAP in this document is not intended to be a declaration of it
being endorsed by the GNAP working group.*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-4>

This document describes the core Grant Negotiation and Authorization
Protocol (GNAP). The protocol supports the widely deployed use cases
supported by OAuth 2.0 [RFC6749
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#RFC6749>] & [
RFC6750
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#RFC6750>],
OpenID Connect [OIDC
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#OIDC>] - an
extension of OAuth 2.0, as well as other extensions. Related documents
include: GNAP - Advanced Features [GNAP_Advanced
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#GNAP_Advanced>
] and JOSE Authentication [JOSE_Authentication
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#JOSE_Authentication>
] that describes the JOSE mechanisms for client authentication.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-5>

The technology landscape has changed since OAuth 2.0 was initially drafted.
More interactions happen on mobile devices than PCs. Modern browsers now
directly support asymetric cryptographic functions. Standards have emerged
for signing and encrypting tokens with rich payloads (JOSE) that are widely
deployed.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-6>

GNAP simplifies the overall architectural model, takes advantage of today's
technology landscape, provides support for all the widely deployed use
cases, offers numerous extension points, and addresses many of the security
issues in OAuth 2.0 by passing parameters securely between parties rather
than via a browser redirection.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-7>

While GNAP is not backwards compatible with OAuth 2.0, it strives to
minimize the migration effort.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-8>

The suggested pronunciation of GNAP is "guh-nap".
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1-9>
1.1.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.1>The
Grant
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#name-the-grant>

The Grant is at the center of the protocol between a client and a server. A
Grant Client requests a Grant from a Grant Server. The Grant Client and
Grant Server negotiate the Grant. The Grant Server acquires authorization
to grant the Grant to the Grant Client. The Grant Server then returns the
Grant to the Grant Client.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.1-1>

The Grant Request may contain information about the User, the Grant Client,
the interaction modes supported by the Grant Client, the requested identity
claims, and the requested resource access. Extensions may define additional
information to be included in the Grant Request.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.1-2>
1.2.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2>Protocol
Roles
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#name-protocol-roles>

There are three roles in GNAP: the Grant Client (GC), the Grant Server
(GS), and the Resource Server (RS). Below is how the roles interact:
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2-1>

    +--------+                               +------------+
    | Grant  | - - - - - - -(1)- - - - - - ->|  Resource  |
    | Client |                               |   Server   |
    |  (GC)  |       +---------------+       |    (RS)    |
    |        |--(2)->|     Grant     |       |            |
    |        |<-(3)->|     Server    |- (6) -|            |
    |        |<-(4)--|      (GS)     |       |            |
    |        |       +---------------+       |            |
    |        |                               |            |
    |        |--------------(5)------------->|            |
    +--------+                               +------------+

<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2-2>

(1) The GC may query the RS to determine what the RS requires from a GS for
resource access. This step is not in scope for this document.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2-3>

(2) The GC makes a Grant request to the GS (Create Grant Section 3.2
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#CreateGrant>).
How the GC authenticates to the GS is not in scope for this document. One
mechanism is [JOSE_Authentication
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#JOSE_Authentication>
].
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2-4>

(3) The GC and GS may negotiate the Grant.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2-5>

(4) The GS returns a Grant to the GC (Grant Response Section 4.1
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#GrantResponse>
).
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2-6>

(5) The GC accesses resources at the RS (RS Access Section 6
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#RSAccess>).
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2-7>

(6) The RS evaluates access granted by the GS to determine access granted
to the GC. This step is not in scope for this document.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.2-8>
1.3.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3>Human
Interactions
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#name-human-interactions>

The Grant Client may be interacting with a human end-user (User), and the
Grant Client may need to get authorization to release the Grant from the
User, or from the owner of the resources at the Resource Server, the
Resource Owner (RO)
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-1>

Below is when the human interactions may occur in the protocol:
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-2>

    +--------+                               +------------+
    |  User  |                               |  Resource  |
    |        |                               | Owner (RO) |
    +--------+                               +------------+
        +     +                             +
        +      +                           +
       (A)     (B)                       (C)
        +        +                       +
        +         +                     +
    +--------+     +                   +     +------------+
    | Grant  | - - -+- - - -(1)- - - -+- - ->|  Resource  |
    | Client |       +               +       |   Server   |
    |  (GC)  |       +---------------+       |    (RS)    |
    |        |--(2)->|     Grant     |       |            |
    |        |<-(3)->|     Server    |- (6) -|            |
    |        |<-(4)--|      (GS)     |       |            |
    |        |       +---------------+       |            |
    |        |                               |            |
    |        |--------------(5)------------->|            |
    +--------+                               +------------+

Legend
+ + + indicates an interaction with a human
----- indicates an interaction between protocol roles

<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-3>

Steps (1) - (6) are the same as Section 1.2
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#ProtocolRoles>.
The addition of the human interactions (A) - (C) are *bolded* below.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-4>

*(A) The User is interacting with a GC, and the GC needs resource access
and/or identity claims (a Grant)*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-5>

(1) The GC may query the RS to determine what the RS requires from a GS for
resource access
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-6>

(2) The GC makes a Grant request to the GS
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-7>

(3) The GC and GS may negotiate the Grant
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-8>

*(B) The GS may interact with the User for grant authorization*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-9>

*(C) The GS may interact with the RO for grant authorization*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-10>

(4) The GS returns a Grant to the GC
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-11>

(5) The GC accesses resources at the RS
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-12>

(6) The RS evaluates access granted by the GS to determine access granted
to the GC
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-13>

Alternatively, the Resource Owner could be a legal entity that has a
software component that the Grant Server interacts with for Grant
authorization. This interaction is not in scope of this document.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.3-14>
1.4.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4>Trust
Model
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#name-trust-model>

In addition to the User and the Resource Owner, there are three other
entities that are part of the trust model:
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-1>

   - *Client Owner* (CO) - the legal entity that owns the Grant Client.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-2.1>
   - *Grant Server Owner* (GSO) - the legal entity that owns the Grant
   Server.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-2.2>
   - *Claims Issuer* (Issuer) - a legal entity that issues identity claims
   about the User. The Grant Server Owner may be an Issuer, and the Resource
   Owner may be an Issuer.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-2.3>

These three entities do not interact in the protocol, but are trusted by
the User and the Resource Owner:
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-3>

  +------------+           +--------------+----------+
  |    User    | >> (A) >> | Grant Server |          |
  |            |           | Owner (GSO)  |          |
  +------------+         > +--------------+          |
        V              /          ^       |  Claims  |
       (B)          (C)          (E)      |  Issuer  |
        V          /              ^       | (Issuer) |
  +------------+ >         +--------------+          |
  |  Client    |           |   Resource   |          |
  | Owner (CO) | >> (D) >> |  Owner (RO)  |          |
  +------------+           +--------------+----------+

<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-4>

(A) User trusts the GSO to acquire authorization before making a grant to
the CO
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-5>

(B) User trusts the CO to act in the User's best interest with the Grant
the GSO grants to the CO
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-6>

(C) CO trusts claims issued by the GSO
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-7>

(D) CO trusts claims issued by the RO
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-8>

(E) RO trusts the GSO to manage access to the RO resources
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.4-9>
1.5.
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5>
Terminology
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#name-terminology>

*Roles*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-1>

   -

   *Grant Client* (GC)
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.1.1>
   - may want access to resources at a Resource Server
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.1.2.1>
      - may be interacting with a User and want identity claims about the
      User
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.1.2.2>
      - requests the Grant Service to grant resource access and identity
      claims
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.1.2.3>
   -

   *Grant Server* (GS)
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.2.1>
   - accepts Grant requests from the GC for resource access and identity
      claims
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.2.2.1>
      - negotiates the interaction mode with the GC if interaction is
      required with the User
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.2.2.2>
      - acquires authorization from the User before granting identity
      claims to the GC
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.2.2.3>
      - acquires authorization from the RO before granting resource access
      to the GC
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.2.2.4>
      - grants resource access and identity claims to the GC
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.2.2.5>
   -

   *Resource Server* (RS)
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.3.1>
   - has resources that the GC may want to access
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.3.2.1>
      - expresses what the GC must obtain from the GS for access through
      documentation or an API. This is not in scope for this document
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.3.2.2>
      - verifies the GS granted access to the GC, when the GS makes
      resource access requests
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-2.3.2.3>

*Humans*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-3>

   -

   *User*
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-4.1.1>
   - the person interacting with the Grant Client.
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-4.1.2.1>
      - has delegated access to identity claims about themselves to the
      Grant Server.
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-4.1.2.2>
      - may authenticate at the GS.
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-4.1.2.3>
   -

   *Resource Owner* (RO)
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-4.2.1>
   - the legal entity that owns resources at the Resource Server (RS).
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-4.2.2.1>
      - has delegated resource access management to the GS.
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-4.2.2.2>
      - may be the User, or may be a different entity that the GS interacts
      with independently.
      <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-4.2.2.3>

*Reused Terms*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-5>

   - *access token* - an access token as defined in [RFC6749
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#RFC6749>]
Section
   1.4. An GC uses an access token for resource access at a RS.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-6.1>
   - *Claim* - a Claim as defined in [OIDC
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#OIDC>] Section
   5. Claims are issued by a Claims Issuer.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-6.2>
   - *Client ID* - a GS unique identifier for a Registered Client as
   defined in [RFC6749
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#RFC6749>]
Section
   2.2.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-6.3>
   - *ID Token* - an ID Token as defined in [OIDC
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#OIDC>] Section
   2. ID Tokens are issued by the GS. The GC uses an ID Token to authenticate
   the User.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-6.4>
   - *NumericDate* - a NumericDate as defined in [RFC7519
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#RFC7519>]
Section
   2.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-6.5>
   - *authN* - short for authentication.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-6.6>
   - *authZ* - short for authorization.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-6.7>

*New Terms*
<https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-7>

   - *GS URI* - the endpoint at the GS the GC calls to create a Grant, and
   is the unique identifier for the GS.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-8.1>
   - *Registered Client* - a GC that has registered with the GS and has a
   Client ID to identify itself, and can prove it possesses a key that is
   linked to the Client ID. The GS may have different policies for what
   different Registered Clients can request. A Registered Client MAY be
   interacting with a User.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-8.2>
   - *Dynamic Client* - a GC that has not been previously registered with
   the GS, and each instance will generate it's own asymetric key pair so it
   can prove it is the same instance of the GC on subsequent requests. The GS
   MAY return a Dynamic Client a Client Handle for the Dynamic Client to
   identify itself in subsequent requests. A single-page application with no
   active server component is an example of a Dynamic Client.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-8.3>
   - *Client Handle* - a unique identifier at the GS for a Dynamic Client
   for the Dynamic Client to refer to itself in subsequent requests.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-8.4>
   - *Interaction* - how the GC directs the User to interact with the GS.
   This document defines the interaction modes: "redirect", "indirect", and
   "user_code" in Section 5
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#InteractionModes>
   .
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-8.5>
   - *Grant* - the user identity claims and/or resource access the GS has
   granted to the Client. The GS MAY invalidate a Grant at any time.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-8.6>
   - *Grant URI* - the URI that represents the Grant. The Grant URI MUST
   start with the GS URI.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-8.7>
   - *Access* - the access granted by the RO to the GC and contains an
   access token. The GS may invalidate an Access at any time.
   <https://tools.ietf.org/id/draft-hardt-xauth-protocol-14.html#section-1.5-8.8>
   - *Access URI* - the URI that represents the Access the GC was granted
   by the RO. The Access URI MUST start with the GS URI. The Access URI is
   used to refresh an access token.