Draft: draft-ietf-gnap-core-protocol

Commentary: update token rotation response and requirements add considerations for the difficulties of rotating and revoking stateless tokens add considerations on rotation in unreliable networks 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 Rotation the Access Token :  's note : The net result is that the client 's always going to use the management URL that comes back . But should we let the server omit it from the response if it does n't change ? That seems like an odd optimization that does n't help the client . 
 Close by making inclusion of URI REQUIRED . 
 Rotating the Access Token :  's note : We could also use different verbs to signal whether or not the old token should be kept around or not , instead of using a token flag to do this . 
 Keep " MUST if possible " here . If you want two access tokens , use the grant API not the token rotation API . The rotation mechanism should be for getting a new value for an existing token and replacing it , not for minting entirely new separate tokens ( which is what the grant continuation / update API is for ) . We need to keep " if possible " for the case of using stateless tokens ( fully self - contained JWTs ) , and add a discussion on when it might not be possible . 
 a few minor comments
Paragraph (version A):
The client instance makes an HTTP POST to the token management URI,
sending the access token in the appropriate header and signing the
request with the appropriate key.
Paragraph (version A):
If the access token has expired, the AS SHOULD honor the rotation
request to the token management URL since it is likely that the
client instance is attempting to refresh the expired token.  To
support this, the AS MAY apply different lifetimes for the use of the
token in management vs. its use at an RS.  An AS MUST NOT honor a
rotation request for an access token that has been revoked, either by
the AS or by the client instance through the revoke-access-token.
Paragraph (version B):
If the client instance has an access token and that access token
expires, the client instance might want to rotate the access token.
Rotating an access token consists of issuing a new access token in
place of an existing access token, with the same rights and
properties as the original token, apart from an updated expiration
time.
Paragraph (version B):
To rotate an access token, the client instance makes an HTTP POST to
the token management URI, sending the access token in the appropriate
header and signing the request with the appropriate key.
Paragraph (version B):
Note that in many cases, the access token will have expired for
regular use.  To facilitate token rotation, the AS SHOULD honor the
rotation request of the expired access token since it is likely that
the client instance is attempting to refresh the expired token.  To
support this, the AS MAY allow a longer lifetime for token management
compared to its use at an RS.  An AS MUST NOT honor a rotation
request for an access token that has been revoked or otherwise
disabled.
Paragraph (version B):
If the token is validated and the key is appropriate for the request,
the AS MUST invalidate the current access token associated with this
URL, if possible.  Note that stateless access tokens can make
proactive revocation difficult within a system, see security-
stateless-tokens.
Paragraph (version B):
The AS responds with an HTTP 200 with a JSON body consisting of the
rotated access token in the "access_token" field described in
response-token-single.  The value of the access token MUST NOT be the
same as the current value of the access token used to access the
management API.  The response MUST include an access token management
URL, and the value of this URL MAY be different from the URL used by
the client instance to make the rotation call.  The client instance
MUST use this new URL to manage the rotated access token.
Paragraph (version B):
The access rights in the "access" array for the rotated access token
MUST be included in the response and MUST be the same as the token
before rotation.  If the client instance requires different access
rights, the client instance can request a new access token by
creating request or by continue-modify.
Paragraph (version B):
The contents and format of the access token are at the discretion of
the AS, and are opaque to the client instance within GNAP.  As
discussed in the companion document, I-D.ietf-gnap-resource-servers,
the AS and RS can make use of stateless access tokens with an
internal structure and format.  These access tokens allow an RS to
validate the token without having to make any external calls at
runtime, allowing for benefits in some deployments, the discussion of
which are outside the scope of this specification.
Paragraph (version B):
However, the use of such self-contained access tokens has an effect
on the ability of the AS to provide certain functionality defined
within this specification.  Specifically, since the access token is
self-contained, it is difficult or impossible for an AS to signal to
all RS's within an ecosystem when a specific access token has been
revoked.  Therefore, an AS in such an ecosystem should probably not
offer token revocation functionality to client instances, since the
client instance's calls to such an endpoint is effectively
meaningless.  However, a client instance calling the token revocation
function will also throw out its copy of the token, so such a placebo
endpoint might not be completely meaningless.  Token rotation
similarly difficult because the AS has to revoke the old access token
after a rotation call has been made.  If the access tokens are
completely self-contained and non-revocable, this means that there
will be a period of time during which both the old and new access
tokens are valid and usable, which is an increased security risk for
the environment.
Paragraph (version B):
These problems can be mitigated by keeping the validity time windows
of self-contained access tokens reasonably short, limiting the time
after a revocation event that a revoked token could be used.
Additionally, the AS could proactively signal to RS's under its
control identifiers for revoked tokens that have yet to expire.  This
type of information push would be expected to be relatively small and
infrequent, and its implementation is outside the scope of this
specification.
Paragraph (version B):
If a client instance makes a call to rotate an access token but the
network connection is dropped before the client instance receives the
response with the new access token, the system as a whole can end up
in an inconsistent state, where the AS has already rotated the old
access token and invalidated it, but the client instance only has
access to the invalidated access token and not the newly rotated
token value.  If the client instance retries the rotation request, it
would fail because the client is no longer presenting a valid and
current access token.  A similar situation can occur during grant
continuation, where the same client instance calls to continue or
update a grant request without successfully receiving the results of
the update.
Paragraph (version B):
To combat this, both continue-request and token-management are
designed to be idempotent, where subsequent calls to the same
function with the same credentials are meant to produce the same
results.  For example, multiple calls to rotate the same access token
need to result in the same rotated token value.
Paragraph (version B):
In practice, an AS can hold on to an old token value for such limited
purposes.  For example, to support rotating access tokens over
unreliable networks, the AS receives the initial request to rotate an
access token and creates a new token value and returns it.  The AS
also marks the old token value as having been used to create the
newly-rotated token value.  If the AS sees the old token value within
a small enough time window, such as a few seconds since the first
rotation attempt, the AS can return the same rotated access token.
Furthermore, once the system has seen the newly-rotated token in use,
the original token can be discarded because the client instance has
proved that it did receive the token.  The result of this is a system
that is eventually self-consistent without placing an undue
complexity burden on the client instance.