OpenID Connect Session Management 1.0 - draft 10

Abstract

NOTE: This is a first cut of a significant rewrite based on the decisions made at the May 5, 2012 working group meeting.

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and RESTful manner.

This document describes how to manage sessions for OpenID Connect.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
    1.2.  Terminology
2.  Endpoint Discovery
3.  Creating and Updating Sessions
4.  Session status change notification
    4.1.  OP iframe
    4.2.  RP iframe
5.  RP initiated Logout
6.  IANA Considerations
7.  Security Considerations
8.  Normative References
Appendix A.  Acknowledgements
Appendix B.  Notices
Appendix C.  Document History
§  Authors' Addresses

1.  Introduction

While OpenID Connect Messages and Standard defines the method to login the user to the RP based on the ID token, it does not talk about how to continuously monitor the user's login status at the OP so that the RP may logout the user once the user has logged out of the OP. This specification defines the method to achieve this.

1.1.  Requirements Notation and Conventions

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

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

1.2.  Terminology

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", and "Token Endpoint" defined by OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], and the terms defined by OpenID Connect Messages 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” December 2012.) [OpenID.Messages].

2.  Endpoint Discovery

To support the OpenID Connect session management, the RP MUST obtain the session management related endpoint URLs. This can either be obtained out of band or through the OP configuration file as described in OpenID Connect Discovery.

The OP endpoints defined in this specification are as follows:

check_session_endpoint

URL of an OP endpoint that provides a page to support cross-origin communications for session state information with the RP client, using the HTML5 postMessage API. The page is loaded from an invisible iframe embedded in an RP page so that it can run in the OP's security context. It accepts postMessage requests from the relevant RP iframe and postMessage back the login status of the user at the OP.

end_session_endpoint

The URL that initiates the user logout at the OP.

The RP endpoints defined in this specification are as follows:

3.  Creating and Updating Sessions

In OpenID Connect, the session at the RP typically starts when the RP validates the user's ID Token. Refer to OpenID Connect Standard to find out how to obtain an ID Token and validate it. Typically, when the RP has enough knowledge on the user's identity, the RP sends the authentication request with previously obtained ID Token as the user hint with prompt=none.

This specification defines one additional claim in the ID Token.

ops

OP Session Status. A JSON string that represents the user's login state at the OP. This string is opaque to the RP. REQUIRED if session management is supported.

4.  Session status change notification

ID Token typically comes with the expiry date. The RP MAY rely on it to expire the RP session. However, it is entirely possible that the user may have logged out of the OP before the expiry date. Therefore, it is highly desirable to be able to find out the login status of the user at the OP.

To do so, it is possible to repeat the authentication request with prompt=none. However, this causes network traffic and this is problematic on the mobile devices that are increasingly becoming popular. Therefore, once the session is established with the authentication request and response, it is desirable to be able to check the login status at the OP without causing network traffic by polling the hidden OP iframe from a RP iframe with origin restricted postMessage as follows.

4.1.  OP iframe

The RP typically loads an invisible OP iframe in the page from the OP's check_session_endpoint with the following parameters.

id_token_hint

REQUIRED. ID Token that the RP received when it logged in the user. The value of the aud field, which contains a client_id of the RP, is used to set the source origin for the postMessage request. Note: If the ID Token was asymmetrically encrypted for the RP, then the RP MUST decrypt it and use the decrypted version of the ID Token in this field.

The RP MUST assign an id attribute to the iframe so that it can address it later.

The OP iframe MUST accept the postMessage from the source origin that was registered with the client. It MUST reject the postMessage request from other source origin.

The postMessage from the RP iframe delivers session state, the concatenation of the following, as the data:

1. SHA-256 hash of the concatenation of the Client ID, the source origin URL, the OP session state, and a salt, which is 128 bits or more,
2. an ASCII period ('.') character, i.e., 0x2E,
3. the salt.

The OP iframe MUST recalculate it from the previously obtained Client ID, the source origin URL, the current OP session state, and the salt obtained from the data. If the received value and the calculated value do not match, then the OP iframe MUST postMessage the string changed back to the source. If it matched, then it MUST postMessage the string unchanged.

