OpenID Connect
Session Management 1.0 - draft 23

Abstract

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0
protocol. It enables 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
REST-like manner.

This document describes how to manage sessions for OpenID Connect,
including when to log out the End-User.

1.
Introduction

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0
[RFC6749] (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.)
protocol. It enables 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
REST-like manner.

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.

Continuous period of time during which an End-User
accesses a Relying Party relying on the Authentication
of the End-User performed by the OpenID Provider.

IMPORTANT NOTE TO READERS: The terminology definitions in
this section are a normative portion of this specification,
imposing requirements upon implementations. All the
capitalized words in the text of this specification, such as
"Session", reference these defined terms.
Whenever the reader encounters them, their definitions
found in this section must be followed.

2.1.
OpenID Provider Discovery Metadata

These OpenID Provider Metadata parameters MUST be included in
the Server's discovery responses
when Session Management and Discovery are supported:

check_session_iframe

REQUIRED.
URL of an OP iframe that supports 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
uses postMessage to post back the login status of the End-User at the OP.

end_session_endpoint

REQUIRED.
URL at the OP to which an RP can perform a redirect to request that the
End-User be logged out at the OP.

Session State.
JSON string that represents the End-User's login state
at the OP.
It MUST NOT contain the space (" ") character.
This value is opaque to the RP.
This is REQUIRED if session management is supported.

The Session State value is initially calculated on the server.
The same Session State value is also recalculated by the OP iframe in the browser client.
The generation of suitable Session State values is specified in Section 4.2 (OP iframe),
and is based on a salted cryptographic hash of Client ID, origin URL, and OP browser state.
For the origin URL, the server can use the origin URL of the Authentication Response,
following the algorithm specified in Section 4 of RFC 6454 (Barth, A., “The Web Origin Concept,” December 2011.) [RFC6454].

4.
Session Status Change Notification

An ID Token typically comes with an expiration date. The RP MAY rely on it
to expire the RP session. However, it is entirely possible that the End-User
might have logged out of the OP before the expiration date. Therefore, it is
highly desirable to be able to find out the login status of the End-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 becoming increasingly
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
a hidden OP iframe from an RP iframe with an origin restricted postMessage
as follows.

4.1.
RP iframe

The RP loads an invisible iframe from itself.
This iframe MUST know the ID of the OP iframe,
as described in Section 4.2 (OP iframe), so that it can
postMessage to the OP iframe.

The RP iframe polls the OP iframe with postMessage at an interval
suitable for the RP application. With each postMessage, it sends the
session state defined in Section 4.2 (OP iframe).

The postMessage from the RP iframe delivers the
following concatenation as the data:

Client ID + " " + Session State

It also has to be able to
receive the postMessage back from the OP iframe. The received data
will either be changed or
unchanged
unless the syntax of the message sent was determined by the OP to be malformed,
in which case the received data will be error.
Upon receipt of
changed, the RP MUST perform re-authentication with
prompt=none to obtain the current
session state at the OP.
Upon receipt of
error, the RP MUST NOT perform re-authentication
with prompt=none, so as to not cause potential
infinite loops that generate network traffic to the OP.

When the RP detects a session state change, it SHOULD first
try a prompt=none request
within an iframe to obtain a
new ID Token and session state, sending the old ID Token as
the id_token_hint.
If the RP receives an ID token for the same End-User, it SHOULD
simply update the value of the session state. If it doesn't
receive an ID token or receives an ID token for another
End-User, then it needs to handle this case as a logout for the
original End-User.

Note that the session state is origin bound.
Session state SHOULD be returned upon an authentication failure.

4.2.
OP iframe

The RP also loads an invisible OP iframe into itself from the OP's
check_session_iframe.

The RP MUST assign an id attribute to the iframe so that it can
address it, as described above.

The OP iframe MUST enforce that the caller has the same
origin as its parent frame. It MUST reject postMessage
requests from any other source origin.

As specified in Section 4.1 (RP iframe),
the postMessage from the RP iframe delivers the
following concatenation as the data:

Client ID + " " + Session State

The OP iframe has access to Browser state at the OP (in a
cookie or in HTML5 storage) that it uses to calculate and
compare with the OP session state that was passed by the RP.

The OP iframe MUST recalculate it from the previously
obtained Client ID, the source origin URL (from the
postMessage), and the current OP Browser state.
If the postMessage received is syntactically malformed in such a way
that the posted Client ID and origin URL cannot be determined
or are syntactically invalid, then the OP iframe SHOULD
postMessage the string error back to the source.
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.

The OP browser state is typically going to be stored in a
cookie or HTML5 local storage. It is origin bound to the
Authorization Server. It captures meaningful events such as
logins, logouts, change of user,
change of authentication status for Clients being used by the End-User,
etc. Thus, the OP SHOULD
update the value of the browser state in response to such
meaningful events. As a result, the next call to
check_session() after such an event will return the
value changed.
It is RECOMMENDED that the OP not update
the browser state too frequently in the absence of
meaningful events so as to spare excessive network traffic
at the Client in response to spurious changed events.

The computation of the session state returned in response to
unsuccessful Authentication Requests SHOULD, in addition to
the browser state, incorporate sufficient randomness in the
form of a salt so as to prevent identification of an End-User
across successive calls to the OP's Authorization Endpoint.

