Internet DRAFT - draft-howard-jwt-attr-cert
draft-howard-jwt-attr-cert
Network Working Group L. Howard
Internet-Draft PADL
Intended status: Experimental December 24, 2013
Expires: June 27, 2014
JWT Attribute Certificate (JAC)
draft-howard-jwt-attr-cert-00.txt
Abstract
A JSON Web Token Attribute Certificate (JAC) contains additional
claims, grouped by scope, to be presented alongside a primary JWT.
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 June 27, 2014.
Copyright Notice
Copyright (c) 2013 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.
Howard Expires June 27, 2014 [Page 1]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . 3
2. Requirements notation . . . . . . . . . . . . . . . . 4
3. Terminology . . . . . . . . . . . . . . . . . . . . . 5
4. JWT Attribute Certificate (JAC) Overview . . . . . . . 6
4.1. Example JAC . . . . . . . . . . . . . . . . . . . . . 6
5. JAC Claims . . . . . . . . . . . . . . . . . . . . . . 7
5.1. "cdi" (Certificate Digest Information) . . . . . . . . 7
5.1.1. "alg" (Digest Algorithm) . . . . . . . . . . . . . . . 7
5.1.2. "dig" (Digest Value) . . . . . . . . . . . . . . . . . 7
5.2. "scope" (Scope) . . . . . . . . . . . . . . . . . . . 7
5.3. "scope_description" (Scope Description) . . . . . . . 8
6. Rules for Creating and Validating a JAC . . . . . . . 9
7. Security Considerations . . . . . . . . . . . . . . . 11
8. IANA Considerations . . . . . . . . . . . . . . . . . 12
8.1. JSON Web Token Claims Registry . . . . . . . . . . . . 12
8.2. JAC Digest Algorithm Registry . . . . . . . . . . . . 12
8.2.1. Registration Template . . . . . . . . . . . . . . . . 12
8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 13
8.3. JAC Scope Registry . . . . . . . . . . . . . . . . . . 13
8.3.1. Registration Template . . . . . . . . . . . . . . . . 13
8.3.2. Initial Registry Contents . . . . . . . . . . . . . . 14
9. References . . . . . . . . . . . . . . . . . . . . . . 16
9.1. Normative References . . . . . . . . . . . . . . . . . 16
9.2. Informative References . . . . . . . . . . . . . . . . 16
Appendix A. BrowserID JAC Profile . . . . . . . . . . . . . . . . 17
Author's Address . . . . . . . . . . . . . . . . . . . 18
Howard Expires June 27, 2014 [Page 2]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
1. Introduction
JSON Web Tokens [I-D.ietf-oauth-json-web-token] may be used to convey
certified claims about a subject. For example, the [BrowserID]
protocol uses a JWT containing an e-mail address and public key to
bind an identity to a signing key. JWTs may include a variety of
claims, however doing so in a single token has some disadvantages.
First, all claims must be issued by the same entity (or the issuer
must contact other authorities). Secondly, they must share the same
validity period. Finally, the disclosing party must either reveal
all claims or none.
Attribute certificates (similar to those described in [RFC3281])
allow additional claims, grouped by scope, to be disclosed
separately. A special claim is used to bind the attribute
certificate to the primary JWT with which it is associated.
This document defines protocols, procedures and conventions for using
a JWT as an attribute certificate.
Howard Expires June 27, 2014 [Page 3]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
2. Requirements notation
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].
The reader is assumed to be familiar with the terms used in the base
JWT specifications.
Howard Expires June 27, 2014 [Page 4]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
3. Terminology
Certificate Digest Information a claim binding a JAC to its Primary
JWT
Claims individual properties in a JAC or other JWT
JAC Validity the time interval in which the JAC is valid, as
expressed by the "nbf" ([I-D.ietf-oauth-json-web-token] Section
4.1.5) and "exp" ([I-D.ietf-oauth-json-web-token] Section 4.1.4)
claims
JWT Attribute Certificate (JAC) a JWT associated with a Primary JWT
that containing additional claims about a subject
JSON Web Token (JWT) a signed or encrypted structure for
representing a set of Claims to be transferred between two parties
Primary JWT a JWT certifying an identity and typically containing a
public key
Scope a string that identifies the set of claims in a JAC
Scope Description a human readable description of the Scope suitable
for displaying by a user agent
Howard Expires June 27, 2014 [Page 5]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
4. JWT Attribute Certificate (JAC) Overview
A JWT Attribute Certificate is a JSON Web Token (per
[I-D.ietf-oauth-json-web-token] Section 3) that contains the
mandatory claims defined in Section 5 and is associated with another
JWT (the Primary JWT).
4.1. Example JAC
The following is an example of a JAC Claims Set containing a end-
user's profile claims:
{
"scope": "profile",
"scope_description": "My standard profile",
"cdi": {
"alg": "S256",
"dig": "fHf5HxJuzWTSuepVY3N0BvWlvuXPNiUHwqsk0HX1Cjc"
},
"iss": "ca.example.com",
"name": "Luke Howard",
"given_name": "Luke",
"family_name": "Howard",
"website": "www.example.com/~lukeh",
"preferred_username": "lukeh"
}
The Claims Set is signed (in this case, by a key belonging to
"ca.example.com") and encoded as a JWT; this encoding is the JAC.
Howard Expires June 27, 2014 [Page 6]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
5. JAC Claims
The following Claim Names are defined for use in JACs. JACs MAY
contain other claims. Claims present in the Primary JWT, with the
exception of "iss", "aud", "exp", "nbf", "iat" and "jti", SHOULD NOT
be present in a JAC.
5.1. "cdi" (Certificate Digest Information)
The "cdi" claim binds a JAC to its Primary JWT. Its value is a JSON
object containing the name/value pairs (sub-claims) defined below.
Use of this claim is REQUIRED.
(Note that the term "certificate" is used for consistency with
[RFC3281]; however there is no explicit requirement that the Primary
JWT contain a public key or otherwise function as a certificate.)
5.1.1. "alg" (Digest Algorithm)
This sub-claim contains a string identifying the digest algorithm
used to create a digest of the Primary JWT. Algorithms are defined
in Section 8.2 of this document.
5.1.2. "dig" (Digest Value)
This sub-claim contains the digest of the JWS (per
[I-D.ietf-jose-json-web-signature]) or JWE (per
[I-D.ietf-jose-json-web-encryption]) Compact Serialization of the
Primary JWT. The digest algorithm is the one specified by the "alg"
sub-claim. The digest is encoded as a base 64 URL string.
In the case where the Primary JWT has a JWS JSON Serialization and
has multiple signatures, the first signature is used when
constructing the JWS Compact Serialization for input to the digest
algorithm.
5.2. "scope" (Scope)
The "scope" claim is a case-sensitive string identifying the set of
claims contained in the JAC. Use of this claim is REQUIRED.
In order to prevent collisions, Scopes SHOULD either be registered in
the IANA JAC Scopes registry defined in Section 8.3, or be a
Collision-Resistant Name (per [I-D.ietf-oauth-json-web-token] Section
2). A producer and consumer of a JAC MAY agree to use Scopes that
are not registered or Collision-Resistant, but this is discouraged
owing to the possibility of collision.
Howard Expires June 27, 2014 [Page 7]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
Where the subject of the Primary JWT is an end-user, support for the
scopes defined in [OpenID.Core] Section 5.4 is RECOMMENDED.
5.3. "scope_description" (Scope Description)
The "scope_description" claim is a string suitable for displaying to
an end-user that describes the set of claims contained in the JAC.
Use of this claim is OPTIONAL.
Howard Expires June 27, 2014 [Page 8]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
6. Rules for Creating and Validating a JAC
To create a JAC, one MUST perform these steps. The order of the
steps is not significant in cases where there are no dependencies
between the inputs and outputs of the steps.
1. Choose a digest algorithm to be used in creating a digest of the
Primary JWT. Place the corresponding Algorithm Name in the "alg"
sub-claim of the "cdi" claim.
2. Create a digest of the Primary JWT and place it in the "dig" sub-
claim of the "cdi" claim.
3. Place the Scope in the "scope" claim.
4. Optionally, place a human readable description of the Scope in
the "scope_description" claim.
5. Create a JWT containing a Claims Set with the above along with
any additional claims relevant to the Scope.
When validating a JAC, the following steps MUST be taken. The order
of the steps is not significant in cases where there are no
dependencies between the inputs and outputs of the steps. If any of
the listed steps fails then the JAC MUST be rejected for processing.
Note that the manner in which JACs are presented to the validating
party is outside the scope of this specification. However, it is
assumed that the Primary JWT is available to the party validating the
JAC.
1. The Primary JWT MUST be a valid JWT, per
[I-D.ietf-oauth-json-web-token] Section 7.
2. The JAC MUST be a valid JWT, per [I-D.ietf-oauth-json-web-token]
Section 7.
3. The algorithm in the "alg" sub-claim of the "cdi" claim MUST be
a supported algorithm.
4. The digest in the "dig" sub-claim of the "cdi" claim MUST match
the digest of the Primary JWT using the selected algorithm.
5. The "scope" claim of the JAC MUST be unique amongst all JACs
presented with the Primary JWT.
6. To avoid ambiguity, the JAC SHOULD NOT have any claims that are
present in the Primary JWT, other than "iss", "aud", "exp",
Howard Expires June 27, 2014 [Page 9]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
"nbf", "iat" and "jti".
7. If the "iss" claim of the JAC is absent, or is present and
matches the "iss" claim of the Primary JWT, the JAC MUST be
signed with a key that signed the Primary JWT; otherwise, the
signer of the JAC MUST be directly trusted (by configuration or
otherwise).
8. The time for which the JAC is being validated MUST be within the
JAC Validity. If the evaluation time is equal to the time
expressed by either of the "nbf" or "exp" claims, the JAC is
timely and this check succeeds. Note that in some applications,
the evaluation time MAY not be the same as the current time.
(This language is based on [RFC3281] Section 5.)
9. The JAC Validity MUST match or be within the interval specified
by the "nbf" and "exp" claims of the Primary JWT, if present.
10. If the JAC contains an "aud" claim, and the validating party
would normally process this claim in a Primary JWT, then the
validating party MUST identify itself with one of its values
(per [I-D.ietf-oauth-json-web-token] Section 4.1.3). This claim
has the effect of restricting any values of the "aud" claim in
the primary JWT.
Additional checks:
1. The JAC MAY be rejected on the basis of further validating party
configuration.
2. The validating party MAY filter the attributes returned to the
application on the basis of configuration information.
Howard Expires June 27, 2014 [Page 10]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
7. Security Considerations
JACs must be valid JWTs and are subject to the same validation policy
as the Primary JWT.
JAC issuers must protect their private keys.
The binding between a JAC and the Primary JWT cannot be stronger than
the algorithm used to generate the Certificate Digest Information.
Claims Names that are present in both the Primary JWT and the JAC
(other than those explicitly permitted by this specification) SHOULD
be rejected.
To avoid conflicts between identically named claims in different
JACs, the validating party SHOULD group claims by Scope when
surfacing them to the application.
If the issuer of an JAC differs from the issuer of the Primary JWT,
trust in any claims made by the JAC is subject to local policy (for
example, different issuers may only be trusted to issue JACs for
certain Scopes, and/or to issue certain claims). If no such policy
exists, the JAC MUST be ignored.
User agents that permit selective disclosure of JACs SHOULD provide a
means for the user to determine what claims are being made by a JAC,
particularly in the cases where the JAC is not issued by the issuer
of the Primary JWT, and/or only the Scope Description is displayed by
default.
The presentation of JACs is not defined by this document. However,
JACs SHOULD be presented over a secure channel and, when used with
Primary JWTs that contain a public key, SHOULD be secured by the
corresponding private key so that the choice of JACs is protected.
This specification does not discuss revocation. It is assumed that
the JAC Validity will typically be less than the time required to
issue and distribute revocation information (see [RFC3281] Section
6). If revocation is required, it SHOULD be discussed when profiling
this specification for a particular application or protocol.
Howard Expires June 27, 2014 [Page 11]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
8. IANA Considerations
8.1. JSON Web Token Claims Registry
The following Claim Names are registered in the IANA JSON Web Token
Claims registry created in [I-D.ietf-oauth-json-web-token] Section
10.1.
o Claim Name: "cdi"
o Claim Description: Certificate Digest Information
o Change Controller: IESG
o Specification Document(s): Section 5.1 of [[ this document ]]
o Claim Name: "scope"
o Claim Description: JWT Attribute Certificate Scope
o Change Controller: IESG
o Specification Document(s): Section 5.2 of [[ this document ]]
o Claim Name: "scope_description"
o Claim Description: JWT Attribute Certificate Scope Description
o Change Controller: IESG
o Specification Document(s): Section 5.3 of [[ this document ]]
8.2. JAC Digest Algorithm Registry
This section creates a registry of digest algorithms for binding a
JAC to its Primary JWT.
8.2.1. Registration Template
Algorithm Name: A string identifying the digest algorithm. It is
RECOMMENDED that the name be short -- not to exceed 8 characters
without a compelling reason to do so. This name is case-
sensitive.
Algorithm Description: Brief description of the digest algorithm.
Howard Expires June 27, 2014 [Page 12]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
Implementation Requirements: The algorithm implementation
requirements, which must be one the words Required, Recommended,
Optional, Deprecated, or Prohibited.
Change Controller: For Standards Track RFCs, state "IESG". For
others, give the name of the responsible party. Other details
(e.g., postal address, email address, home page URI) may also be
included.
Specification Document(s): Reference to the document(s) that specify
the algorithm, preferably including URI(s) that can be used to
retrieve copies of the document(s). An indication of the relevant
sections may also be included but is not required.
8.2.2. Initial Registry Contents
o Algorithm Name: "S256"
o Algorithm Description: SHA-256 hash
o Implementation Requirements: Required
o Change Controller: IESG
o Specification Document(s): Section 6.2 of [SHS]
o Algorithm Name: "S512"
o Algorithm Description: SHA-512 hash
o Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 6.4 of [SHS]
8.3. JAC Scope Registry
This section creates a registry of Scopes for grouping the set of
claims in a JAC.
8.3.1. Registration Template
Scope Name: A string identifying the Scope.
Howard Expires June 27, 2014 [Page 13]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
Scope Description: Brief description of the Scope. The description
MAY include the Claim Names.
Change Controller: For Standards Track RFCs, state "IESG". For
others, give the name of the responsible party. Other details
(e.g., postal address, email address, home page URI) may also be
included.
Specification Document(s): Reference to the document(s) that specify
the algorithm, preferably including URI(s) that can be used to
retrieve copies of the document(s). An indication of the relevant
sections may also be included but is not required.
8.3.2. Initial Registry Contents
o Scope Name: "profile"
o Scope Description: The End-User's default profile claims, which
are name, family_name, given_name, middle_name, nickname,
preferred_username, profile, picture, website, gender, birthdate,
zoneinfo, locale, and updated_at.
o Change Controller: The OpenID Foundation
o Specification Document(s): Section 5.4 of [OpenID.Core]
o Scope Name: "email"
o Scope Description: The email and email_verified claims
o Change Controller: The OpenID Foundation
o Specification Document(s): Section 5.4 of [OpenID.Core]
o Scope Name: "address"
o Scope Description: The address claim
o Change Controller: The OpenID Foundation
o Specification Document(s): Section 5.4 of [OpenID.Core]
o Scope Name: "phone"
o Scope Description: The phone_number and phone_number_verified
claims
Howard Expires June 27, 2014 [Page 14]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
o Change Controller: The OpenID Foundation
o Specification Document(s): Section 5.4 of [OpenID.Core]
Howard Expires June 27, 2014 [Page 15]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[I-D.ietf-jose-json-web-algorithms]
Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms-18 (work in progress),
November 2013.
[I-D.ietf-jose-json-web-encryption]
Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", draft-ietf-jose-json-web-encryption-18
(work in progress), November 2013.
[I-D.ietf-jose-json-web-key]
Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key-18 (work in progress),
November 2013.
[I-D.ietf-jose-json-web-signature]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature-18
(work in progress), November 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-13 (work in
progress), November 2013.
[OpenID.Core]
Jones, M., "OpenID Connect Basic Client Implementer's
Guide", December 2013.
[SHS] "Secure Hash Standard (SHS)", FIPS PUB 180-4, March 2012.
9.2. Informative References
[RFC3281] Farrell, S. and R. Housley, "An Internet Attribute
Certificate Profile for Authorization", RFC 3281,
April 2002.
[BrowserID]
Adida, B., "BrowserID Specification", February 2013.
Howard Expires June 27, 2014 [Page 16]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
Appendix A. BrowserID JAC Profile
This section is non-normative.
A [BrowserID] user agent (UA) may present a set of JACs as a value of
the "jac" claim in an assertion (that is, an array of strings where
each value is a JAC). This ensures that chosen set is authenticated
by the user's private key. BrowserID JACs MUST use the JWS Compact
Serialization.
The Primary JWT is the certificate issued by the user's identity
provider (IdP). The JAC validating party is the BrowserID Relying
Party (RP). The RP MAY provide the UA with a set of Scopes it
desires in order to authorize the user; these should be divided into
Essential Scopes (those which it deems necessary to authorize the
user) and Voluntary Scopes (those which it deems useful but not
necessary). (This language is consistent with [OpenID.Core].)
The IdP SHOULD localize the "scope_description" claim according to
the UA locale.
The UA SHOULD only present JACs when the RP has indicated its desire
for specific Scopes, and the user has explicitly authorized
disclosure of the JACs corresponding to those Scopes. The RP SHOULD
deal gracefully with a user who refuses to disclose Essential Scopes,
for example by providing limited authorization rather than rejecting
the request entirely.
Howard Expires June 27, 2014 [Page 17]
Internet-Draft JWT Attribute Certificate (JAC) December 2013
Author's Address
Luke Howard
PADL Software
PO Box 59
Central Park, VIC 3145
Australia
Email: lukeh@padl.com
Howard Expires June 27, 2014 [Page 18]
