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.

Table of Contents

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

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 (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.

1.2.  Terminology

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

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 (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.

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 Foundation, “OpenID Authentication 2.0,” December 2007.) [OpenID.2.0].

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 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.) [OpenID.Core].

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 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.) [OpenID.Core].

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 (Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0,” November 2005.) [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"
   }

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

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.

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.

9.  Privacy Considerations

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].

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.

10.  Security Considerations

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.

11.  References

11.1. Normative References

11.2. Informative References

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|
      +----+  +----------+  +--------------+ +----------+  +----------+

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). 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.

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

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.

Authors' Addresses