One document matched: draft-ietf-oauth-dyn-reg-metadata-00.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN"
"http://xml.resource.org/authoring/rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
]>
<rfc category="std" docName="draft-ietf-oauth-dyn-reg-metadata-00"
ipr="trust200902">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc='yes' ?>
<?rfc tocdepth='3' ?>
<?rfc symrefs='yes' ?>
<?rfc sortrefs='yes' ?>
<?rfc compact='yes' ?>
<?rfc subcompact='no' ?>
<?rfc strict='yes' ?>
<?rfc notedraftinprogress='yes' ?>
<front>
<title abbrev="OAuth Dynamic Registration Metadata">OAuth 2.0 Dynamic Client Registration Metadata</title>
<author fullname="Justin Richer" initials="J" surname="Richer">
<organization>The MITRE Corporation</organization>
<address>
<email>jricher@mitre.org</email>
</address>
</author>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization abbrev="Microsoft">Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization abbrev="Ping Identity">Ping Identity</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
</address>
</author>
<author fullname="Maciej Machulak" initials="M" surname="Machulak">
<organization>Newcastle University</organization>
<address>
<email>m.p.machulak@ncl.ac.uk</email>
<uri>http://ncl.ac.uk/</uri>
</address>
</author>
<author fullname="Phil Hunt" initials="P" surname="Hunt">
<organization>Oracle Corporation</organization>
<address>
<email>phil.hunt@yahoo.com</email>
</address>
</author>
<date day="6" month="February" year="2014"/>
<area>Security</area>
<workgroup>OAuth Working Group</workgroup>
<abstract>
<t>
This specification defines client metadata values used to
describe attributes of dynamically registered OAuth 2.0 clients.
</t>
</abstract>
</front>
<middle>
<section anchor="Introduction" title="Introduction">
<t>
In order for an OAuth 2.0 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 ID to use at that server.
The <xref target="OAuth.Registration">OAuth 2.0
Dynamic Client Registration Core Protocol</xref> specification
describes how an OAuth 2.0 client
can be dynamically registered with an authorization server
to obtain this information
and how metadata about the client can be registered with the server.
</t>
<t>
This specification extends the core registration specification
by defining a specific set of client metadata values
that can be used to describe additional attributes
of dynamically registered OAuth 2.0 clients
beyond those defined in the core registration specification.
</t>
<section anchor="Notation" title="Notational Conventions">
<t>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 <xref
target="RFC2119"/>.</t>
<t>Unless otherwise noted, all the protocol parameter names and values
are case sensitive.</t>
</section>
<section anchor="Terminology" title="Terminology">
<t>
This specification uses the terms "Access Token", "Refresh Token",
"Authorization Code", "Authorization Grant", "Authorization Server",
"Authorization Endpoint", "Client", "Client Identifier", "Client
Secret", "Protected Resource", "Resource Owner", "Resource Server",
"Response Type", and
"Token Endpoint" defined by <xref target="RFC6749">OAuth 2.0</xref>
and the terms defined by
the <xref target="OAuth.Registration">OAuth 2.0 Client Dynamic Registration Core Protocol</xref>.
</t>
</section>
</section>
<section anchor="ClientMetadata" title="Client Metadata">
<t>
Registering client metadata values with an authorization server
may be necessary or useful to facilitate usage of
the authorization server by the client.
This specification extends the list of client metadata values
defined in <xref target="OAuth.Registration">OAuth 2.0 Client Dynamic Registration Core Protocol</xref>
with the following fields:
</t>
<t>
<list style="hanging">
<t hangText="client_name">Human-readable
name of the client to be presented to the user. If omitted, the
authorization server MAY display the raw <spanx style="verb">client_id</spanx>
value to the user instead. It is RECOMMENDED that clients always
send this field. The value of this field MAY be internationalized,
as described in <xref target="HumanReadableClientMetadata"/>.</t>
<t hangText="client_uri">URL of the homepage of the client.
If present, the server SHOULD display this URL to the end user in a
clickable fashion. It is RECOMMENDED that clients always send this
field. The value of this field MUST point to a valid web page. The
value of this field MAY be internationalized,
as described in <xref target="HumanReadableClientMetadata"/>.</t>
<t hangText="logo_uri">URL that references a
logo for the client. If present, the server SHOULD display this
image to the end user during approval. The value of this field MUST
point to a valid image file. The value of this field MAY be
internationalized,
as described in <xref target="HumanReadableClientMetadata"/>.</t>
<t hangText="scope">Space separated list of
scope values (as described in <xref target="RFC6749">OAuth 2.0
Section 3.3</xref>) that the client can use when requesting access
tokens. The semantics of values in this list is service specific. If
omitted, an authorization server MAY register a Client with a
default set of scopes.</t>
<t hangText="contacts">Array of email
addresses for people responsible for this client. The authorization
server MAY make these addresses available to end users for support
requests for the client. An authorization server MAY use these email
addresses as identifiers for an administrative page for this
client.</t>
<t hangText="tos_uri">URL that points to a
human-readable Terms of Service document for the client. The
Authorization Server SHOULD display this URL to the end-user if it
is given. The Terms of Service usually describe a contractual
relationship between the end-user and the client that the end-user
accepts when authorizing the client. The value of this field MUST
point to a valid web page. The value of this field MAY be
internationalized,
as described in <xref target="HumanReadableClientMetadata"/>.</t>
<t hangText="policy_uri">URL that points to
a human-readable Policy document for the client. The authorization
server SHOULD display this URL to the end-user if it is given. The
policy usually describes how an end-user's data will be used by the
client. The value of this field MUST point to a valid web page. The
value of this field MAY be internationalized,
as described in <xref target="HumanReadableClientMetadata"/>.</t>
<t hangText="jwks_uri">URL for the Client's
<xref target="JWK">JSON Web Key Set</xref> document representing the
client's public keys. The value of this field MUST point to a valid
JWK Set. These keys MAY be used for higher level protocols that
require signing or encryption.</t>
<t hangText="software_id">
Identifier for the software that comprises a client.
Unlike <spanx style="verb">client_id</spanx>,
which is issued by the authorization server and generally varies
between instances, the <spanx style="verb">software_id</spanx> is
asserted by the client software and is intended to be shared between
all copies of the client software. The value for this field MAY be a
<xref target="RFC4122">UUID</xref>. The identifier SHOULD NOT change
when software version changes or when a new installation instance is
detected.
Unless used as a claim in a signed software statement,
authorization servers MUST treat this field as
self-asserted by the client and MUST NOT make any trust decisions
based upon the value of this field alone.
</t>
<t hangText="software_version">
Version identifier for the software that comprises a client. The value of
this field is a string that is intended to be compared using string
equality matching. The value of the <spanx style="verb">software_version</spanx>
SHOULD change on any update to the client software.
Unless used as a claim in a signed software statement,
authorization servers MUST treat this field as
self-asserted by the client and MUST NOT make any trust decisions
based upon the value of this field alone.
</t>
</list>
</t>
<section anchor="HumanReadableClientMetadata"
title="Human Readable Client Metadata">
<t>Human-readable client metadata values and client metadata values
that reference human-readable values MAY be represented in multiple
languages and scripts. For example, the values of fields such as
<spanx style="verb">client_name</spanx>, <spanx style="verb">tos_uri</spanx>,
<spanx style="verb">policy_uri</spanx>, <spanx style="verb">logo_uri</spanx>,
and <spanx style="verb">client_uri</spanx> might have multiple
locale-specific values in some client registrations.</t>
<t>To specify the languages and scripts, <xref
target="RFC5646">BCP47</xref> language tags are added to client
metadata member names, delimited by a # character. Since JSON member
names are case sensitive, it is RECOMMENDED that language tag values
used in Claim Names be spelled using the character case with which
they are registered in the <xref target="IANA.Language">IANA Language
Subtag Registry</xref>. In particular, normally language names are
spelled with lowercase characters, region names are spelled with
uppercase characters, and languages are spelled with mixed case
characters. However, since BCP47 language tag values are case
insensitive, implementations SHOULD interpret the language tag values
supplied in a case insensitive manner. Per the recommendations in
BCP47, language tag values used in metadata member names should only
be as specific as necessary. For instance, using <spanx style="verb">fr</spanx>
might be sufficient in many contexts, rather than <spanx style="verb">fr-CA</spanx>
or <spanx style="verb">fr-FR</spanx>.</t>
<t>For example, a client could represent its name in English as <spanx
style="verb">"client_name#en": "My Client"</spanx> and its name in
Japanese as <spanx style="verb">"client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"</spanx>
within the same registration request. The authorization server MAY
display any or all of these names to the resource owner during the
authorization step, choosing which name to display based on system
configuration, user preferences or other factors.</t>
<t>If any human-readable field is sent without a language tag, parties
using it MUST NOT make any assumptions about the language, character
set, or script of the string value, and the string value MUST be used
as-is wherever it is presented in a user interface. To facilitate
interoperability, it is RECOMMENDED that clients and servers use a
human-readable field without any language tags in addition to any
language-specific fields, and it is RECOMMENDED that any
human-readable fields sent without language tags contain values
suitable for display on a wide variety of systems.</t>
<t>Implementer's Note: Many JSON libraries make it possible to
reference members of a JSON object as members of an object construct
in the native programming environment of the library. However, while
the <spanx style="verb">#</spanx> character is a valid character
inside of a JSON object's member names, it is not a valid character
for use in an object member name in many programming environments.
Therefore, implementations will need to use alternative access forms
for these claims. For instance, in JavaScript, if one parses the JSON
as follows, <spanx style="verb">var j = JSON.parse(json);</spanx>,
then the member <spanx style="verb">client_name#en-us</spanx> can be
accessed using the JavaScript syntax <spanx style="verb">j["client_name#en-us"]</spanx>.</t>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<section title="OAuth Registration Client Metadata Registration" anchor="MetadataReg">
<t>
This specification registers the Client Metadata values defined in
<xref target="ClientMetadata"/> in the IANA
OAuth Registration Client Metadata registry
defined in <xref target="OAuth.Registration"/>.
</t>
<section title="Registry Contents" anchor="MetadataContents">
<t> <?rfc subcompact="yes"?>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">client_name</spanx>
</t>
<t>
Client Metadata Description:
Human-readable name of the client to be presented to the user
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">client_uri</spanx>
</t>
<t>
Client Metadata Description: URL of the homepage of the client
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">logo_uri</spanx>
</t>
<t>
Client Metadata Description:
URL that references a logo for the client
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">scope</spanx>
</t>
<t>
Client Metadata Description:
Space separated list of scope values
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">contacts</spanx>
</t>
<t>
Client Metadata Description:
Array of email addresses for people responsible for this client
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">tos_uri</spanx>
</t>
<t>
Client Metadata Description:
URL that points to a human-readable Terms of Service document for the client
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">policy_uri</spanx>
</t>
<t>
Client Metadata Description:
URL that points to a human-readable Policy document for the client
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">jwks_uri</spanx>
</t>
<t>
Client Metadata Description:
URL for the Client's <xref target="JWK">JSON Web Key Set</xref> document
representing the client's public keys
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">software_id</spanx>
</t>
<t>
Client Metadata Description:
Identifier for the software that comprises a client
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
<t>
<list style='symbols'>
<t>
Client Metadata Name: <spanx style="verb">software_version</spanx>
</t>
<t>
Client Metadata Description:
Version identifier for the software that comprises a client
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): [[ this document ]]
</t>
</list>
</t>
</section>
<?rfc subcompact="no"?>
</section>
</section>
<section anchor="Security" title="Security Considerations">
<t>
Unless used as a claim in a signed software statement,
the authorization server MUST treat all client metadata as
self-asserted. For instance, a rogue client might use the name and logo
for the legitimate client which it is trying to impersonate.
Additionally, a rogue client might try to use the software identifier or
software version of a legitimate client to attempt to associate itself
on the authorization server instances of the legitimate client. To
counteract this, an authorization server needs to take steps to mitigate
this phishing risk by looking at the entire registration request and
client configuration. For instance, an authorization server could warn
if the domain/site of the logo doesn't match the domain/site of redirect
URIs. An authorization server could also refuse registration from a
known software identifier that is requesting different redirect URIs or
a different client homepage URI. An authorization server can also
present warning messages to end users about dynamically registered
clients in all cases, especially if such clients have been recently
registered or have not been trusted by any users at the authorization
server before.
</t>
<t>In a situation where the authorization server is supporting open
client registration, it must be extremely careful with any URL provided
by the client that will be displayed to the user (e.g. <spanx
style="verb">logo_uri</spanx>, <spanx style="verb">tos_uri</spanx>,
<spanx style="verb">client_uri</spanx>, and <spanx style="verb">policy_uri</spanx>).
For instance, a rogue client could specify a registration request with a
reference to a drive-by download in the <spanx style="verb">policy_uri</spanx>.
The authorization server SHOULD check to see if the <spanx style="verb">logo_uri</spanx>,
<spanx style="verb">tos_uri</spanx>, <spanx style="verb">client_uri</spanx>,
and <spanx style="verb">policy_uri</spanx> have the same host and scheme
as the those defined in the array of <spanx style="verb">redirect_uris</spanx>
and that all of these resolve to valid web pages.</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.4122.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5646.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6749.xml'?>
<reference anchor="OAuth.Registration">
<front>
<title abbrev="OAuth Dynamic Registration Core">OAuth 2.0 Dynamic Client Registration Core Protocol</title>
<author fullname="Justin Richer" initials="J" surname="Richer">
<organization>The MITRE Corporation</organization>
<address>
<email>jricher@mitre.org</email>
</address>
</author>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization abbrev="Microsoft">Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization abbrev="Ping Identity">Ping Identity</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
</address>
</author>
<author fullname="Maciej Machulak" initials="M" surname="Machulak">
<organization>Newcastle University</organization>
<address>
<email>m.p.machulak@ncl.ac.uk</email>
<uri>http://ncl.ac.uk/</uri>
</address>
</author>
<author fullname="Phil Hunt" initials="P" surname="Hunt">
<organization>Oracle Corporation</organization>
<address>
<email>phil.hunt@yahoo.com</email>
</address>
</author>
<date day="6" month="February" year="2014"/>
</front>
<seriesInfo value="draft-ietf-oauth-dyn-reg" name="Internet-Draft"/>
<format target="http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg" type="HTML" />
</reference>
<reference anchor="JWK">
<front>
<title>JSON Web Key (JWK)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<date day="20" month="January" year="2014" />
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-jose-json-web-key"/>
<format target="http://tools.ietf.org/html/draft-ietf-jose-json-web-key"
type="HTML"/>
</reference>
<reference anchor="IANA.Language">
<front>
<title>Language Subtag Registry</title>
<author>
<organization>Internet Assigned Numbers Authority
(IANA)</organization>
</author>
<date year="2005"/>
</front>
<format target="http://www.iana.org/assignments/language-subtag-registry"
type="TXT"/>
</reference>
</references>
<section anchor="Acknowledgments" title="Acknowledgments">
<t>
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
versions of this document: Amanda Anganes, Derek Atkins, Tim Bray,
Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, George Fletcher,
Thomas Hardjono, Phil Hunt, William Kim, Torsten Lodderstedt, Eve Maler,
Josh Mandel, Nov Matake, Tony Nadalin, Nat Sakimura, Christian Scholz,
and Hannes Tschofenig.
</t>
</section>
<section anchor="OpenIssues" title="Open Issues">
<t>
<list style="symbols">
<t>
Should some or all of the metadata values defined in this specification
be moved into draft-ietf-oauth-dyn-reg?
</t>
</list>
</t>
</section>
<section anchor="History" title="Document History">
<t>[[ to be removed by the RFC editor before publication as an RFC ]]</t>
<t>
-00
<list style="symbols">
<t>
Created from draft-jones-oauth-dyn-reg-metadata-00.
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 01:09:47 |