Internet DRAFT - draft-sakimura-oidc-structured-token

draft-sakimura-oidc-structured-token



 



INTERNET-DRAFT                                               N. Sakimura
Intended Status: Informational                                       NRI
Expires: August 29, 2013                                   B. Kihara, Ed
                                                              K. Shimizu
                                                                 Lepidum
                                                       February 25, 2013


        Structured Access Token for Sharing Authorization Grant
         between a Resource Server and an Authorization Server
                draft-sakimura-oidc-structured-token-01


Abstract

   This specification defines a format of structured access tokens that
   are issued by the authorization server and received by the resource
   server. By using this format, the authorization server and the
   resource server can be easily separated and the validation of the
   access token can be performed offline.

Status of this Memo

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

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts.

   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."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/1id-abstracts.html

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html


Copyright and License Notice

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

 


Sakimura, et al.        Expires August 29, 2013                 [Page 1]

INTERNET DRAFT          Structured Access Token            February 2013


   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.



Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Terminology  . . . . . . . . . . . . . . . . . . . . . . .  3
   2. Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . .  4
   3.  Structured Access Token Format . . . . . . . . . . . . . . . .  5
     3.1.  "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . . .  5
     3.2.  "sub" (Subject) Claim  . . . . . . . . . . . . . . . . . .  5
     3.3.  "aud" (Audience) Claim . . . . . . . . . . . . . . . . . .  5
     3.4.  "exp" (Expiration Time) Claim  . . . . . . . . . . . . . .  5
     3.5.  "nbf" (Not Before) Claim . . . . . . . . . . . . . . . . .  5
     3.6.  "iat" (Issued At) Claim  . . . . . . . . . . . . . . . . .  5
     3.7.  "claims" Claim . . . . . . . . . . . . . . . . . . . . . .  5
     3.8.  "azp" Claim  . . . . . . . . . . . . . . . . . . . . . . .  6
   4.  Structured Access Token Usages . . . . . . . . . . . . . . . .  7
   5. Examples of the structured access token usage . . . . . . . . .  8
     5.1.  UserInfo Request . . . . . . . . . . . . . . . . . . . . .  8
     5.2.  Aggregated/Distributed Claims in OpenID Connect  . . . . .  8
     5.3. Other Usages  . . . . . . . . . . . . . . . . . . . . . . .  9
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 10
   7.  Privacy Considerations . . . . . . . . . . . . . . . . . . . . 10
   8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 10
   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 10
     9.2.  Informative References . . . . . . . . . . . . . . . . . . 11
   Appendix A.  Document History  . . . . . . . . . . . . . . . . . . 12
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12









 


Sakimura, et al.        Expires August 29, 2013                 [Page 2]

INTERNET DRAFT          Structured Access Token            February 2013


1.  Introduction

   The OAuth 2.0 authorization framework ([RFC6749]) defines a method
   for third-party client authorization using access tokens. In OAuth,
   an authorization server issues an access token to a client and the
   client requests resources from a resource server sending the access
   token.

   In OAuth, an authorization server and a resource server need neither
   be the same server nor be closely-coupled. This means that a resource
   server may have to validate access tokens without information that is
   implicitly passed from authorization servers. However, the OAuth 2.0
   ([RFC6749]) framework does not define methods for resource servers to
   validate access tokens, leading to implementation specific non-
   interoperable validation methods.  

   To achieve better interoperability, this specification defines a
   format of structured access token that can be examined by the
   recipient. By using this format, the authorization server and the
   resource server can be easily separated and the validation of the
   access token can be performed offline.

   The format of structured access tokens specified in this document is
   based on the JSON Web Token (JWT) format ([I-D.ietf-oauth-json-web-
   token]).

   [[Note: this document should be harmonized with the jwt-bearer
   draft.]]

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














 


Sakimura, et al.        Expires August 29, 2013                 [Page 3]

INTERNET DRAFT          Structured Access Token            February 2013


2. Assumptions

   In this specification, it is assumed that the account at the
   protected server is linked to the subject at the issuer in advance. 

   The exact method of how this account linking is done is out of scope
   of this document. A few possible ways includes the pre-existing
   common identifier between the protected resource and the issuer, and
   the explicit linking by the user providing the protected resource
   credential together with the ID Token from the issuer. 






































 


Sakimura, et al.        Expires August 29, 2013                 [Page 4]

INTERNET DRAFT          Structured Access Token            February 2013


