Network Working Group                                      E. Wahlstroem
Internet-Draft                                          Nexus Technology
Intended status: Informational                             March 9, 2015
Expires: September 10, 2015


OAuth 2.0 Introspection over the Constrained Application Protocol (CoAP)
            draft-wahlstroem-ace-oauth-introspection-01.txt

Abstract

   This document defines a method for a client or resource server to
   query an OAuth authorization server to determine meta- information
   about an OAuth token using the Constrained Application Protocol
   (CoAP) [4].  An client in possession of a OAuth2 token can use it to
   get metadata about the token like validity and approved scopes.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 10, 2015.

Copyright Notice

   Copyright (c) 2015 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.



Wahlstroem             Expires September 10, 2015               [Page 1]


Internet-Draft   OAuth 2.0 Token Introspection over CoAP      March 2015


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   2
   3.  Introspection CoAP Endpoint . . . . . . . . . . . . . . . . .   3
   4.  Introspection Request . . . . . . . . . . . . . . . . . . . .   3
   5.  Introspection Response  . . . . . . . . . . . . . . . . . . .   3
   6.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
   9.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   5
   10. Change Log  . . . . . . . . . . . . . . . . . . . . . . . . .   5
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     11.1.  Normative References . . . . . . . . . . . . . . . . . .   5
     11.2.  Informative References . . . . . . . . . . . . . . . . .   6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

1.  Introduction

   OAuth2 enables clients to access protected resources by obtaining an
   access token, which is defined in "The OAuth 2.0 Authorization
   Framework" [2] as "a string representing an access authorization
   issued to the client", rather than using the resource owner's
   credentials directly.

   Tokens are issued to clients by an authorization server and the
   client uses the access token to access the protected resources hosted
   by the resource server.  This document defines a way for a holder of
   this token, mostly Clients and Resource Servers, to get metadata like
   validity and scopes for the token.  The OAuth Token Introspection
   specification [14] defines a way to validate the token using HTTP
   POST or HTTP GET.  This document reuses the work done in the OAuth
   Token Introspection and defines a mapping of the request and response
   to CoAP [4] to be used by constrained devices.

2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in "Key words for use in
   RFCs to Indicate Requirement Levels" [1].

   This document also re-uses terminology from RFC 6749 [2] and RFC 6750
   [6].







Wahlstroem             Expires September 10, 2015               [Page 2]


Internet-Draft   OAuth 2.0 Token Introspection over CoAP      March 2015


3.  Introspection CoAP Endpoint

   The Introspection CoAP Endpoint responds to CoAP Confirmable requests
   from token holders, particularly Clients and Resource Servers.  The
   endpoint takes a single parameter representing the token (and
   optionally further authentication) and returns a JSON [7] document
   representing the meta information surrounding the token.  The
   endpoint MUST be protected by DTLS [5] or equivalent.

4.  Introspection Request

   The token holder makes a request to the Introspection CoAP Endpoint
   by adding the following parameters using the "application/x-www-form-
   urlencoded" format with a character encoding of UTF-8 in the CoAP
   request entity-body:

   In order to prevent man-in-the-middle attacks, the client MUST
   require the use of DTLS with server authentication for any request
   sent to the authorization and token endpoints.  If certificate-based
   server authentication is used then the client MUST validate the TLS
   certificate of the authorization server, as defined by RFC6125.

   The Endpoint SHOULD also require some form of authentication to
   access this endpoint, such as the Client Authentication as described
   in OAuth 2.0 [RFC6749] or equivalent.

   token:  REQUIRED.  The string value of the token.

   resource_id:  OPTIONAL.  A service-specific string identifying the
      resource that the client doing the introspection is asking about.

   token_type_hint:  OPTIONAL.  A hint about the type of the token
      submitted for introspection.  Clients MAY pass this parameter in
      order to help the authorization server to optimize the token
      lookup.  If the server is unable to locate the token using the
      given hint, it MUST extend its search across all of its supported
      token types.  An authorization server MAY ignore this parameter,
      particularly if it is able to detect the token type automatically.
      Values for this field are defined in OAuth Token Revocation
      [RFC7009].

5.  Introspection Response

   If the introspection request is valid and authorized, the
   authorization server responds with a CoAP message using Content
   response code with the response encoded as a JSON structure in the
   payload of the message.  If the request failed client authentication
   or is invalid, the authorization server returns an error response



Wahlstroem             Expires September 10, 2015               [Page 3]


Internet-Draft   OAuth 2.0 Token Introspection over CoAP      March 2015


   using the CoAP 4.00 'Bad Request' response code with the error
   messages defined in Section 5.2 of RFC 6749 [2].

   The JSON structure in the payload response includes the top-level
   members defined in Section 2.2 in the OAuth Token Introspection
   specification [14].  It's recommended to only return the active
   attribute considering the lossy and constrained nature of CoAP client
   and server network and capacity.

   Note that the HTTP "Cache-Control" parameters MAY be used in the CoAP
   response message.