Following is a non-normative example pseudo code for the OP iframe.

window.addEventListener("message",receiveMessage, false);
function receiveMessage(e){
  if ( e.origin !== "http://client.example.net" ) {
    return;
  }
  var stat;
  var opss = get_op_session_state();
  var ss = CryptoJS.SHA256(client_id + origin + opss + salt) + "." + salt;
  if (e.data == ss) {
    stat = 'unchanged';
  } else [
    stat = 'changed';
  }
  e.source.postMessage(stat, e.origin);
};

4.2.  RP iframe

The RP also loads an invisible iframe from itself in the same page. This iframe MUST know the id of the OP iframe so that it can postMessage to the OP iframe.

RP iframe polls OP iframe with postMessage with certain interval suitable for the RP application. With each postMessage, it sends the session state defined in Section 4.1. It also has to be able to receive the postMessage back from the OP iframe. The received data would either be changed or unchanged. Upon receipt of changed, the RP MUST perform the re-authentication with prompt=none to find the current session state at the OP.

Following is a non-normative example pseudo code for the RP iframe.

var stat = "unchanged";
var mes = CryptoJS.SHA256(client_id + origin + opss + salt) + "." + salt;

function check_session()
{
  var targetOrigin  = "http://server.example.com";
  var win = window.parent.document.getElementById("op").contentWindow;
  win.postMessage( mes, targetOrigin);

}
function setTimer()
{
  check_session();
  timerID = setInterval("check_session()",3*1000);
}

window.addEventListener("message", receiveMessage, false);

function receiveMessage(e)
{
  var targetOrigin  = "http://server.example.com";
  if (e.origin !== targetOrigin ) {return;}
  stat = e.data;
}

5.  RP initiated Logout

Sometimes, the RP may want to notify the OP that the user has logged out of the site, and he may want to logout of the OP as well. In this case, the RP, after having logged out the user, sends the user to the OP's logout endpoint URL that is either advertised through OP's provider configuration information or via out of band knowledge.

Upon receipt of such message, the OP SHOULD prompt the user whether he wants to logout of the OP as well. If the user says "yes", then the OP MUST log him out.

6.  IANA Considerations

This document makes no requests of IANA.

7.  Security Considerations

TBD

8. Normative References

Appendix A.  Acknowledgements

Breno de Medeiros, Naveen Agarwal, George Fletcher, Torsten Lodderstedt, Axel Nennker, Amanda Anganes, Justin Richer, Tony Nadalin, Edmund Jay, Michael B. Jones, John Bradley, and Nat Sakimura contributed to the design of this specification.

Appendix B.  Notices

Copyright (c) 2012 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.

Appendix C.  Document History

[[ To be removed from the final specification ]]

-10

• Fixed #689 - Track JWT change that allows JWTs to have multiple audiences.

-09

• Changed user_hint to id_token_hint for consistency with Messages.
• Fixed #666 - JWS signature validation vs. verification.
• Referenced OAuth 2.0 RFC -- RFC 6749.

-08

• Complete rewrite based on the decisions made at the May 5, 2012 face to face working group meeting.

-07

• Added warning about the significant revisions planned to session management to the abstract and introduction.
• Changed client.example.com to client.example.org, per issue #251
• Listed author of ISO29115 as "International Telecommunication Union and International Organization for Standardization", per issue #589
• Use standards track version of JSON Web Token spec (draft-ietf-oauth-json-web-token)

-06

• Updated Notices
• Updated References

-05

• Removed Check Session Endpoint
• Updated ID Token claims to reflect changes in Messages

-04

• Changes associated with renaming "Lite" to "Basic Client" and replacing "Core" and "Framework" with "Messages" and "Standard".
• Numerous cleanups, including updating references.

-03

• Corrected examples.

-02

• Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call.

-01

• Consistency and cleanup pass, including removing unused references.

-00

• Split from core when all optional features were removed.

Authors' Addresses