Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-211 - -gnap - core - protocol - editors- 
 Great comments . I 'll add a secondary example to section 3 I 'll change that " and " to " or " -- even though it 's not normative it 's a good idea to give the right impression 
 Thanks for the feedback , I 've addressed the issues raised . 
 See also for additional diagrams 
 Add an abstract diagram showing the connection between the different roles / parties in the protocol , without necessarily showing the temporal steps of the interactions between them . 
 That could be useful indeed . A few comments : not sure if that 's really necessary , but since it 's a fairly different scenario , maybe that could even be an additional response example in section 3 ( and there we could use email , while elsewhere we 'd use opaque ) . I checked our definition for the AS and we might just need to change very slightly ( and -or ? ): " server that grants delegated privileges to a particular instance of client software in the form of an access token or other information ( such as subject information ) . " Because " and " means we need an access token .
Paragraph (version B):
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):
In some circumstances, the information needed at a given stage is
communicated out of band or is preconfigured between the components
or entities performing the roles.  For example, one entity can fulfil
multiple roles, and so explicit communication between the roles is
not necessary within the protocol flow.
Paragraph (version B):
In some circumstances, the information needed at a given stage is
communicated out of band or is preconfigured between the components
or entities performing the roles.  For example, one entity can fulfil
multiple roles, and so explicit communication between the roles is
not necessary within the protocol flow.  Additionally some components
may not be involved in all use cases.  For example, a client instance
could be calling the AS just to get direct user information and have
no need to get an access token to call an RS.
Paragraph (version A):
The following sections and examples contain specific guidance on how
to use GNAP in different situations and deployments.
Paragraph (version B):
The following sections and examples contain specific guidance on how
to use GNAP in different situations and deployments.  For example, it
is possible for the client instance to never request an access token
and never call an RS, just as it is possible for there not to be a
user involved in the delegation process.
Paragraph (version B):
The AS determines that the request is been authorized, the AS
grants access to the information in the form of response-token to
the client instance.  Note that response-subject is not generally
applicable in this use case, as there is no user involved.
Paragraph (version B):
Time passes and the client instance uses the access token to call
the RS again.
Paragraph (version B):
The RS validates the access token and determines that the access
token is expired The RS responds to the client instance with an
error.
Paragraph (version B):
The client instance calls the token management URI returned in (2)
to rotate-access-token.  The client instance use-access-token in
this call as well as the appropriate key, see the token rotation
section for details.
Paragraph (version B):
The AS determines that interaction is needed and response with
appropriate information for response-interact.
Paragraph (version B):
The user authenticates at the AS, taking on the role of the RO.
Paragraph (version B):
As the RO, the user authorizes the pending request from the client
instance.
Paragraph (version B):
When the AS is done interacting with the user, the AS returns the
user to the client instance and signals continuation.
Paragraph (version B):
The client instance loads the continuation information from (2)
and calls the AS to continue-request.
Paragraph (version B):
If the request has been authorized, the AS grants access to the
requested response-subject to the client instance.  At this stage,
the user is generally considered "logged in" to the client
instance based on the identifiers and assertions provided by the
AS.  Note that the AS can restrict the subject information
returned and it might not match what the client instance
requested, see the section on subject information for details.
Paragraph (version A):
In this example, the AS is returning a bearer response-token-single
with a management URL and a response-subject in the form of an email
address.
Paragraph (version B):
In this example, the AS is returning a bearer response-token-single
with a management URL and a response-subject in the form of an opaque
identifier.
Paragraph (version B):
In this example, the AS is returning only a pair of response-subject
as both an email address and an opaque identifier.
Paragraph (version B):
The AS validates the access token value and the client instance's
request and returns the introspection response for the token.