P. Madsen
Internet-Draft                                       Ping Identity Corp.
Intended status: Informational                                 June 2011
Expires: December 3, 2011


           OAuth Authorization Server Verification Interface
                            verification.xml

Abstract

   This specification defines an interface by which a Resource Server,
   upon receiving an access token on a call from a Client, can verify
   with the issuing Authorization Server that the token is valid, and
   optionally, retrieve identity attributes associated with the
   corresponding Client and/or Resource Owner.

Status of this Memo

   This document is an Internet-Draft and is subject to all provisions
   of Section 3 of RFC 3667.  By submitting this Internet-Draft, each
   author represents that any applicable patent or other IPR claims of
   which he or she is aware have been or will be disclosed, and any of
   which he or she become aware will be disclosed, in accordance with
   RFC 3668.

   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 December 3, 2011.














Madsen                  Expires December 3, 2011                [Page 1]

Internet-Draft         Ping Identity Verification              June 2011


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 3
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . . . 3
   2.  Access Token Validation Request/Response  . . . . . . . . . . . 3
     2.1.  RS sends Validation Request . . . . . . . . . . . . . . . . 4
     2.2.  Validation Server sends Response  . . . . . . . . . . . . . 4
     2.3.  Example (non-normative) . . . . . . . . . . . . . . . . . . 5
   Appendix A.  Contributors . . . . . . . . . . . . . . . . . . . . . 6
   Appendix B.  Document History . . . . . . . . . . . . . . . . . . . 6
   3.  Normative References  . . . . . . . . . . . . . . . . . . . . . 6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 6
   Intellectual Property and Copyright Statements  . . . . . . . . . . 7






































Madsen                  Expires December 3, 2011                [Page 2]

Internet-Draft         Ping Identity Verification              June 2011


1.  Introduction

   The OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2] provides a
   method for making authenticated HTTP requests to a resource hosted by
   some Resource Server using an access token.  Access tokens are issued
   to third-party clients by an Authorization Server with the (sometimes
   implicit) approval of the resource owner.

   Depending on the nature of the access token, a Resource Server may
   not be able to directly verify/validate the access token and may need
   to interact with an Authorization Server in order to verify the
   token.

   This specification defines an interface by which a Resource Server,
   upon receiving an access token on a call from a Client, can verify
   with the issuing Authorization Server that the token is valid, and
   optionally, retrieve identity attributes associated with the
   corresponding Client and/or Resource Owner

1.1.  Notational Conventions

   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 RFC 2119 [RFC2119].

   Unless otherwise noted, all the protocol parameter names and values
   are case sensitive.


2.  Access Token Validation Request/Response

   A Resource Server validates an access token by sending the token to
   an Authorization Server - as shown below.

   The validation endpoint interface profiles and extends that of the
   OAuth [I-D.ietf.oauth-v2] token endpoint, by defining a unique grant
   type and a format for the returned token.



        +--------+                                  +---------------+
        |        |                                  |               |
        |Resource|>--(A)----- access token    ----->| Authorization |
        | Server |                                  |     Server    |
        |        |<--(B)---- y/n + attributes  ----<|               |
        |        |                                  |               |
        +--------+                                  +---------------+




Madsen                  Expires December 3, 2011                [Page 3]

Internet-Draft         Ping Identity Verification              June 2011


            Figure 1: Access Token Validation Request/Response

   The request/response flow illustrated in Figure 1 includes the
   following steps:

   (A)  The RS sends an access token validation request to the
        Authorization Server that includes an access token and a
        grant_type of
        "urn:pingidentity.com:oauth2:grant_type:validate_bearer".

   (B)  The Authorization Server validates the access token and returns
        a list of attributes associated with the access token, formatted
        as JSON.

2.1.  RS sends Validation Request

   The client calls the Authorization Server with an access token
   request, the core details of which are defined in OAuth
   [I-D.ietf.oauth-v2] and by adding the following parameters:

   grant_type
         REQUIRED.  A value of
         "urn:pingidentity.com:oauth2:grant_type:validate_bearer"

   token
         REQUIRED.  The value of the access token for which validation
         is sought.

2.2.  Validation Server sends Response

   If validation was successful, the Authorization Server responds with
   a JSON formatted data structure with the following parameters at the
   top-level.

   token_type
         REQUIRED.  A value of 'ping_validated_token' indicates the
         access token was successfully validated.

   expires_in
         OPTIONAL.  The duration in seconds of the returned attributes.

   client_id
         OPTIONAL.  The client identifier of the client to whom the
         grant was originally issued.







Madsen                  Expires December 3, 2011                [Page 4]

Internet-Draft         Ping Identity Verification              June 2011


   access_token
         OPTIONAL.  A set of attributes.

   If validation was not successful, the Authorization Server responds
   with an OAuth error response with an error code of 'invalid grant'.

2.3.  Example (non-normative)

   The following examples illustrate access token validation request and
   responses.


GET /as/token.oauth2?client_id=a&client_secret=pwd&grant_type=urn:pingidentity.com:oauth2:grant_type:validate_bearer&token=5mZkmAoN6JjHREneyC7EuY8WdzGm1aRJaXT HTTP/1.1
Host: authz.example.net


                       Figure 2: Example GET Request



   HTTP/1.1 200 OK
   Content-Type: application/json; charset=UTF-8

   {"token_type":"ping_validated_token",
    "expires_in":"3600",
    "client_id":"a",
    "access_token":
       {"uid":"john",
        "fake-email":"john@example.cloud"}}


                   Figure 3: Example Successful Response



   HTTP/1.1 400 Bad Request
   Content-Type: application/json; charset=UTF-8

   {"error":"invalid_grant",
    "error_description":"token not found, expired or invalid"}


                  Figure 4: Example Unsuccessful Response








Madsen                  Expires December 3, 2011                [Page 5]

Internet-Draft         Ping Identity Verification              June 2011


Appendix A.  Contributors

   folks


Appendix B.  Document History

   [[ to be removed by RFC editor before publication as an RFC ]]


3.  Normative References

   [I-D.ietf.oauth-v2]
              Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The
              OAuth 2.0 Authorization Protocol",
              ID draft-ietf-oauth-v2-16 (work in progress), July 2011.

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


Author's Address

   Paul Madsen
   Ping Identity Corp.

   Email: pmadsen@pingidentity.com
























Madsen                  Expires December 3, 2011                [Page 6]

Internet-Draft         Ping Identity Verification              June 2011


Full Copyright Statement

   Copyright (C) The IETF Trust (2011).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.











Madsen                  Expires December 3, 2011                [Page 7]