In the case of an authorized Client (successful
Authentication Response), the OP SHOULD change the value of
the session state returned to the Client under one of the
following events:

The set of users authenticated to the browser changes
(login, logout, session add).

The authentication status of Clients being used by the End-User changes.

In addition, the browser state used to verify the session state
SHOULD change with such events.
Calls to check_session() will return changed
against earlier versions of session state after such events.
It is RECOMMENDED that the browser state SHOULD NOT vary too
frequently in the absence of such events to minimize network
traffic caused by the Client's response to changed
notifications.

In the case of an unsuccessful Authentication Request, the
value of the session state returned SHOULD vary with each
request. However, the browser session state need not change
unless a meaningful event happens. In particular, many
values of session state can be simultaneously valid, for
instance by the introduction of random salt in the session
states issued in response to unsuccessful Authentication Requests.

If a cookie is used to maintain the OP browser state,
the HttpOnly flag likely can't be set for this cookie,
because it needs to be accessed from JavaScript.
Therefore, information that can be used for identifying the user
should not be put into the cookie, as it could be read by unrelated JavaScript.

In some implementations, changed
notifications will occur only when changes to the End-User's
session occur, whereas in other implementations, they might
also occur as a result of changes to other sessions between
the User Agent and the OP.
RPs need to be prepared for either eventuality,
silently handling any false positives that might occur.

5.
RP-Initiated Logout

An RP can notify the OP that the End-User has logged
out of the site, and might want to log out of the OP as well. In this
case, the RP, after having logged the End-User out of the RP,
redirects the End-User's User Agent to the OP's logout endpoint URL.
This URL is normally obtained via the
end_session_endpoint element of the OP's
Discovery response, or may be learned via other mechanisms.

This specification also defines the following parameters
that are passed as query parameters in the logout request:

id_token_hint

RECOMMENDED.
Previously issued ID Token passed to the logout endpoint
as a hint about the End-User's current authenticated
session with the Client.
This is used as an indication of the identity of the
End-User that the RP is requesting be logged out by the OP.
The OP need not be listed as an
audience of the ID Token when it is used as an
id_token_hint value.

post_logout_redirect_uri

OPTIONAL.
URL to which the RP is requesting that
the End-User's User Agent be redirected
after a logout has been performed.
The value MUST have been previously registered with the OP,
either using the post_logout_redirect_uris
Registration parameter or via another mechanism.
If supplied, the OP SHOULD honor this request following the logout.

state

OPTIONAL.
Opaque value used by the RP to maintain state between
the logout request and the callback to the endpoint specified by
the post_logout_redirect_uri parameter.
If included in the logout request, the OP passes this value back to the RP
using the state query parameter
when redirecting the User Agent back to the RP.

At the logout endpoint, the OP SHOULD ask the End-User whether
he wants to log out of the OP as well.
If the End-User says "yes", then the OP MUST log out the End-User.

6.
Validation

If any of the validation procedures defined in this specification fail, any operations requiring
the information that failed to correctly validate MUST be aborted and
the information that failed to validate MUST NOT be used.

7.
Implementation Considerations

This specification defines features used by both Relying Parties and
OpenID Providers that choose to implement Session Management.
All of these Relying Parties and OpenID Providers
MUST implement the features that are listed
in this specification as being "REQUIRED" or are described with a "MUST".
No other implementation considerations for implementations of
Session Management are defined by this specification.

8.
Security Considerations

The OP iframe MUST enforce that the caller has the same
origin as its parent frame. It MUST reject postMessage
requests from any other source origin,
to prevent cross-site scripting attacks.

The id_token_hint parameter to a logout request
can be used to determine which RP initiated the logout request.
Logout requests without a valid id_token_hint value
are a potential means of denial of service; therefore,
OPs may want to require explicit user confirmation before acting upon them.

Appendix B.
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.

Fixed #859 - Added IMPORTANT NOTE TO READERS about the terminology
definitions being a normative part of the specification.

-14

Clarified RP-initiated logout description.

Added an id_token_hint parameter to logout requests.

Stated that RPs should gracefully any false positive
changed notifications that may occur.

-13

Added OpenID Connect Working Group declaration to the document metadata.

-12

Fixed #364 - Term "Session" not defined.

State that when any validations fail, any operations requiring
the information that failed to correctly validate MUST be aborted and
the information that failed to validate MUST NOT be used.

Fixed #779 - Parameters missing from IANA Considerations.

Fixed #782 - Changed uses of "_url" in identifiers to "_uri".

-11

Applied changes from October 24, 2012 editing session at the
Internet Identity Workshop (IIW).
This separates the session state from the ID Token,
adding the new session_state parameter
to the authorization response.
These identifiers also changed:
check_session_endpoint to
check_session_iframe_url and
end_session_endpoint to
end_session_endpoint_url.

Fixed #605 - op_logout_url description.

Added Implementation Considerations section.

Fixed #698 - Inconsistent use of articles.

Naming consistency changes. Renamed
check_session_iframe_url to
check_session_iframe and
end_session_endpoint_url back to
end_session_endpoint.