3.  Structured Access Token Format

   A structured access token will be a JWT ([I-D.ietf-oauth-json-web-
   token]) that contains claims defined in the following sections and
   other claims. The JWT MUST be signed unless otherwise the
   authenticity of the JWT is assured. The JWT MAY be encrypted by the
   issuer.

3.1.  "iss" (Issuer) Claim

   The "iss" (issuer) claim contains the identifier of the authorization
   server that issues the access token. Use of this claim is REQUIRED.

3.2.  "sub" (Subject) Claim

   The "sub" (subject) claim contains the identifier of the entity whose
   claims are provided in exchange for the access token. The value of
   this claims needs to be shared between the authorization server and
   the resource server. Use of this claim is REQUIRED.

3.3.  "aud" (Audience) Claim

   The "aud" (audience) claim contains the identifier of the resource
   server that receives the access token and returns claims. Use of this
   claim is REQUIRED.

3.4.  "exp" (Expiration Time) Claim

   The "exp" (expiration time) claim contains the expiration time on or
   after which the JWT MUST NOT be accepted. The value is an integer of
   seconds from 1970-01-01T00:00:00Z. Use of this claim is REQUIRED.

3.5.  "nbf" (Not Before) Claim

   The "nbf" (not before) claim contains the time before which the JWT
   MUST NOT be acceppted. The value is an integer of seconds from 1970-
   01-01T00:00:00Z. Use of this claim is OPTIONAL.

3.6.  "iat" (Issued At) Claim

   The "iat" (issued at) claim contains the time at which the JWT was
   issued. The value is an integer of seconds from 1970-01-01T00:00:00Z.
   Use of this claim is OPTIONAL.

3.7.  "claims" Claim

   The "claims" claim contains the required claims about the entity
   identified by the "sub" claim. The value is an array of strings. Use
 


Sakimura, et al.        Expires August 29, 2013                 [Page 5]

INTERNET DRAFT          Structured Access Token            February 2013


   of this claim is OPTIONAL.

3.8.  "azp" Claim

   The "azp" (Authorized Presenter) claim contains the identifier of the
   party which is intended to use the access token and to request
   resources. Use of this claim is OPTIONAL.









































 


Sakimura, et al.        Expires August 29, 2013                 [Page 6]

INTERNET DRAFT          Structured Access Token            February 2013


4.  Structured Access Token Usages

   Structured access tokens can be used for accessing protected
   resources like end-users' claims. The resource server and the
   authorization server need to share entities' identifiers beforehand
   in order to validate access tokens and provide resources by the "sub"
   claim.

   When a resource server received a structured access token, the
   resource server is RECOMMENDED to validate the token in the following
   criteria. Note that the validation criteria MAY vary by the contents
   of tokens.

   o The "aud" claim MUST be the identifier of the resource server or
     the value that the resource server can accept as the audience of
     the token.
   o The value of the "exp" claim MUST be more than the current time.
   o If the "nbf" claim exists, the value MUST be less than or equal to
     the current time.
   o If the "iat" claim exists, the value can be used to reject tokens
     that are issued at an unacceptable time (e.g., future or too far
     past). The acceptable range is dependent on the actual protocol and
     implementation used and is out of scope for this document.
   o The token MUST be a valid JWT and signed by the authorization
     server identified by the "iss" claim.
   o The "iss" claim MUST be an identifier of an acceptable
     authorization server. The acceptable values MAY vary by the "sub"
     claim or other claims.
   o The "sub" claim MUST be a valid identifier of an entity. The value
     will be authorization-server specific, so the resource server needs
     to evaluate the "sub" claim together with the "iss" claim.
   o The authorization server specified by the "iss" claim MUST be
     granted to manage authorization by the entity specified by the
     "sub" claim.
   o If "azp" claim exists and the protected resource policy requires
     the identification of the client, the resource server MUST compare
     the "azp" and the client identifier. The exact method to achieve it
     is dependent on the actual protocol used and is out of scope for
     this specification. 

   After validating a structured access token, a resource server SHOULD
   provide resources specified by the "claims" claim or other claims.






 


Sakimura, et al.        Expires August 29, 2013                 [Page 7]

INTERNET DRAFT          Structured Access Token            February 2013


5. Examples of the structured access token usage

5.1.  UserInfo Request

   When using a structured access token at UserInfo Endpoint of OpenID
   Connect, the "claims" claim will be used to specify requested claim
   names.

   The following is a non-normative example of a JSON object ([RFC4627])
   that could be encoded into a JWT ([I-D.ietf-oauth-json-web-token])
   for a UserInfo request:

      {
        "aud":"https://op.example.com/",
        "iss":"https://op.example.com/",
        "sub":"alice",
        "exp":1360387733,
        "iat":1360386833,
        "nbf":1360385933,
        "claims": [
          "gender",
          "picture"
        ],
        "azp":"https://rp.example.com/"
      }

