Archive for the 'Specifications' Category

April 10, 2014
JSON Web Key (JWK) Thumbprint Specification

IETF logoI created a new simple spec that defines a way to create a thumbprint of an arbitrary key, based upon its JWK representation. The abstract of the spec is:

This specification defines a means of computing a thumbprint value (a.k.a. digest) of JSON Web Key (JWK) objects analogous to the x5t (X.509 Certificate SHA-1 Thumbprint) value defined for X.509 certificate objects. This specification also registers the new JSON Web Signature (JWS) and JSON Web Encryption (JWE) Header Parameters and the new JSON Web Key (JWK) member name jkt (JWK SHA-256 Thumbprint) for holding these values.

The desire for this came up in an OpenID Connect context, but it’s of general applicability, so I decided to submit the spec to the JOSE working group. Thanks to James Manger, John Bradley, and Nat Sakimura for the discussions that led up to this spec.

The specification is available at:

An HTML formatted version is also available at:

April 1, 2014
Proof-Of-Possession Semantics for JSON Web Tokens (JWTs)

OAuth logoI’ve written a concise Internet-Draft on proof-of-possession for JWTs with John Bradley and Hannes Tschofenig. Quoting from the abstract:

This specification defines how to express a declaration in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular key and that the recipient can cryptographically confirm proof-of-possession of the key by the presenter. This property is also sometimes described as the presenter being a holder-of-key.

This specification intentionally does not specify the means of communicating the proof-of-possession JWT, nor the messages used to exercise the proof key, as these are necessarily application-specific. Rather, this specification defines a proof-of-possession JWT data structure to be used by other specifications that do define those things.

The specification is available at:

An HTML formatted version is available at:

March 31, 2014
JOSE -25 drafts fixing typos and updating references

IETF logoJOSE -25 drafts have been released that fix a few typos and update the WebCrypto reference to refer to the W3C Last Call draft.

The specifications are available at:

HTML formatted versions are also available at:

Thanks to Antonio Sanso for bringing the typos to our attention.

March 19, 2014
OAuth Assertions drafts updating spec references

OAuth logoI’ve released updated versions of the OAuth Assertions, OAuth SAML Assertion Profile, and OAuth JWT Assertion Profile specs that use current citations for the other specs they reference, including the JSON, JWT, OAuth Dynamic Registration, and OpenID Connect specs. I also improved the formatting of hanging lists. There were no content changes.

The specifications are available at:

HTML formatted versions are also available at:

March 18, 2014
JOSE -24 and JWT -19 drafts fixing errors found in examples

IETF logoJOSE -24 drafts have been released that fix two errors found in example values. The JWT -19 draft clarifies that support for Nested JWTs is optional. The JSON reference was also updated to RFC 7159 in all drafts.

The specifications are available at:

HTML formatted versions are also available at:

Thanks to Edmund Jay and Hideki Nara for finding the bugs in the examples.

March 3, 2014
JWT -18 addressing remaining WGLC comments

IETF logoDraft -18 of the JSON Web Token (JWT) spec has been released, which addresses the few remaining outstanding comments from Working Group Last Call (WGLC). All edits were clarifications, rather than normative changes. See the Document History appendix for a description of the changes made.

New -23 versions of the JSON Object Signing and Encryption (JOSE) specs were also released since one clarification made to JWT also applied to JWS.

The specifications are available at:

HTML formatted versions are also available at:

March 2, 2014
JOSE -22 drafts fixing requirements language nits

IETF logoUpdated JOSE and JWT drafts have been published that fix a few instances of incorrect uses of RFC 2119 requirements language, such as changing an occurrence of “MUST not” to “MUST NOT”. These drafts also reference the newly completed JSON specification – RFC 7158.

The specifications are available at:

HTML formatted versions are also available at:

February 26, 2014
OpenID Connect Specifications are Final!

OpenID logoThe OpenID Connect Core, OpenID Connect Discovery, OpenID Connect Dynamic Registration, and OAuth 2.0 Multiple Response Types specifications are now final! These are the result of almost four years of intensive work, both by specification writers including myself, and importantly, by developers who built, deployed, and interop tested these specifications throughout their development, significantly improving the quality of both the specs and their implementations as a result.

Throughout the development of OpenID Connect, we applied the design philosophy “keep simple things simple”. While being simple, OpenID Connect is also flexible enough to enable more complex things to be done, when necessary, such as encrypting claims, but this flexibility doesn’t come at the cost of keeping simple things simple. Its simplicity is intended to make it much easier for deployers to adopt than previous identity protocols. For instance, it uses straightforward JSON/REST data structures and messages, rather than XML/SOAP or ASN.1.

