rfc:7591

cid 232d63e31caccbe5a6047dba74776b159351d0161c2a23b0187bc7784b03d345 · original · open access · via rfc

Title: rfc:7591
Authors: 
Venue: rfc
Year: 2015
Canonical: rfc:7591
URL: https://www.rfc-editor.org/rfc/rfc7591.txt
Collector: rfc
OA: true

ABSTRACT
Abstract This specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7591. Copyright Notice Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 7 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 8 2.1. Relationship between Grant Types and Response Types . . . 12 2.2. Human-Readable Client Metadata . . . . . . . . . . . . . 13 2.3. Software Statement . . . . . . . . . . . . . . . . . . . 14 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 15 3.1. Client Registration Request . . . . . . . . . . . . . . . 16 3.1.1. Client Registration Request Using a Software Statement . . . . . . . . . . . . . . . . . . . . . . 18 3.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 19 3.2.1. Client Information Response . . . . . . . . . . . . . 19 3.2.2. Client Registration Error Response . . . . . . . . . 21 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 4.1. OAuth Dynamic Client Registration Metadata Registry . . . 22 4.1.1. Registration Template . . . . . . . . . . . . . . . . 24 4.1.2. Initial Registry Contents . . . . . . . . . . . . . . 24 4.2. OAuth Token Endpoint Authentication Methods Registry . . 27 4.2.1. Registration Template . . . . . . . . . . . . . . . . 28 4.2.2. Initial Registry Contents . . . . . . . . . . . . . . 28 5. Security Considerations . . . . . . . . . . . . . . . . . . . 28 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 32 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 7.1. Normative References . . . . . . . . . . . . . . . . . . 33 7.2. Informative References . . . . . . . . . . . . . . . . . 35 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 33 A.1. Open versus Protected Dynamic Client Registration . . . . 34 A.1.1. Open Dynamic Client Registration . . . . . . . . . . 34 A.1.2. Protected Dynamic Client Registration . . . . . . . . 34 A.2. Registration without or with Software Statements . . . . 34 A.2.1. Registration without a Software Statement . . . . . . 34 A.2.2. Registration with a Software Statement . . . . . . . 34 A.3. Registration by the Client or Developer . . . . . . . . . 34 A.3.1. Registration by the Client . . . . . . . . . . . . . 35 A.3.2. Registration by the Developer . . . . . . . . . . . . 35 A.4. Client ID per Client Instance or per Client Software . . 35 A.4.1. Client ID per Client Software Instance . . . . . . . 35 A.4.2. Client ID Shared among All Instances of Client Software . . . . . . . . . . . . . . . . . . . . . . 35 A.5. Stateful or Stateless Registration . . . . . . . . . . . 35 A.5.1. Stateful Client Registration . . . . . . . . . . . . 36 A.5.2. Stateless Client Registration . . . . . . . . . . . . 36 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 36 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 1. Introduction In order for an OAuth 2.0 [RFC6749] client to utilize an OAuth 2.0 authorization server, the client needs specific information to interact with the server, including an OAuth 2.0 client identifier to use at that server. This specification describes how an OAuth 2.0 client can be dynamically registered with an authorization server to obtain this information. As part of the registration process, this specification also defines a mechanism for the client to present the authorization server with a set of metadata, such as a set of valid redirection URIs. This metadata can either be communicated in a self-asserted fashion or as a set of metadata called a software statement, which is digitally signed or protected with a Message Authentication Code (MAC); in the case of a software statement, the issuer is vouching for the validity of the data about the client. Traditionally, registration of a client with an authorization server is performed manually. The mechanisms defined in this specification can be used either for a client to dynamically register itself with authorization servers or for a client developer to programmatically register the client with authorization servers. Multiple applications using OAuth 2.0 have previously developed mechanisms for accomplishing such registrations. This specification generalizes the registration mechanisms defined by "OpenID Connect Dynamic Client Registration 1.0" [OpenID.Registration] and used by "User Managed Access (UMA) Profile of OAuth 2.0" [UMA-Core] in a way that is compatible with both, while being applicable to a wider set of OAuth 2.0 use cases. 1.1. Notational Conventions 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]. Unless otherwise noted, all the protocol parameter names and values are case sensitive. 1.2. Terminology This specification uses the terms "access token", "authorization code", "authorization endpoint", "authorization grant", "authorization server", "client", "client identifier", "client secret", "grant type", "protected resource", "redirection URI", "refresh token", "resource owner", "resource server", "response type", and "token endpoint" defined by OAuth 2.0 [RFC6749] and uses the term "Claim" defined by JSON Web Token (JWT) [RFC7519]. This specification defines the following terms: Client Software Software implementing an OAuth 2.0 client. Client Instance A deployed instance of a piece of client software. Client Developer The person or organization that builds a client software package and prepares it for distribution. At the time the client is built, the developer is often not aware of who the deploying service provider organizations will be. Client developers will need to use dynamic registration when they are unable to predict aspects of the software, such as the deployment URLs, at compile time. For instance, this can occur when the software API publisher and the deploying organization are not the same. Client Registration Endpoint OAuth 2.0 endpoint through which a client can be registered at an authorization server. The means by which the URL for this endpoint is obtained are out of scope for this specification. Initial Access Token OAuth 2.0 access token optionally issued by an authorization server to a developer or client and used to authorize calls to the client registration endpoint. The type and format of this token are likely service specific and are out of scope for this specification. The means by which the authorization server issues this token as well as the means by which the registration endpoint validates this token are out of scope for this specification. Use of an initial access token is required when the authorization server limits the parties that can register a client. Deployment Organization An administrative security domain under which a software API (service) is deployed and protected by an OAuth 2.0 framework. In some OAuth scenarios, the deployment organization and the software API publisher are the same. In these cases, the deploying organization will often have a close relationship with client software developers. In many other cases, the definer of the service may be an independent third-party publisher or a standards organization. When working to a published specification for an API, the client software developer is unable to have a prior relationship with the potentially many deployment organizations deploying the software API (service). Software API Deployment A deployed instance of a software API that is protected by OAuth 2.0 (a protected resource) in a particular deployment organization domain. For any particular software API, there may be one or more deployments. A software API deployment typically has an associated OAuth 2.0 authorization server as well as a client registration endpoint. The means by which endpoints are obtained are out of scope for this specification. Software API Publisher The organization that defines a particular web-accessible API that may be deployed in one or more deployment environments. A publisher may be any standards body, commercial, public, private, or open source organization that is responsible for publishing and distributing software and API specifications that may be protected via OAuth 2.0. In some cases, a software API publisher and a client developer may be the same organization. At the time of publication of a web-accessible API, the software publisher often does not have a prior relationship with the deploying organizations. Software Statement A digitally signed or MACed JSON Web Token (JWT) [RFC7519] that asserts metadata values about the client software. In some cases, a software statement will be issued directly by the client developer. In other cases, a software statement will be issued by a third-party organization for use by the client developer. In both cases, the trust relationship the authorization server has with the issuer of the software statement is intended to be used as an input to the evaluation of whether the registration request is accepted. A software statement can be presented to an authorization server as part of a client registration request. 1.3. Protocol Flow +--------(A)- Initial Access Token (OPTIONAL) | | +----(B)- Software Statement (OPTIONAL) | | v v +-----------+ +---------------+ | |--(C)- Client Registration Request --| Client | | Client or | | Registration | | Developer |. [IANA.Language] IANA, "Language Subtag Registry", . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, . [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009, . [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2011, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", . [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, . [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 2014, . [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7522, DOI 10.17487/RFC7522, May 2015, . [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 2015, . 7.2. Informative References [OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0", November 2014, . [OpenID.Registration] Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Dynamic Client Registration 1.0", November 2014, . [RFC7592] Richer, J., Jones, M., Bradley, J., and M. Machulak, "OAuth 2.0 Dynamic Client Registration Management Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, . [UMA-Core] Hardjono, T., Maler, E., Machulak, M., and D. Catalano, "User-Managed Access (UMA) Profile of OAuth 2.0", Work in Progress, draft-hardjono-oauth-umacore-13, April 2015. Appendix A. Use Cases This appendix describes different ways that this specification can be utilized, including describing some of the choices that may need to be made. Some of the choices are independent and can be used in combination, whereas some of the choices are interrelated. A.1. Open versus Protected Dynamic Client Registration A.1.1. Open Dynamic Client Registration Authorization servers that support open registration allow registrations to be made with no initial access token. This allows all client software to register with the authorization server. A.1.2. Protected Dynamic Client Registration Authorization servers that support protected registration require that an initial access token be used when making registration requests. While the method by which a client or developer receives this initial access token and the method by which the authorization server validates this initial access token are out of scope for this specification, a common approach is for the developer to use a manual preregistration portal at the authorization server that issues an initial access token to the developer. A.2. Registration without or with Software Statements A.2.1. Registration without a Software Statement When a software statement is not used in the registration request, the authorization server must be willing to use client metadata values without them being digitally signed or MACed (and thereby attested to) by any authority. (Note that this choice is independent of the Open versus Protected choice, and that an initial access token is another possible form of attestation.) A.2.2. Registration with a Software Statement A software statement can be used in a registration request to provide attestation by an authority for a set of client metadata values. This can be useful when the authorization server wants to restrict registration to client software attested to by a set of authorities or when it wants to know that multiple registration requests refer to the same piece of client software. A.3. Registration by the Client or Developer A.3.1. Registration by the Client In some use cases, client software will dynamically register itself with an authorization server to obtain a client identifier and other information needed to interact with the authorization server. In this case, no client identifier for the authorization server is packaged with the client software. A.3.2. Registration by the Developer In some cases, the developer (or development software being used by the developer) will preregister the client software with the authorization server or a set of authorization servers. In this case, the client identifier value(s) for the authorization server(s) can be packaged with the client software. A.4. Client ID per Client Instance or per Client Software A.4.1. Client ID per Client Software Instance In some cases, each deployed instance of a piece of client software will dynamically register and obtain distinct client identifier values. This can be advantageous, for instance, if the code flow is being used, as it also enables each client instance to have its own client secret. This can be useful for native clients, which cannot maintain the secrecy of a client secret value packaged with the software, but which may be able to maintain the secrecy of a per- instance client secret. A.4.2. Client ID Shared among All Instances of Client Software In some cases, each deployed instance of a piece of client software will share a common client identifier value. For instance, this is often the case for in-browser clients using the implicit flow, when no client secret is involved. Particular authorization servers might choose, for instance, to maintain a mapping between software statement values and client identifier values, and return the same client identifier value for all registration requests for a particular piece of software. The circumstances under which an authorization server would do so, and the specific software statement characteristics required in this case, are beyond the scope of this specification. A.5. Stateful or Stateless Registration A.5.1. Stateful Client Registration In some cases, authorization servers will maintain state about registered clients, typically indexing this state using the client identifier value. This state would typically include the client metadata values associated with the client registration, and possibly other state specific to the authorization server's implementation. When stateful registration is used, operations to support retrieving and/or updating this state may be supported. One possible set of operations upon stateful registrations is described in [RFC7592]. A.5.2. Stateless Client Registration In some cases, authorization servers will be implemented in a manner the enables them to not maintain any local state about registered clients. One means of doing this is to encode all the registration state in the returned client identifier value, and possibly encrypting the state to the authorization server to maintain the confidentiality and integrity of the state. Acknowledgments The authors thank the OAuth Working Group, the User-Managed Access Working Group, and the OpenID Connect Working Group participants for their input to this document. In particular, the following individuals have been instrumental in their review and contribution to various draft versions of this document: Amanda Anganes, Derek Atkins, Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, George Fletcher, Thomas Hardjono, William Kim, Torsten Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat Sakimura, Christian Scholz, and Hannes Tschofenig. Authors' Addresses Justin Richer (editor) Email: ietf@justin.richer.org Michael B. Jones Microsoft Email: mbj@microsoft.com URI: http://self-issued.info/ John Bradley Ping Identity Email: ve7jtb@ve7jtb.com Maciej Machulak Newcastle University Email: maciej.machulak@gmail.com Phil Hunt Oracle Corporation Email: phil.hunt@yahoo.com