5.2.  Aggregated/Distributed Claims in OpenID Connect

   In [OIDF.Connect.Standard], when using a structured access token for
   requesting claims to a claims provider in aggregated or distributed
   claims, the "claims" claim is used in the request. Typically the
   claims provider and the OpenID provider are separated parties, so
   they need to share the identifier of the entity specified by the
   "sub" claim beforehand. This may be done, for example, by the claims
   provider performing as a relying party to the OpenID provider.

   The following is a non-normative example of a JSON object ([RFC4627])
   that could be encoded into JWT:

      {
        "aud":"https://cp.example.com/",
        "iss":"https://op.example.com/",
        "sub":"82FB7D5C-C6F1-4505-B230-796F31DF683E",
          // PPID from the OpenID provider to the claims provider
        "exp":1360847733,
        "iat":1360846833,
        "nbf":1360845933,
        "claims": [
 


Sakimura, et al.        Expires August 29, 2013                 [Page 8]

INTERNET DRAFT          Structured Access Token            February 2013


          "gender",
          "picture"
        ],
        "azp":"https://rp.example.com/"
      }

5.3. Other Usages

   This document specifies methods for relying parties to obtain claims
   using structured access tokens. Furthermore, the format may be used
   for access grant transfer between entities; for example, Alice grants
   Bob to download her picture and the authorization server issues an
   access token for Bob to access the protected picture. The protocols
   to issue and transfer access tokens are out of scope of this
   document.

































 


Sakimura, et al.        Expires August 29, 2013                 [Page 9]

INTERNET DRAFT          Structured Access Token            February 2013


6.  Security Considerations

   If an access token is a "Bearer" access token, the token MUST be sent
   over a protected channel such as TLS ([RFC5246]). 

   Resource servers MUST verify the "iss" claim in the access tokens and
   confirm that the issuer is trusted to issue access tokens for the
   subject. The process in which the issuer is trusted is out of scope
   of this document; several examples are described in the Assumption
   section.

   Resource servers are responsible to protect resources from invalid
   access tokens. Resource servers MUST deny request when requested
   claims contains unacceptable values. Resource servers SHOULD provide
   end-users with methods to discard trust on authorization servers.


7.  Privacy Considerations

   In the distributed claims model, the access token issued to the
   client might contain information that should not disclosed to the
   client. To protect such information, JWE ([I-D.ietf-jose-json-web-
   encryption]) MAY be used to encrypt the contents of the token.

   In the distributed claims model, resource servers might know which
   client is requesting claims via the "azp" claim. The "azp" claim is
   OPTIONAL and authorization servers MAY omit the claim.


8.  IANA Considerations

   <IANA considerations text>


9.  References

9.1.  Normative References

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

   [OIDF.Connect.Standard]  Sakimura, N., Bradley, J., Jones, M., de
              Medeiros, B., and E. Jay, "OpenID Connect Standard 1.0 -
              draft 16", January 2013.

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


Sakimura, et al.        Expires August 29, 2013                [Page 10]

INTERNET DRAFT          Structured Access Token            February 2013


9.2.  Informative References

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

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246, August 2008.

   [OIDF.Connect.Messages]  Sakimura, N., Bradley, J., Jones, M., de
              Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect
              Messages 1.0 - draft 15", January 2013,
              <http://openid.net/specs/openid-connect-messages-
              1_0.html>.

   [I-D.ietf-jose-json-web-encryption]  Jones, M., "JSON Web Algorithms
              (JWA)", draft-ietf-jose-json-web-algorithms (work in
              progress), December 2012.































 


Sakimura, et al.        Expires August 29, 2013                [Page 11]

INTERNET DRAFT          Structured Access Token            February 2013


Appendix A.  Document History

   -01 in 5
   o Renamed draft's title.
   o Inserted Assumption section.
   o Inserted Other Usages section.
   o Inserted Security Considerations and Privacy Consideration
   sections.
   o Removed OIDC dependency from the normative text.

   -00
   o Initial draft.

Authors' Addresses


   Nat Sakimura
   Nomura Research Institute

   EMail: n-sakimura@nri.co.jp


   Boku Kihara (editor)
   Lepidum Co. Ltd.

   EMail: kihara@lepidum.co.jp


   Kazuki Shimizu
   Lepidum Co. Ltd.





















Sakimura, et al.        Expires August 29, 2013                [Page 12]