Final N. Sakimura NRI J. Bradley Ping Identity N. Agarwal Google E. Jay Illumila April 16, 2015 OpenID 2.0 to OpenID Connect Migration 1.0 Abstract 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. Sakimura, et al. [Page 1] OpenID 2.0 to OpenID Connect Migration April 2015 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Requesting the OpenID 2.0 Identifier and OpenID Connect Identifier Together . . . . . . . . . . . . . . . . . . . . . 4 3. Verification of the Relying Party by the OpenID Provider . . . 6 4. Returning the OpenID 2.0 Identifier . . . . . . . . . . . . . 7 4.1. Error Responses . . . . . . . . . . . . . . . . . . . . . 7 5. Verification of the ID Token . . . . . . . . . . . . . . . . . 8 6. Verification that the OpenID Connect OP is Authoritative . . . 9 7. Associating the Existing OpenID 2.0 Account with the OpenID Connect Identifier . . . . . . . . . . . . . . . . . . 11 8. Implementation Considerations . . . . . . . . . . . . . . . . 12 8.1. After End-Of-Life of the OpenID 2.0 OP . . . . . . . . . . 12 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 13 9.1. Correlation . . . . . . . . . . . . . . . . . . . . . . . 13 9.2. Identification by Other Parties . . . . . . . . . . . . . 13 9.3. Secondary Use . . . . . . . . . . . . . . . . . . . . . . 13 9.4. Disclosure . . . . . . . . . . . . . . . . . . . . . . . . 13 9.5. Exclusion . . . . . . . . . . . . . . . . . . . . . . . . 13 10. Security Considerations . . . . . . . . . . . . . . . . . . . 14 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 11.1. Normative References . . . . . . . . . . . . . . . . . . . 15 11.2. Informative References . . . . . . . . . . . . . . . . . . 15 Appendix A. Sequence Diagrams . . . . . . . . . . . . . . . . . . 16 Appendix B. Differences from Google's Migration Guide as of June 3, 2014 . . . . . . . . . . . . . . . . . . . . 17 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18 Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20 Sakimura, et al. [Page 2] OpenID 2.0 to OpenID Connect Migration April 2015 1. Introduction 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. 1.1. Requirements Notation and Conventions 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 [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". 1.2. Terminology The terms defined in OpenID Connect Core 1.0 [OpenID.Core] and OpenID Authentication 2.0 [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 Sakimura, et al. [Page 3] OpenID 2.0 to OpenID Connect Migration April 2015 2. Requesting the OpenID 2.0 Identifier and OpenID Connect Identifier Together 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 [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.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 [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 Sakimura, et al. [Page 4] OpenID 2.0 to OpenID Connect Migration April 2015 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. Sakimura, et al. [Page 5] OpenID 2.0 to OpenID Connect Migration April 2015 3. Verification of the Relying Party by the OpenID Provider 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.2.0]. Sakimura, et al. [Page 6] OpenID 2.0 to OpenID Connect Migration April 2015 4. Returning the OpenID 2.0 Identifier 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" } 4.1. Error Responses This specification does not define any additional Error Responses to augment those defined in OpenID Connect Core 1.0 [OpenID.Core]. Sakimura, et al. [Page 7] OpenID 2.0 to OpenID Connect Migration April 2015 5. Verification of the ID Token The RP MUST verify the ID Token as specified in 3.1.3.7 of OpenID Connect Core 1.0 [OpenID.Core]. Sakimura, et al. [Page 8] OpenID 2.0 to OpenID Connect Migration April 2015 6. Verification that the OpenID Connect OP is Authoritative 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: 1. 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. 2. 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. 3. If the "openid2_id" does not start with "http" or "https", it is an XRI [XRI_Syntax_2.0]. 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: 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" Sakimura, et al. [Page 9] OpenID 2.0 to OpenID Connect Migration April 2015 } 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 Sakimura, et al. [Page 10] OpenID 2.0 to OpenID Connect Migration April 2015 7. Associating the Existing OpenID 2.0 Account with the OpenID Connect Identifier 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. Sakimura, et al. [Page 11] OpenID 2.0 to OpenID Connect Migration April 2015 8. Implementation Considerations 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. 8.1. After End-Of-Life of the OpenID 2.0 OP 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. Sakimura, et al. [Page 12] OpenID 2.0 to OpenID Connect Migration April 2015 9. Privacy Considerations This section considers the Privacy Specific Threats described in Section 5.2 of RFC 6973 [RFC6973]. 9.1. Correlation 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. 9.2. Identification by Other Parties 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. 9.3. Secondary Use 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. 9.4. Disclosure 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. 9.5. Exclusion To avoid Exclusion in this case, make sure to ask the user if he wants the identifiers to be correlated. Sakimura, et al. [Page 13] OpenID 2.0 to OpenID Connect Migration April 2015 10. Security Considerations In addition to correctly implementing the usual OpenID Connect security measures, the RP MUST carefully follow and correctly implementing Section 6. If in doubt, skipping step 1 and just doing step 2 is safer. Sakimura, et al. [Page 14] OpenID 2.0 to OpenID Connect Migration April 2015 11. References 11.1. Normative References [OpenID.2.0] OpenID Foundation, "OpenID Authentication 2.0", December 2007. [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. [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. [XRI_Syntax_2.0] Reed, D. and D. McAlpin, "Extensible Resource Identifier (XRI) Syntax V2.0", November 2005. 11.2. Informative References [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. [Yadis] Miller, J., "Yadis Specification 1.0", March 2005. Sakimura, et al. [Page 15] OpenID 2.0 to OpenID Connect Migration April 2015 Appendix A. Sequence Diagrams 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| +----+ +----------+ +--------------+ +----------+ +----------+ Sakimura, et al. [Page 16] OpenID 2.0 to OpenID Connect Migration April 2015 Appendix B. Differences from Google's Migration Guide as of June 3, 2014 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 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 Google does not perform RP verification. 4. 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 [XRI_Syntax_2.0] while this standard does. 6. Verification that the OpenID Connect OP is Authoritative Google does not perform authority verification. Sakimura, et al. [Page 17] OpenID 2.0 to OpenID Connect Migration April 2015 Appendix C. Acknowledgements 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 Sakimura, et al. [Page 18] OpenID 2.0 to OpenID Connect Migration April 2015 Appendix D. Notices 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. Sakimura, et al. [Page 19] OpenID 2.0 to OpenID Connect Migration April 2015 Authors' Addresses 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 Google Email: naa@google.com URI: http://www.google.com Edmund Jay Illumila Email: ejay@illumi.la URI: http://illumi.la Sakimura, et al. [Page 20]