Draft: draft-ietf-ace-oauth-authz

Commentary: Mostly grammar stuff and punctuation . Feel free to reject anything that looks weird .
The specifications in this document is called the "framework" or "ACE
framework".  When referring to "profiles of this framework" it refers
to additional specifications that define the use of this
specification with concrete transport, and communication security
protocols (e.g., CoAP over DTLS).
The specifications in this document is called the "framework" or "ACE
framework".  When referring to "profiles of this framework" it refers
to additional specifications that define the use of this
specification with concrete transport and communication security
protocols (e.g., CoAP over DTLS).
A third building block is CBOR RFC7049, for encodings where JSON
RFC8259 is not sufficiently compact.  CBOR is a binary encoding
designed for small code and message size, which may be used for
encoding of self contained tokens, and also for encoding payload
transferred in protocol messages.
A third building block is CBOR RFC7049, for encodings where JSON
RFC8259 is not sufficiently compact.  CBOR is a binary encoding
designed for small code and message size, which may be used for
encoding of self contained tokens, and also for encoding payloads
transferred in protocol messages.
At the start of the protocol, there is an optional discovery step
where the client discovers the resource server and the resources this
server hosts.  In this step, the client might also determine what
permissions are needed to access the protected resource.  A generic
procedure is described in asDiscovery, profiles MAY define other
procedures for discovery.
At the start of the protocol, there is an optional discovery step
where the client discovers the resource server and the resources this
server hosts.  In this step, the client might also determine what
permissions are needed to access the protected resource.  A generic
procedure is described in asDiscovery; profiles MAY define other
procedures for discovery.
If the request from the client is authorized, the RS fulfills the
request and returns a response with the appropriate response code.
The RS uses the dynamically established keys to protect the
response, according to used communication security protocol.
If the request from the client is authorized, the RS fulfills the
request and returns a response with the appropriate response code.
The RS uses the dynamically established keys to protect the
response, according to the communication security protocol used.
RS has no valid access token for the sender of the request
regarding the requested action on that resource.
RS has a valid access token for the sender of the request, but
this does not allow the requested action on the requested
resource.
Note: These conditions ensure that RS can handle requests
autonomously once access was granted and a secure channel has been
established between C and RS.  The authz-info endpoint MUST NOT be
protected as specified above, in order to allow clients to upload
access tokens to RS (cf.  tokenAuthInfoEndpoint).
Unauthorized Resource Request messages MUST be denied with a client
error response.  In this response, the Resource Server SHOULD provide
proper AS Request Creation Hints to enable the Client to request an
access token from RS's AS as described in asInfo.
The AS Request Creation Hints message is sent by RS as a response to
an Unauthorized Resource Request message (see rreq) to help the
sender of the Unauthorized Resource Request message in acquiring a
valid access token.  The AS Request Creation Hints message is CBOR
map, with a MANDATORY element "AS" specifying an absolute URI (see
Section 4.3 of RFC3986) that identifies the AS in charge of RS.
A "audience" element containing a suggested audience that the
client should request towards the AS.
The RS has no valid access token for the sender of the request
regarding the requested action on that resource.
The RS has a valid access token for the sender of the request, but
that token does not authorize the requested action on the
requested resource.
Note: These conditions ensure that the RS can handle requests
autonomously once access was granted and a secure channel has been
established between C and RS.  The authz-info endpoint, as part of
the process for authorizing to protected resources, is not itself a
protected resource and MUST NOT be protected as specified above (cf.
tokenAuthInfoEndpoint).
Unauthorized Resource Request messages MUST be denied with an
"unauthorized_client" error response.  In this response, the Resource
Server SHOULD provide proper AS Request Creation Hints to enable the
Client to request an access token from RS's AS as described in
asInfo.
The AS Request Creation Hints message is sent by an RS as a response
to an Unauthorized Resource Request message (see rreq) to help the
sender of the Unauthorized Resource Request message acquire a valid
access token.  The AS Request Creation Hints message is a CBOR map,
with a MANDATORY element "AS" specifying an absolute URI (see
Section 4.3 of RFC3986) that identifies the appropriate AS for the
RS.
A "audience" element containing a suggested audience that the
client should request at the AS.
A RS that is using the client-nonce mechanism and that receives an
access token MUST verify that this token contains a cnonce claim,
with a client-nonce value that is fresh according to the
information stored at the first step above.  If the cnonce claim
is not present or if the cnonce claim value is not fresh, it MUST
discard the access token.  If this was an interaction with the
authz-info endpoint the RS MUST also respond with an error message
using a response code equivalent to the CoAP code 4.01
(Unauthorized).
To request an access token, the client obtains authorization from the
resource owner or uses its client credentials as grant.  The
authorization is expressed in the form of an authorization grant.
A RS that is using the client-nonce mechanism and that receives an
access token MUST verify that this token contains a cnonce claim,
with a client-nonce value that is fresh according to the
information stored at the first step above.  If the cnonce claim
is not present or if the cnonce claim value is not fresh, the RS
MUST discard the access token.  If this was an interaction with
the authz-info endpoint the RS MUST also respond with an error
message using a response code equivalent to the CoAP code 4.01
(Unauthorized).
To request an access token, the client obtains authorization from the
resource owner or uses its client credentials as a grant.  The
authorization is expressed in the form of an authorization grant.
The grant type is selected depending on the use case.  In cases where
the client acts on behalf of the resource owner, authorization code
grant is recommended.  If the client acts on behalf of the resource
owner, but does not have any display or very limited interaction
possibilities it is recommended to use the device code grant defined
in I-D.ietf-oauth-device-flow.  In cases where the client does not
acts autonomously the client credentials grant is recommended.
For details on the different grant types, see section 1.3 of RFC6749.
The OAuth 2.0 framework provides an extension mechanism for defining
additional grant types so profiles of this framework MAY define
additional grant types, if needed.
Authentication of the client is mandatory independent of the grant
type when requesting the access token from the token endpoint.  In
the case of client credentials grant type, the authentication and
grant coincide.
The grant type is selected depending on the use case.  In cases where
the client acts on behalf of the resource owner, the authorization
code grant is recommended.  If the client acts on behalf of the
resource owner, but does not have any display or has very limited
interaction possibilities, it is recommended to use the device code
grant defined in I-D.ietf-oauth-device-flow.  In cases where the
client does not acts autonomously the client credentials grant is
recommended.
For details on the different grant types, see section 1.3 of RFC6749.
The OAuth 2.0 framework provides an extension mechanism for defining
additional grant types, so profiles of this framework MAY define
additional grant types, if needed.
Authentication of the client is mandatory independent of the grant
type when requesting an access token from the token endpoint.  In the
case of the client credentials grant type, the authentication and
grant coincide.
The OAuth framework defines one client credential type in section
2.3.1 of RFC6749: client id and client secret.  I-D.erdtman-ace-rpcc
adds raw-public-key and pre-shared-key to the client credentials
types.  Profiles of this framework MAY extend with additional client
credentials client certificates.
Client credential does not, by default, authenticate the AS that the
client connects to.  In classic OAuth, the AS is authenticated with a
TLS server certificate.
Profiles of this framework MUST specify how clients authenticate the
AS and how communication security is implemented, otherwise server
side TLS certificates, as defined by OAuth 2.0, are required.
The authorization endpoint is used to interact with the resource
owner and obtain an authorization grant in certain grant flows.  The
primary use case for this framework is machine-to-machine
interactions, not involving the resource owner in the authorization
flow, therefore this endpoint is out of scope here.  Future profiles
may define constrained adaptation mechanisms for this endpoint as
well.  Non-constrained clients interacting with constrained resource
servers can use the specification in section 3.1 of RFC6749 and the
attack countermeasures suggested in section 4.2 of RFC6819.
The OAuth framework defines one client credential type in section
2.3.1 of RFC6749: client id and client secret.  I-D.erdtman-ace-rpcc
adds raw-public-key and pre-shared-key to the client credentials
types.  Profiles of this framework MAY extend with an additional
client credentials type using client certificates.
The client credential grant does not, by default, authenticate the AS
that the client connects to.  In classic OAuth, the AS is
authenticated with a TLS server certificate.
Profiles of this framework MUST specify how clients authenticate the
AS and how communication security is implemented.  By default, server
side TLS certificates, as defined by OAuth 2.0, are required.
The OAuth 2.0 authorization endpoint is used to interact with the
resource owner and obtain an authorization grant, in certain grant
flows.  The primary use case for the ACE-OAuth framework is for
machine-to-machine interactions that do not involve the resource
owner in the authorization flow; therefore, this endpoint is out of
scope here.  Future profiles may define constrained adaptation
mechanisms for this endpoint as well.  Non-constrained clients
interacting with constrained resource servers can use the
specification in section 3.1 of RFC6749 and the attack
countermeasures suggested in section 4.2 of RFC6819.
The content type (for CoAP-based interactions) or media type (for
HTTP-based interactions) "application/ace+cbor" MUST be used for
the error response.
The Content-Format (for CoAP-based interactions) or media type
(for HTTP-based interactions) "application/ace+cbor" MUST be used
for the error response.
The requesting entity sends a POST request to the introspection
endpoint at the AS, the profile MUST specify how the communication is
protected.  If CBOR is used, the payload MUST be encoded as a CBOR
map with a "token" entry containing either the access token or a
reference to the token (e.g., the cti).  Further optional parameters
representing additional context that is known by the requesting
entity to aid the AS in its response MAY be included.
The requesting entity sends a POST request to the introspection
endpoint at the AS.  The profile MUST specify how the communication
is protected.  If CBOR is used, the payload MUST be encoded as a CBOR
map with a "token" entry containing either the access token or a
reference to the token (e.g., the cti).  Further optional parameters
representing additional context that is known by the requesting
entity to aid the AS in its response MAY be included.
with the token reference.  Self-contained token MUST, at a minimum,
be integrity protected but they MAY also be encrypted.
with the token reference.  Self-contained tokens MUST, at a minimum,
be integrity protected but they MAY also be encrypted.
All communication between the client and the Authorization Server
MUST be encrypted, integrity and replay protected.  Furthermore
responses from the AS to the client MUST be bound to the client's
request to avoid attacks where the attacker swaps the intended
response for an older one valid for a previous request.  This
requires that the client and the Authorization Server have
previously exchanged either a shared secret, or their public keys
in order to negotiate a secure communication.  Furthermore the
client MUST be able to determine whether an AS has the authority
to issue access tokens for a certain RS.  This can be done through
pre-configured lists, or through an online lookup mechanism that
in turn also must be secured.
All communication between the client and the Authorization Server
MUST be encrypted, integrity and replay protected.  Furthermore
responses from the AS to the client MUST be bound to the client's
request to avoid attacks where the attacker swaps the intended
response for an older one valid for a previous request.  This
requires that the client and the Authorization Server have
previously exchanged either a shared secret or their public keys
in order to negotiate a secure communication.  Furthermore the
client MUST be able to determine whether an AS has the authority
to issue access tokens for a certain RS.  This can be done through
pre-configured lists, or through an online lookup mechanism that
in turn also must be secured.
The communication between the Resource Server and the
Authorization Server via the introspection endpoint MUST be
encrypted, integrity and replay protected.  Furthermore responses
from the AS to the RS MUST be bound to the RS's request.  This
requires that the client and the Authorization Server have
previously exchanged either a shared secret, or their public keys
in order to negotiate a secure communication.  Furthermore the RS
MUST be able to determine whether an AS has the authority to issue
access tokens itself.  This is usually configured out of band, but
could also be performed through an online lookup mechanism
provided that it is also secured in the same way.
The communication between the Resource Server and the
Authorization Server via the introspection endpoint MUST be
encrypted, integrity and replay protected.  Furthermore responses
from the AS to the RS MUST be bound to the RS's request.  This
requires that the RS and the Authorization Server have previously
exchanged either a shared secret, or their public keys in order to
negotiate a secure communication.  Furthermore the RS MUST be able
to determine whether an AS has the authority to issue access
tokens itself.  This is usually configured out of band, but could
also be performed through an online lookup mechanism provided that
it is also secured in the same way.
The initial communication between the client and the Resource
Server can not be secured in general, since the RS is not in
possession of on access token for that client, which would carry
the necessary parameters.  Certain security mechanisms (e.g.  DTLS
with server-side authentication via a certificate or a raw public
key) can be possible and are RECOMMEND if supported by both
parties.  After the client has successfully transmitted the access
token to the RS, a secure communication protocol MUST be
established between client and RS for the actual resource request.
This protocol MUST provide encryption, integrity and replay
protection as well as a binding between requests and responses.
This requires that the client learned either the RS's public key
or received a symmetric proof-of-possession key bound to the
access token from the AS.  The RS must have learned either the
client's public key or a shared symmetric key from the claims in
the token or an introspection request.  Since ACE does not provide
profile negotiation between C and RS, the client MUST have learned
what profile the RS supports (e.g. from the AS or pre-configured)
and initiate the communication accordingly.
The initial communication between the client and the Resource
Server can not be secured in general, since the RS is not in
possession of on access token for that client, which would carry
the necessary parameters.  Certain security mechanisms (e.g.  DTLS
with server-side authentication via a certificate or a raw public
key) can be possible and are RECOMMEND if supported by both
parties.  After the client has successfully transmitted the access
token to the RS, a secure communication protocol MUST be
established between client and RS for the actual resource request.
This protocol MUST provide confidentiality, integrity and replay
protection as well as a binding between requests and responses.
This requires that the client learned either the RS's public key
or received a symmetric proof-of-possession key bound to the
access token from the AS.  The RS must have learned either the
client's public key or a shared symmetric key from the claims in
the token or an introspection request.  Since ACE does not provide
profile negotiation between C and RS, the client MUST have learned
what profile the RS supports (e.g. from the AS or pre-configured)
and initiate the communication accordingly.
Communication with the authz-info endpoint, as well as the various
error responses defined in this framework all potentially include
sending information over an unprotected channel.  These messages may
leak information to an adversary.  For example errors responses for
requests to the Authorization Information endpoint can reveal
information about an otherwise opaque access token to an adversary
who has intercepted this token.
Communication with the authz-info endpoint, as well as the various
error responses defined in this framework, all potentially include
sending information over an unprotected channel.  These messages may
leak information to an adversary.  For example error responses for
requests to the Authorization Information endpoint can reveal
information about an otherwise opaque access token to an adversary
who has intercepted this token.
In some scenarios it may be possible to protect the communication
with the authz-info endpoint (e.g. through DTLS with only server-side
authentication).  In cases where this is not possible this framework
RECOMMENDS to use encrypted CWTs or opaque references and need to be
subjected to introspection by the RS.
If the initial unauthorized resource request message (see rreq) is
used, the client MUST make sure that it is not sending sensitive
content in this request.  While GET and DELETE requests only reveal
the target URI of the resource, while POST and PUT requests would
reveal the whole payload of the intended operation.
In some scenarios it may be possible to protect the communication
with the authz-info endpoint (e.g. through DTLS with only server-side
authentication).  In cases where this is not possible this framework
RECOMMENDS to use encrypted CWTs or tokens that are opaque references
and need to be subjected to introspection by the RS.
If the initial unauthorized resource request message (see rreq) is
used, the client MUST make sure that it is not sending sensitive
content in this request.  While GET and DELETE requests only reveal
the target URI of the resource, POST and PUT requests would reveal
the whole payload of the intended operation.
If the audience addresses a group of resource servers, the mapping of
group identifier to individual RS has to be provisioned to each RS
before the group-audience is usable.  Managing dynamic groups could
be an issue, if the RS is not always reachable when the group
memberships change.  Furthermore issuing access tokens bound to
symmetric proof-of-possession keys that apply to a group-audience is
problematic, as an RS that is in possession of the access token can
impersonate the client towards the other RSs that are part of the
group.  It is therefore NOT RECOMMENDED to issue access tokens bound
to a group audience and symmetric proof-of possession keys.
If the audience addresses a group of resource servers, the mapping of
group identifier to individual RS has to be provisioned to each RS
before the group-audience is usable.  Managing dynamic groups could
be an issue, if any RS is not always reachable when the groups'
memberships change.  Furthermore, issuing access tokens bound to
symmetric proof-of-possession keys that apply to a group-audience is
problematic, as an RS that is in possession of the access token can
impersonate the client towards the other RSs that are part of the
group.  It is therefore NOT RECOMMENDED to issue access tokens bound
to a group audience and symmetric proof-of possession keys.
All of the IANA registries established in this document are defined
as expert review.  This section gives some general guidelines for
what the experts should be looking for, but they are being designated
as experts for a reason, so they should be given substantial
latitude.
All of the IANA registries established in this document are defined
to use a registration policy of Expert Review.  This section gives
some general guidelines for what the experts should be looking for,
but they are being designated as experts for a reason, so they should
be given substantial latitude.