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]
