TOC |
|
This 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.
1.
Introduction
1.1.
Requirements Notation and Conventions
1.2.
Terminology
2.
Requesting the OpenID 2.0 Identifier and OpenID Connect Identifier Together
3.
Verification of the Relying Party by the OpenID Provider
4.
Returning the OpenID 2.0 Identifier
4.1.
Error Responses
5.
Verification of the ID Token
6.
Verification that the OpenID Connect OP is Authoritative
7.
Associating the Existing OpenID 2.0 Account with the OpenID Connect Identifier
8.
Implementation Considerations
8.1.
After End-Of-Life of the OpenID 2.0 OP
9.
Privacy Considerations
9.1.
Correlation
9.2.
Identification by Other Parties
9.3.
Secondary Use
9.4.
Disclosure
9.5.
Exclusion
10.
Security Considerations
11.
References
11.1.
Normative References
11.2.
Informative References
Appendix A.
Sequence Diagrams
Appendix B.
Differences from Google’s Migration Guide as of June 3, 2014
Appendix C.
Acknowledgements
Appendix D.
Notices
§
Authors' Addresses
TOC |
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.
TOC |
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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].
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.
TOC |
The terms defined in OpenID Connect Core 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.) [OpenID.Core] and OpenID Authentication 2.0 (OpenID Foundation, “OpenID Authentication 2.0,” December 2007.) [OpenID.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:
- OpenID 2.0 Identifier
- Verified Claimed Identifier as specified by OpenID Authentication 2.0.
- Connect OP
- OpenID Connect OP
- OpenID Connect Identifier
- OpenID Connect issuer and subject pair
TOC |
To obtain the OpenID 2.0 Identifier, the RP sends a modified OpenID Connect Authentication Request by adding openid2 as an additional scope value.
NOTE: If the OP does not support the openid2 scope, it SHOULD ignore it, as specified in Section 3.1.2.1 of OpenID Connect Core 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.) [OpenID.Core].
If a pairwise pseudonymous identifier (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.
- openid2_realm
- REQUIRED. The openid.realm value as defined in Section 9.1 of OpenID 2.0 (OpenID Foundation, “OpenID Authentication 2.0,” December 2007.) [OpenID.2.0]
If 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 (Miller, J., “Yadis Specification 1.0,” March 2005.) [Yadis]. In the Yadis case, it is using an Accept header with its value set to application/xml+xrds.
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.
GET /authorize?response_type=id_token &scope=openid%20openid2 &client_id=s6BhdRkqt3 &state=af0ifjsldkj &nonce=n-0S6_WzA2Mj &openid2_realm=https%3A%2F%2Fclient.example.org &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1 Host: server.example.com
The End-User performs authentication and authorization at the Connect OP which then returns the authentication response:
HTTP/1.1 302 Found Location: https://client.example.org/cb# id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IktleTAwMSJ9.ew0KIC Jpc3MiOiAiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLA0KICJzdW IiOiAiMjQ4Mjg5NzYxMDAxIiwNCiAiYXVkIjogInM2QmhkUmtxdDMiLA 0KICJub25jZSI6ICJuLTBTNl9XekEyTWoiLA0KICJleHAiOiAxMzExMj gxOTcwLA0KICJpYXQiOiAxMzExMjgwOTcwLA0KICJvcGVuaWQyX2lkIj ogImh0dHBzOi8vb3BlbmlkMi5leGFtcGxlLmNvbS91c2VyMzU5MzkwOD cyMTEyIg0KfQ.xSUAiR8OqhMIX3Gs8djq5ORwunLktRFBbDnb2EUY8hZ D3E7qk8518hOe7TVzC-VMCiq1o4KQrM_J0N-5MtiO2mvQ7j1I7iF-qgb KQMUe6Rt26Z1sA2uWs1223QBlUQ634BPiWrCYD6NfkofPTxsBwvzfMR1 0e2KVCdwpo33yJc5jelgqr26TymqhTFPiMiQhfXIA7lihzNq6cyxFHUY 541NiwVmsziUlgfV9ZKgADOYFimTc3-WsjEq_oPHF8WN9B_-dRTw0mT1 p6DjW0gqcGVJAag_T_Bb4uykizeyP_c8ghVRd3WCtF-kSZcbNn-WTLKw 5vO8I27_tneA6mBXeKw& state=af0ifjsldkj
The contents of the ID Token after decoding are:
{ "iss": "https://server.example.com", "sub": "248289761001", "aud": "s6BhdRkqt3", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "openid2_id": "https://openid2.example.com/user359390872112" }
To verify the issuer in the ID Token is authoritative for openid2_id, get the issuer from the OpenID 2.0 Identifier URI.
GET /user359390872112 HTTP/1.1 Host: openid2.example.com Accept: application/json HTTP/1.1 200 OK Content-Type: application/json { "iss": "https://server.example.com" }
Verify the value of iss claim of ID Token exactly matches the value of iss claim of this response.
TOC |
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 (OpenID Foundation, “OpenID Authentication 2.0,” December 2007.) [OpenID.2.0].
TOC |
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 ID Token with the following claim name:
- openid2_id
- OpenID 2.0 Identifier. It MUST be represented as a JSON string.
If the associated OpenID 2.0 Identifier for the user is not found, then the OP MUST NOT include this claim in the response.
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:
{ "iss": "https://server.example.com", "sub": "248289761001", "aud": "s6BhdRkqt3", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "openid2_id": "https://openid2.example.com/user359390872112" }
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 an XRI Identifier:
{ "iss": "https://server.example.com", "sub": "248289761001", "aud": "s6BhdRkqt3", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "openid2_id": "=!91F2.8153.F600.AE24" }
TOC |
This specification does not define any additional Error Responses to augment those defined in OpenID Connect Core 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.) [OpenID.Core].
TOC |
The RP MUST verify the ID Token as specified in 3.1.3.7 of OpenID Connect Core 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.) [OpenID.Core].
TOC |
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 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:
GET /user359390872112 HTTP/1.1 Host: openid2.example.com Accept: application/json HTTP /1.1 200 OK Content-Type: application/json { "iss": "https://server.example.com" }
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):
GET /=!91F2.8153.F600.AE24/(+openid_iss) HTTP/1.1 Host: xri.net HTTP/1.1 302 Moved Temporarily Location: http://forwarding.fullxri.com/forwarding/ =!91F2.8153.F600.AE24/(+openid_iss) GET /forwarding/=!91F2.8153.F600.AE24/(+openid_iss) HTTP/1.1 Host: forwarding.fullxri.com HTTP/1.1 302 Found Location: https://forwarding.fullxri.com/forwarding/ =!91F2.8153.F600.AE24/(+openid_iss) HTTP/1.1 302 Found Location: https://server.example.com/ GET / HTTP/1.1 Host: server.example.com HTTP /1.1 200 OK Content-Type: text/html
TOC |
Once the association between the 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.
TOC |
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 that 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.
TOC |
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.
TOC |
This section considers the Privacy Specific Threats described in Section 5.2 of RFC 6973 (Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, “Privacy Considerations for Internet Protocols,” July 2013.) [RFC6973].
TOC |
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 look 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, the OP MUST make sure that the user picks the intended identity.
TOC |
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.
TOC |
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.
TOC |
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.
TOC |
To avoid Exclusion in this case, make sure to ask the user if he wants the identifiers to be correlated.
TOC |
In addition to correctly implementing the usual OpenID Connect security measures, the RP MUST carefully follow and correctly implementing Section 6 (Verification that the OpenID Connect OP is Authoritative). If in doubt, skipping step 1 and just doing step 2 is safer.
TOC |
TOC |
[OpenID.2.0] | OpenID Foundation, “OpenID Authentication 2.0,” December 2007 (TXT, HTML). |
[OpenID.Core] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014. |
[RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
[RFC6749] | Hardt, D., “The OAuth 2.0 Authorization Framework,” RFC 6749, October 2012 (TXT). |
[XRI_Syntax_2.0] | Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0,” November 2005 (HTML, PDF). |
TOC |
[RFC6973] | Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, “Privacy Considerations for Internet Protocols,” RFC 6973, July 2013 (TXT). |
[Yadis] | Miller, J., “Yadis Specification 1.0,” March 2005. |
TOC |
Migration Sequence Diagram for Implicit Flow
+----+ +----------+ +--------------+ +----------+ +----------+ | UA | | RP | | Redirect URI | | AuthZ EP | |OpenID2URI| +-+--+ +----+-----+ +-----+--------+ +---+------+ +-----+----+ Click|AuthN Link| | | | +--------> | | | | |AuthN Req | | | | | <--------+ | | | | | AuthN Req | | | +---------------------------------------> | | +----+-----------------------------------------------------------------+ |OPT | | | AuthN Page | | | | +----+ | <---------------------------------------+ | | | | | Credential | | | | | +---------------------------------------> | | | +----------------------------------------------------------------------+ | |302 to Redirect URI | | | <------------------------+--------------+ | | |ID Token | | | +------------------------> | | | | | |------+ | | | |Get OpenID2URI | | | | | |from ID Token | <----+ | | | | | GET w/Accept: application/json | | +----------------------------> | | | | iss in JSON | | | | <----------------------------+ | | | | | +-+--+ +----+-----+ +------+-------+ +----+-----+ +------+---+ | UA | | RP | | Redirect URI | | AuthZ EP | |OpenID2URI| +----+ +----------+ +--------------+ +----------+ +----------+
TOC |
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).
2 (Requesting the OpenID 2.0 Identifier and OpenID Connect Identifier Together). Requesting the OpenID 2.0 Identifier and OpenID Connect Identifier Together (Requesting the OpenID 2.0 Identifier and OpenID Connect Identifier Together)
Google uses openid.realm instead of openid2_realm. Since OpenID Connect uses param_name style names instead of param.name style and the name openid.realm might mislead users into thinking that it is a Connect parameter proper, it has been changed to openid2_realm.
Google uses the existence of the openid.realm parameter to switch the behavior at the Connect OP. The new scope value openid2 has been introduced in this spec to make it more explicit and semantically consistent that it is asking for a resource.
3 (Verification of the Relying Party by the OpenID Provider). Verification of the Relying Party by the OpenID Provider (Verification of the Relying Party by the OpenID Provider)
Google does not perform RP verification.
4 (Returning the OpenID 2.0 Identifier). Returning the OpenID 2.0 Identifier (Returning the OpenID 2.0 Identifier)
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 (Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0,” November 2005.) [XRI_Syntax_2.0] while this standard does.
6 (Verification that the OpenID Connect OP is Authoritative). Verification that the OpenID Connect OP is Authoritative (Verification that the OpenID Connect OP is Authoritative)
Google does not perform authority verification.
TOC |
In addition to the authors, the OpenID Community would like to thank the following people for their contributions to this specification:
Allan Foster (allan.foster@forgerock.com), ForgeRock
Breno de Medeiros (breno@google.com), Google
Chuck Mortimore (cmortimore@salesforce.com), Salesforce
James Manger (James.H.Manger@team.telstra.com), Telstra
Justin Richer (jricher@mitre.org), MITRE Corporation
Michael B. Jones (mbj@microsoft.com), Microsoft
Nov Matake (nov@matake.jp), Independent
Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc.
Torsten Lodderstedt (torsten@lodderstedt.net), Deutsche Telekom
TOC |
Copyright (c) 2015 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.
TOC |
Nat Sakimura | |
Nomura Research Institute, Ltd. | |
Email: | n-sakimura@nri.co.jp |
URI: | http://nat.sakimura.org/ |
John Bradley | |
Ping Identity | |
Email: | ve7jtb@ve7jtb.com |
URI: | http://www.thread-safe.com/ |
Naveen Agarwal | |
Email: | naa@google.com |
URI: | http://www.google.com |
Edmund Jay | |
Illumila | |
Email: | ejay@illumi.la |
URI: | http://illumi.la |