OpenID 2.0 to
OpenID Connect Migration 1.0 - draft 06Nomura Research Institute,
Ltd.n-sakimura@nri.co.jphttp://nat.sakimura.org/Ping Identityve7jtb@ve7jtb.comhttp://www.thread-safe.com/Googlenaa@google.comhttp://www.google.comIllumilaejay@illumi.lahttp://illumi.laOpenID Connect Working GroupThis specification defines how an OpenID Authentication 2.0 relying
party can migrate the user from OpenID 2.0 identifier to OpenID Connect
Identifier by using an ID Token that includes the OpenID 2.0 verified
claimed ID. In this specification, the method to request such an
additional claim and the method for the verification of the resulting ID
Token is specified.OpenID Authentication 2.0 is a popular authentication federation
protocol through which the relying party can obtain the user’s
verified identifier from the OpenID Provider (OP) to which the user was
authenticated. OpenID Connect is a new version of OpenID Authentication but the
identifier format is different and thus relying parties need to migrate
those user identifiers to continue serving these users.In this specification, a standard method for this kind of migration
on a per-user basis is described.The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.In the .txt version of this document, values are quoted to indicate
that they are to be taken literally. When using these values in
protocol messages, the quotes MUST NOT be used as part of the value.
In the HTML version of this document, values to be taken literally are
indicated by the use of this fixed-width font.The terms defined in OpenID Connect Core 1.0 and OpenID Authentication 2.0 are used by this
specification. When the same term is defined in both specifications,
the term defined in OpenID Connect Core takes precedence.This specification also defines the following terms: Verified Claimed
Identifier as specified by OpenID Authentication 2.0. OpenID Connect OP OpenID Connect issuer and subject pairTo obtain the OpenID 2.0 Identifier, the RP sends a modified OpenID
Connect Authentication Request by adding openid2
as an additional scope value.If PPID was used to obtain the OpenID 2.0 Identifier,
openid.realm
has to be sent to the OP with the request. For this purpose, a new
authentication request parameter openid2_realm
is defined.OPTIONAL. The openid.realm value as defined in Section 9.1 of
OpenID 2.0If the authority section of Authorization Endpoint URI is
different from the authority section of the OpenID 2.0 OP’s OP
Endpoint URL, the client MUST issue a GET request to the OpenID 2.0
Identifier obtained through the ID Token, i.e., the value of
openid2_id, with
an Accept header set to application/json
to obtain the value of
iss claim in it.
The value of the iss claim
obtained this way and the value of
the iss
claim in the ID Token MUST exactly match.
NOTE: This is similar to Yadis.
In the Yadis case, it is using an Accept header with
its value set to application/xml+xrds.NOTE: If the value of openid2_id is an
XRI, the mechanism for verifying the
iss in the ID Token is still TBD.
This may involve work by xri.net or individual i-Brokers.The following is a non-normative example of an
authentication request to request the OpenID 2.0 Identifier (with line
wraps within values for display purposes only).
NOTE: This example assumes that the OpenID 2.0 OP Identifier
is https://openid2.example.com.
The End-User performs authentication and
authorization at the Connect OP which then returns
the authentication response:
The contents of the ID Token
after decoding are:
To verify the issuer in the ID Token is
authoritative for openid2_id, get the issuer from
the OpenID 2.0 Identifier URI.
Verify the value of iss claim of ID Token
exactly matches the value of iss claim of this response.
There could be an attack by a malicious RP to obtain the user’s
PPID for another RP to perform identity correlation. To mitigate the
risk, the OP MUST verify that the realm and RP’s Redirect URI
matches as per Section 9.2 of OpenID
2.0.If the verification of the Relying Party was successful and an
associated OpenID 2.0 Identifier for the user is found, then the OP MUST
include the OpenID 2.0 Identifier in the asymmetrically signed ID Token
with the following claim name: REQUIRED. OpenID 2.0 Identifier.
It MUST be represented as a JSON string.The following is a non-normative example of ID Token claims with
an OpenID 2.0 Identifier claim (with line wraps within values for
display purposes only) whose value is a URL:The following is a non-normative examples of ID Token claims with
an OpenID 2.0 Identifier claim (with line wraps within values for
display purposes only) whose value is an XRI Identifier:In addition to the error conditions defined in OpenID Connect Core 1.0, the following error
conditions are defined in this standard.If the openid2 scope is not supported, the error invalid_scope as defined in 4.1.2.1 of OAuth SHOULD be returned.If a corresponding OpenID 2.0 Identifier is not found for the
authenticated user, the openid2_id claim
in the ID Token MUST have the value NOT FOUND.NOTE: Even if the openid2_id claim
value is NOT FOUND, the overall ID Token
can still be valid.The RP MUST verify the ID Token as specified in 3.1.3.7 of OpenID Connect Core 1.0. A malicious OP may try to impersonate the user by returning the
OpenID 2.0 Identifier that it is not authoritative for. Therefore,
verifying that the Connect OP is indeed authoritative for the OpenID 2.0
Identifier is imperative. To verify that the Connect OP is
authoritative for the OpenID 2.0 Identifier,
the RP MUST verify that one of the following
verification rules hold:If the RP a priori knows that the authority hosted only one
OpenID 2.0 OP and OpenID Connect OP each, the authority section of
Authorization Endpoint URI is the same as the authority section of
the OpenID 2.0 OP’s OP Endpoint URL.If they are not (or when a higher confidence is sought), RP MUST
make a GET call to the obtained verified claimed ID with an Accept
header set to application/json.
The server SHOULD return a JSON with iss
as its top level member.
The value of this member MUST exactly match the
iss
in the ID Token.
If the openid2_id does not start
with http or https, it is an
XRI.
In this case, the RP needs to construct the
verification URI by concatenating
https://xri.net/,
the value of the
openid2_id claim, and
/(+openid_iss).
Requesting the resulting URI with GET will
result in a series of HTTP 302 redirects.
The RP MUST follow the redirects until
HTTP status code 200 OK
comes back. The URI that resulted in
200 OK is the
authoritative issuer for the XRI.
This URI MUST exactly match the
iss
in the ID Token except for the potential trailing
slash (/) character.
If all three fail, the verification has failed and the RP MUST NOT accept the
OpenID 2.0 Identifier.NOTE: XRI users may need to configure the forwarding service
and define (+openid_iss) themselves.
The following is a non-normative example of obtaining
the authoritative issuer from
an OpenID 2.0 Identifier URI:
The following is a non-normative example of obtaining
the authoritative issuer from an OpenID 2.0 Identifier XRI
(with line wraps within values for display purposes only):
As the association between OpenID Connect Identifier and
OpenID 2.0 Identifier has been
verified, the RP SHOULD associate the existing OpenID 2.0 account with
the OpenID Connect account.NOTE: At some point in the future, the
OpenID Connect server may drop the support for openid2
scope. In this case, the OP will return the invalid_scope
in the error as defined in .There are OpenID 2.0 libraries that use openid.identity
instead of openid.claimed_id to link to the user account at
the RP. This is a bug as openid.identity may be recycled.
However, there are not many OpenID 2.0 providers who use different values for
openid.identity and openid.claimed_id.
Yahoo! and Yahoo! Japan seem to be the only large scale providers that fall under this
category. In their case, by stripping out the fragment from the
openid.claimed_id, you can get
openid.identity. For implementations that are using these
buggy OpenID 2.0 libraries, they can adopt this strategy to link Yahoo! and Yahoo! Japan
users to their local accounts.This standard allows the RP to verify the authenticity of the
OpenID 2.0 Identifier through ID Token even after the OpenID 2.0 OP is
taken down. To enable this, the OP MUST publish the public keys that
were used to sign the ID Token with openid2_id
claim at the URI that this OpenID 2.0 Identifier points to.NOTE: The OpenID 2.0 Identifiers can be mapped to a static file
containing the keys, so maintaining such can require minimal overhead
compared to maintaining the full OpenID 2.0 OP.This section considers the Privacy Specific Threats described in
Section 5.2 of RFC 6973.This standard essentially is a correlation specification. It
correlates the OpenID Connect identifier with OpenID 2.0 Identifier.
In the usual case where the user has only one account and the Connect
and OpenID 2.0 OPs look similar, then the user probably would be
expecting that those identifiers to be correlated silently. However,
if the OPs looks very different, then some users may prefer not to be
correlated. As such, the OP SHOULD make sure that to ask the user if
the user wants to correlate.When multiple accounts are available for the user, then the OP MUST
make sure that the user picks the intended identity.Since the channel is encrypted, this risk is low. If the channel
was vulnerable, then user identifiers and other attributes will be
exposed and thus allows the attacker to identify the user. To avoid
it, the parties can employ ID Token encryption as well.While there is no technical control in this standard as to the
secondary use is concerned, RP is strongly advised to announce its
policy against secondary use in its privacy policy. Secondary use
usually is associated with privacy impact, so its legitimacy should be
carefully evaluated.Since the channel is encrypted, this risk is low. If the channel
was vulnerable, then user identifiers and other attributes will be
exposed and thus allows the attacker to identify the user. To avoid
it, the parties can employ ID Token encryption as well.To avoid Exclusion in this case, make sure to ask the user if he
wants the identifiers to be correlated.In addition to correctly implementing the usual OpenID Connect
security measures, the RP MUST carefully follow and correctly
implementing . If in doubt, skipping step 1 and just doing step
2 is safer.OpenID Connect Core 1.0Nomura Research Institute,
Ltd.Ping IdentityMicrosoftGoogleSalesforceOpenID Authentication 2.0OpenID FoundationExtensible Resource Identifier (XRI) Syntax V2.0Yadis Specification 1.0NetMeshMigration Sequence Diagram for Implicit Flow | | | |
|AuthN Req | | | |
| <--------+ | | |
| | AuthN Req | | |
+---------------------------------------> | |
+----+-----------------------------------------------------------------+
|OPT | | | AuthN Page | | | |
+----+ | <---------------------------------------+ | |
| | | Credential | | | |
| +---------------------------------------> | | |
+----------------------------------------------------------------------+
| |302 to RedirectURI | |
| <------------------------+--------------+ |
| |ID Token | | |
+------------------------> | | |
| | |------+ | |
| |Get OpenID2URI | | | |
| |from ID Token | <----+ | |
| | | GET w/Accept: application/json
| | +----------------------------> |
| | | iss in JSON |
| | | <----------------------------+
| | | | |
+-+--+ +----+-----+ +------+-------+ +----+-----+ +------+---+
| UA | | RP | | Redirect URI | | AuthZ EP | |OpenID2URI|
+----+ +----------+ +--------------+ +----------+ +----------+
]]>In this appendix, the differences between this spec and
Google’s migration guide as of June 3, 2014 are explained. The
differences are categorized in accordance with the section number of
this specification. Google's migration guide is available at
Migrating to OAuth 2.0 login (OpenID Connect)
.
.
Google uses openid.realm instead. Since
OpenID Connect uses param_name style instead of param.name,
as well as the name openid.realm may mislead
the user that it is a Connect parameter proper, it has been changed to
openid2_realm.Google uses the existence of
openid.realm parameter to switch the
behavior at the Connect OP. New scope value openid2
has been introduced in this spec to make it more explicit and
semantically in-line that it is asking for a resource..
Google does not perform RP verification..
Google uses the claim name openid_id instead of openid2_id . It was changed to openid2_id
because openid_id may cause confusion among
people that it is the Connect identifier. Since this spec allows
providing openid2_id even after the OpenID
2.0 OP has been taken down, this claim may persists much longer than the
OpenID 2.0 OP. Thus, the chance of confusion should be minimized. Google does not take care of XRI
while this standard does..
Google does not perform authority verification.In addition to the authors, the OpenID Community would like to thank
the following people for their contributions to this specification:Breno de Medeiros (breno@google.com), GoogleRyo Ito (ryo.ito@mixi.co.jp), mixi, Inc.Michael B. Jones (mbj@microsoft.com), MicrosoftNov Matake (nov@matake.jp), IndependentAllan Foster (allan.foster@forgerock.com), ForgeRockChuck Mortimore (cmortimore@salesforce.com), SalesforceTorsten Lodderstedt (torsten@lodderstedt.net), Deutsche TelekomJustin Richer (jricher@mitre.org), MITRE CorporationCopyright (c) 2014 The OpenID Foundation.The OpenID Foundation (OIDF) grants to any Contributor, developer,
implementer, or other interested party a non-exclusive, royalty free,
worldwide copyright license to reproduce, prepare derivative works from,
distribute, perform and display, this Implementers Draft or Final
Specification solely for the purposes of (i) developing specifications,
and (ii) implementing Implementers Drafts and Final Specifications based
on such documents, provided that attribution be made to the OIDF as the
source of the material, but that such attribution does not indicate an
endorsement by the OIDF.The technology described in this specification was made available
from contributions from various sources, including members of the OpenID
Foundation and others. Although the OpenID Foundation has taken steps to
help ensure that the technology is available for distribution, it takes
no position regarding the validity or scope of any intellectual property
or other rights that might be claimed to pertain to the implementation
or use of the technology described in this specification or the extent
to which any license under such rights might or might not be available;
neither does it represent that it has made any independent effort to
identify any such rights. The OpenID Foundation and the contributors to
this specification make no (and hereby expressly disclaim any)
warranties (express, implied, or otherwise), including implied
warranties of merchantability, non-infringement, fitness for a
particular purpose, or title, related to this specification, and the
entire risk as to implementing this specification is assumed by the
implementer. The OpenID Intellectual Property Rights policy requires
contributors to offer a patent promise not to assert certain patent
claims against other contributors and against implementers. The OpenID
Foundation invites any interested party to bring to its attention any
copyrights, patents, patent applications, or other proprietary rights
that may cover technology that may be required to practice this
specification.[[ To be removed from the final version ]]
-06
Added XRI 2.0 reference.
Changed text from Resource to RP in Appendix A diagram.
Corrected definition of OpenID 2.0 Identifier.
Added Document History.
Fixed #954 - Added "NOT RECOMMENDED" to the list of RFC 2119 terms.
Use XRI forwarding of /(+openid_iss)
to obtain the OpenID Connect issuer.
-05
Implementer’s Draft release candidate