6.  Example

   For example, the client makes a CoAP request carrying the
   introspection request protected with DTLS to the authorization
   server.  It then receives a response containing metadata about the
   token.

   In the example below content-type 51 corresponds to the 'application/
   x-www-form-urlencoded'.


              Authorization
      Client     Server
         |         |
         |<=======>| DTLS Connection Establishment
         |         |
         +-------->| Header: POST (T=CON, Code=0.02, MID=0x7d34,
         | POST    | ct=51, Uri-Path:"introspect"
         |         | Payload: cid=qwerty&cs=2123&t=X3241Affw.4233-99JXJ
         |         |
         |<--------+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34,
         | 2.05    | ct=50)
         |         | Payload: <JSON-Payload>
         |         |

   <JSON-Payload>:=
      {
       "active": true
      }


              Figure 1: Example CoAP Introspection Exchange.







Wahlstroem             Expires September 10, 2015               [Page 4]


Internet-Draft   OAuth 2.0 Token Introspection over CoAP      March 2015


7.  Security Considerations

   TBD

8.  IANA Considerations

   TBD

9.  Acknowledgements

   The author would like to thank Justin Richer for his work on [14]
   richer-oauth-introspection and Hannes Tschofenigs [10] and [11].
   This document is heavily inspired from those document's and it
   borrows a lot of texts from there work.  The author would also like
   to thank Samuel Erdtman for valuable input.

10.  Change Log

   [[This section to be removed prior to publication as an RFC]]

   Draft 01 - Using same request format as OAuth2 introspection endpoint
   to ease proxying.

11.  References

11.1.  Normative References

   [1]        Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [2]        Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
              6749, October 2012.

   [3]        Saint-Andre, P. and J. Hodges, "Representation and
              Verification of Domain-Based Application Service Identity
              within Internet Public Key Infrastructure Using X.509
              (PKIX) Certificates in the Context of Transport Layer
              Security (TLS)", RFC 6125, March 2011.

   [4]        Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252, June 2014.

   [5]        Rescorla, E. and N. Modadugu, "Datagram Transport Layer
              Security Version 1.2", RFC 6347, January 2012.

   [6]        Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
              Framework: Bearer Token Usage", RFC 6750, October 2012.




Wahlstroem             Expires September 10, 2015               [Page 5]


Internet-Draft   OAuth 2.0 Token Introspection over CoAP      March 2015


   [7]        Crockford, D., "The application/json Media Type for
              JavaScript Object Notation (JSON)", RFC 4627, July 2006.

   [8]        Tschofenig, H. and T. Fossati, "A TLS/DTLS Profile for the
              Internet of Things", draft-ietf-dice-profile-10 (work in
              progress), March 2015.

   [9]        Tschofenig, H., "OAuth 2.0: Audience Information", draft-
              tschofenig-oauth-audience-00 (work in progress), February
              2013.

11.2.  Informative References

   [10]       Tschofenig, H., "The OAuth 2.0 Bearer Token Usage over the
              Constrained Application Protocol (CoAP)", draft-
              tschofenig-ace-oauth-bt-01 (work in progress), March 2015.

   [11]       Tschofenig, H., "The OAuth 2.0 Internet of Things (IoT)
              Client Credentials Grant", draft-tschofenig-ace-oauth-
              iot-01 (work in progress), March 2015.

   [12]       Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", draft-ietf-oauth-json-web-token-32 (work in
              progress), December 2014.

   [13]       Hunt, P., Richer, J., Mills, W., Mishra, P., and H.
              Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security
              Architecture", draft-hunt-oauth-pop-architecture-02 (work
              in progress), June 2014.

   [14]       Richer, J., "OAuth Token Introspection", draft-richer-
              oauth-introspection-06 (work in progress), July 2014.

   [15]       Bormann, C., "An Authorization Information Format (AIF)
              for ACE", draft-bormann-core-ace-aif-01 (work in
              progress), July 2014.

   [16]       Seitz, L., Gerdes, S., Selander, G., Mani, M., and S.
              Kumar, "ACE use cases", draft-seitz-ace-usecases-02 (work
              in progress), October 2014.

Author's Address









Wahlstroem             Expires September 10, 2015               [Page 6]


Internet-Draft   OAuth 2.0 Token Introspection over CoAP      March 2015


   Erik Wahlstroem
   Nexus Technology
   Sweden

   Email: erik.wahlstrom@nexusgroup.com
   URI:   https://www.nexusgroup.com













































Wahlstroem             Expires September 10, 2015               [Page 7]