I want to take this opportunity to thank several key individuals without whose enthusiastic participation and expertise OpenID Connect wouldn’t have come into being. Nat Sakimura and John Bradley were there every step of the way, both motivating the features included and providing their insights into how to make the result both highly secure and very usable. Breno de Medeiros and Chuck Mortimore were also key contributors, bringing their practical insights informed by their implementation and deployment experiences throughout the process. I want to acknowledge Don Thibeau’s leadership, foresight, wisdom, and perseverance in leading the OpenID Foundation throughout this effort, bringing us to the point where today’s completed specifications are a reality. Numerous people at Microsoft deserve credit for believing in and supporting my work on OpenID Connect. And finally, I’d like to thank all the developers who built OpenID Connect code, told us what they liked and didn’t, and verified that what was specified would actually work well for them in practice.

Of course, final specifications are really just the beginning of the next journey. I look forward to seeing how people will use them to provide the Internet’s missing identity layer, making people’s online experiences, both on the Web and on their devices, easier, safer, and more satisfying!

February 14, 2014
JOSE -21 drafts incorporating WGLC feedback

IETF logoJSON Object Signing and Encryption (JOSE) drafts have been published that address the feedback received during Working Group Last Call (WGLC) on the specifications, which ran from January 22 to February 13, 2014. Two breaking (but very local) changes were made as a result of working group discussions:

  • Replaced the JWK key_ops values wrap and unwrap with wrapKey and unwrapKey to match the KeyUsage values defined in the current Web Cryptography API editor’s draft.
  • Compute the PBES2 salt parameter as (UTF8(Alg) || 0×00 || Salt Input), where the p2s Header Parameter encodes the Salt Input value and Alg is the alg Header Parameter value.

A few editorial changes were also made to improve readability. See the Document History sections for the issues addressed by these changes. One parallel editorial change was also made to the JSON Web Token (JWT) specification.

The specifications are available at:

HTML formatted versions are also available at:

Thanks to those of you who provided feedback on the specs during Working Group Last Call.

February 11, 2014
Vote to Approve Final OpenID Connect Specifications Under Way

OpenID logoThe vote to approve final OpenID Connect Core, OpenID Connect Discovery, OpenID Connect Dynamic Registration, and OAuth 2.0 Multiple Response Types specifications is now under way, as described at http://openid.net/2014/02/11/vote-for-final-openid-connect-specifications-and-implementers-drafts-is-open/. The OpenID Connect Session Management and OAuth 2.0 Form Post Response Mode specifications are also being approved as Implementer’s Drafts. Voting closes on Tuesday, February 25, 2014.

Please vote now!

February 7, 2014
Working Group Versions of Refactored OAuth Dynamic Client Registration Specs

OAuth logo
There are now OAuth working group versions of the refactored OAuth Dynamic Client Registration specifications:

  • OAuth 2.0 Dynamic Client Registration Core Protocol
  • OAuth 2.0 Dynamic Client Registration Metadata
  • OAuth 2.0 Dynamic Client Registration Management Protocol

These versions address review comments by Phil Hunt and Tony Nadalin. Phil is now also an author. The data structures and messages used are the same as the previous versions.

The drafts are available at:

HTML formatted versions are also available at:

January 28, 2014
Refactored OAuth Dynamic Client Registration Specs

OAuth logoI’ve posted an updated set of OAuth Dynamic Client Registration specifications that refactors the previous single specification into three specs:

  • OAuth 2.0 Dynamic Client Registration Core Protocol
  • OAuth 2.0 Dynamic Client Registration Metadata
  • OAuth 2.0 Dynamic Client Registration Management Protocol

This refactoring was the result of discussions at IETF 88 in Vancouver, BC. These refactored specifications are compatible with the previous single specification.

The Core specification contains only the definitions needed to perform dynamic registrations. It contains a completely rewritten Use Cases appendix, intended to clarify the different ways that dynamic registration can be performed. It also adds the Software Statement abstraction invented by Phil Hunt – enabling assertions to be made and used about the client software being registered.

The Metadata specification defines useful client metadata values that are nonetheless not essential to the core, such as “client_name”, “logo_uri”, and “software_id”. These were previously defined in the single dynamic registration spec.

The Management specification defines the client management operations Read, Update, and Delete, and addresses client secret rotation. These were previously defined in the single dynamic registration spec.

The drafts are available at:

HTML formatted versions are also available at:

These versions build upon prior restructuring work done by both Justin Richer and Phil Hunt.

January 20, 2014
JOSE -20 drafts intended for Working Group Last Call

IETF logoJSON Object Signing and Encryption (JOSE) -20 drafts have been published that incorporate the changes agreed to on last week’s JOSE working group call. Hopefully this brings us to the point of Working Group Last Call.

The only normative changes were to change the name of the “use_details” JWK member to “key_ops” and to clarify that “use” is meant for public key use cases, “key_ops” is meant for use cases in which public, private, or symmetric keys may be present, and that “use” and “key_ops” should not be used together.

The drafts, including JSON Web Token (JWT), now also reference draft-ietf-json-rfc4627bis, rather than RFC 4627.

The drafts are available at:

HTML formatted versions are also available at:

December 29, 2013
JOSE -19 drafts intended for Working Group Last Call

