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 26, 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.

Table of Contents

• 1. Introduction
• 2. Requirements notation
• 3. Terminology
• 4. JWT Attribute Certificate (JAC) Overview
• 4.1. Example JAC
• 5. JAC Claims
• 5.1. “cdi” (Certificate Digest Information)
• 5.1.1. “alg” (Digest Algorithm)
• 5.1.2. “dig” (Digest Value)
• 5.2. “scope” (Scope)
• 5.3. “scope_description” (Scope Description)
• 6. Rules for Creating and Validating a JAC
• 7. Security Considerations
• 8. IANA Considerations
• 8.1. JSON Web Token Claims Registry
• 8.2. JAC Digest Algorithm Registry
• 8.2.1. Registration Template
• 8.2.2. Initial Registry Contents
• 8.3. JAC Scope Registry
• 8.3.1. Registration Template
• 8.3.2. Initial Registry Contents
• 9. References
• 9.1. Normative References
• 9.2. Informative References
• Appendix A. BrowserID JAC Profile
• Author's Address

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.

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.

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

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.

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.

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.

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”, “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.

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.

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.

• Claim Name: “cdi”
• Claim Description: Certificate Digest Information
• Change Controller: IESG
• Specification Document(s): Section 5.1 of [[ this document ]]
• Claim Name: “scope”
• Claim Description: JWT Attribute Certificate Scope
• Change Controller: IESG
• Specification Document(s): Section 5.2 of [[ this document ]]
• Claim Name: “scope_description”
• Claim Description: JWT Attribute Certificate Scope Description
• Change Controller: IESG
• 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.

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

• Algorithm Name: “S256”
• Algorithm Description: SHA-256 hash
• Implementation Requirements: Required
• Change Controller: IESG
• Specification Document(s): Section 6.2 of [SHS]
• Algorithm Name: “S512”
• Algorithm Description: SHA-512 hash
• Implementation Requirements: Optional
• Change Controller: IESG
• 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.

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

• Scope Name: “profile”
• 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.
• Change Controller: The OpenID Foundation
• Specification Document(s): Section 5.4 of [OpenID.Core]
• Scope Name: “email”
• Scope Description: The email and email_verified claims
• Change Controller: The OpenID Foundation
• Specification Document(s): Section 5.4 of [OpenID.Core]
• Scope Name: “address”
• Scope Description: The address claim
• Change Controller: The OpenID Foundation
• Specification Document(s): Section 5.4 of [OpenID.Core]
• Scope Name: “phone”
• Scope Description: The phone_number and phone_number_verified claims
• Change Controller: The OpenID Foundation
• Specification Document(s): Section 5.4 of [OpenID.Core]

9. References

9.1. Normative References

9.2. Informative References

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.

Author's Address