IETF logoJSON Object Signing and Encryption (JOSE) -19 drafts have been published that address all my remaining to-do items for the open issues. I believe the remainder of the issues are either ready to close because of actions already taken in the drafts (the majority of them), require further input to identify any specific remaining proposed actions, if any (a few of them), or will be considered during Working Group Last Call (a few of them). Only editorial changes and one addition were made – no breaking changes.

In short, I believe I have addressed everything needed to bring us to Working Group Last Call for the JWS, JWE, JWK, and JWA specs.

The one addition was to add the optional “use_details” JWK field, as discussed on the JOSE list and the WebCrypto list. While I realize that this proposal hasn’t gotten much review yet (I believe due to the holidays), I wanted to get it in so people can review it in context, and as a concrete step towards meeting a perceived need for additional JWK functionality from the WebCrypto working group. It’s cleanly separable from the rest of the spec, so if the JOSE WG ends up hating it, we can always take it back out and possibly move it to a separate spec. But at least we have a concrete write-up of it now to review.

I also made a one-paragraph change to the JSON Web Token (JWT) spec to reference text in JWE, rather than duplicating it in JWT.

See the History entries for details of the (small number of) changes made.

The drafts are available at:

HTML formatted versions are also available at:

December 20, 2013
Public review of proposed Final OpenID Connect Specifications has begun

OpenID logoI’m thrilled that OpenID Connect is significantly closer to being done today. Proposed final specifications were published yesterday and the 60 day public review period, which leads up a membership vote to approve the specifications, began today. Unless recall-class issues are found during the review, this means we’ll have final OpenID Connect specifications on Tuesday, February 25, 2014!

My sincere thanks to all of you who so generously shared your vision, expertise, judgment, and time to get us to this point – both those of you who worked on the specs and those who implemented and deployed them and tested your code with one another. I consider myself privileged to have done this work with you and look forward to what’s to come!

December 19, 2013
Fourth and possibly last Release Candidates for final OpenID Connect specifications and Notice of 24 hour review period

OpenID logoThe fourth and possibly last set of release candidates for final OpenID Connect specifications is now available. Per the decision on today’s working group call, this message starts a 24 hour final working group review period before starting the 60 day public review period. Unless significant issues are raised during the 24 hour review period, we will announce that these specifications are being proposed as Final Specifications by the working group.

The release candidates for Final Specification status are:

Accompanying release candidates for Implementer’s Draft status are:

Accompanying Implementer’s Guides are:

December 18, 2013
Third Release Candidates for final OpenID Connect specifications

OpenID logoThe third set of release candidates for final OpenID Connect specifications is now available. The changes since the second release candidates have mostly been to incorporate review comments on the Discovery, Dynamic Registration, and Multiple Response Types specifications. All known review comments have now been applied to the specifications.

The release candidates for Final Specification status are:

Accompanying release candidates for Implementer’s Draft status are:

Accompanying Implementer’s Guides are:

December 15, 2013
Second Release Candidates for final OpenID Connect specifications

OpenID logoThe second set of release candidates for final OpenID Connect specifications is now available. The updates to these specs since the first set of release candidates are the result of the most extensive reviews that the OpenID Connect specifications have ever undergone – including 10 complete reviews of the OpenID Connect Core spec. Thanks to all of you who helped make these the clearest, easiest to use OpenID Connect specifications ever!

The release candidates for Final Specification status are:

Accompanying release candidates for Implementer’s Draft status are:

Accompanying Implementer’s Guides are:

Please do a final review of the OpenID Connect Core specification now, because the results of all review comments have now been applied to it. A small number of review comments to the other specs remain, and will be addressed in the next few days, at which point a third and hopefully final set of release candidates will be released.

November 12, 2013
JOSE -18 and JWT -13 drafts continuing to address open issues

IETF logoJSON Object Signing and Encryption (JOSE) -18 and JSON Web Token (JWT) -13 drafts have been published. The JOSE drafts contain changes to address 34 of the 43 currently open issues. The JWT draft addresses several of the working group last call (WGLC) comments. No breaking changes were made to any of the specifications. The most visible change is that all registries now include Description fields – a change that was requested in JWT WGLC.

See the Document History appendices for more details on the changes made and issues addressed.

The drafts are available at:

HTML formatted versions are also available at:

October 15, 2013
First Release Candidates for final OpenID Connect specifications

OpenID logoI’m pleased to announce that the first release candidate versions for final OpenID Connect specifications have been published. The complete set of specifications has been updated to resolve all issues that had been filed against the specs being finished.

Please review these this week, in time for the in-person working group meeting on Monday. Besides publishing the specs in the usual formats, I’ve also created a Word version of the core spec with tracked changes turned on to facilitate people marking it up with specific proposed text changes. If you’re in the working group, please download it and make any corrections or changes you’d like to propose for the final specification.

The release candidate spec versions are:

Also, two implementer’s guides are also available to serve as self-contained references for implementers of basic Web-based Relying Parties:

Thanks to Nat Sakimura for the early feedback. The structure of Core has been changed somewhat since -13 to adopt some of his suggestions.

Next »