TOC 
DraftM. Jones
 Microsoft
 J. Bradley
 Ping Identity
 August 3, 2018


OpenID Connect Back-Channel Logout 1.0 - draft 05

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 specification defines a logout mechanism that uses direct back-channel communication between the OP and RPs being logged out; this differs from front-channel logout mechanisms, which communicate logout requests from the OP to RPs via the User Agent.



Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
    1.2.  Terminology
2.  Back-Channel Logout
    2.1.  Indicating OP Support for Back-Channel Logout
    2.2.  Indicating RP Support for Back-Channel Logout
    2.3.  Remembering Logged-In RPs
    2.4.  Logout Token
    2.5.  Back-Channel Logout Request
    2.6.  Logout Token Validation
    2.7.  Back-Channel Logout Actions
    2.8.  Back-Channel Logout Response
3.  RP-Initiated Logout Functionality
4.  Security Considerations
5.  IANA Considerations
    5.1.  OAuth Dynamic Client Registration Metadata Registration
        5.1.1.  Registry Contents
6.  References
    6.1.  Normative References
    6.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Notices
Appendix C.  Document History
§  Authors' Addresses




 TOC 

1.  Introduction

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 [RFC6749] (Hardt, D., Ed., “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.

This specification defines a logout mechanism that uses direct back-channel communication between the OP and RPs being logged out; this differs from front-channel logout mechanisms, which communicate logout requests from the OP to RPs via the User Agent.

An upside of back-channel communication is that it can be more reliable than communication through the User Agent, since in the front-channel, the RP's browser session must be active for the communication to succeed. (If the RP's browser tab was subsequently used to navigate to an unrelated page, the RP session will be active unless the user uses the back button to return to it.) Both the OpenID Connect Session Management 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” January 2017.) [OpenID.Session] and OpenID Connect Front-Channel Logout 1.0 (Jones, M., “OpenID Connect Front-Channel Logout 1.0,” January 2017.) [OpenID.FrontChannel] specifications use front-channel communication, which communicate logout requests from the OP to RPs via the User Agent.

A downside of back-channel communication is that the session state maintained between the OP and RP over the front-channel, such as cookies and HTML5 local storage, are not available when using back-channel communication. As a result, all needed state must be explicitly communicated between the parties. Furthermore, RPs must implement an application-specific method of terminating RP sessions with the OP upon receiving back-channel logout requests; this can be more complicated than simply clearing cookies and HTML5 local storage state, which is often all that has to happen to implement logout in response to front-channel logout requests.

Another significant limitation of back-channel logout is that the RP's back-channel logout URI must be reachable from all the OPs used. This means, for instance, that the RP cannot be behind a firewall or NAT when used with public OPs.

This specification can be used separately from or in combination with OpenID Connect Session Management 1.0 and/or OpenID Connect Front-Channel Logout 1.0.



 TOC 

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 specification, 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 specification, values to be taken literally are indicated by the use of this fixed-width font.



 TOC 

1.2.  Terminology

This specification uses the terms "Authorization Server", "Client", "Client Identifier", and "Redirection URI" defined by OAuth 2.0 (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], the term "User Agent" defined by RFC 7230 (Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing,” June 2014.) [RFC7230], the terms "Session" and "Session ID" defined by OpenID Connect Front-Channel Logout 1.0 (Jones, M., “OpenID Connect Front-Channel Logout 1.0,” January 2017.) [OpenID.FrontChannel] and the terms defined by 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 JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2015.) [JWT].

This specification also defines the following term:

Logout Token
JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2015.) [JWT] similar to an ID Token that contains Claims about the logout action being requested.



 TOC 

2.  Back-Channel Logout



 TOC 

2.1.  Indicating OP Support for Back-Channel Logout

If the OpenID Provider supports OpenID Connect Discovery 1.0 (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” November 2014.) [OpenID.Discovery], it uses this metadata value to advertise its support for back-channel logout:

backchannel_logout_supported
OPTIONAL. Boolean value specifying whether the OP supports back-channel logout, with true indicating support. If omitted, the default value is false.

It SHOULD also register this related metadata value:

backchannel_logout_session_supported
OPTIONAL. Boolean value specifying whether the OP can pass a sid (session ID) Claim in the Logout Token to identify the RP session with the OP. If supported, the sid Claim is also included in ID Tokens issued by the OP. If omitted, the default value is false.



 TOC 

2.2.  Indicating RP Support for Back-Channel Logout

Relying Parties supporting back-channel-based logout register a back-channel logout URI with the OP as part of their client registration.

The back-channel logout URI MUST be an absolute URI as defined by Section 4.3 of [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.). The back-channel logout URI MAY include an application/x-www-form-urlencoded formatted query component, per Section 3.4 of [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.), which MUST be retained when adding additional query parameters. The back-channel logout URI MUST NOT include a fragment component.

If the RP supports OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” November 2014.) [OpenID.Registration], it uses this metadata value to register the back-channel logout URI:

backchannel_logout_uri
OPTIONAL. RP URL that will cause the RP to log itself out when sent a Logout Token by the OP.

It SHOULD also register this related metadata value:

backchannel_logout_session_required
OPTIONAL. Boolean value specifying whether the RP requires that a sid (session ID) Claim be included in the Logout Token to identify the RP session with the OP when the backchannel_logout_uri is used. If omitted, the default value is false.



 TOC 

2.3.  Remembering Logged-In RPs

OPs supporting back-channel logout need to keep track of the set of logged-in RPs so that they know what RPs to contact at their back-channel logout URIs to cause them to log out. Some OPs track this state using a "visited sites" cookie. OPs are encouraged to send logout requests to them in parallel.



 TOC 

2.4.  Logout Token

OPs send a JWT similar to an ID Token to RPs called a Logout Token to request that they log out. ID Tokens are defined in Section 2 of [OpenID.Core] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.).

The following Claims are used within the Logout Token:

iss
REQUIRED. Issuer Identifier, as specified in Section 2 of [OpenID.Core] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.).
sub
OPTIONAL. Subject Identifier, as specified in Section 2 of [OpenID.Core] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.).
aud
REQUIRED. Audience(s), as specified in Section 2 of [OpenID.Core] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.).
iat
REQUIRED. Issued at time, as specified in Section 2 of [OpenID.Core] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.).
jti
REQUIRED. Unique identifier for the token, as specified in Section 9 of [OpenID.Core] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.).
events
REQUIRED. Claim whose value is a JSON object containing the member name http://schemas.openid.net/event/backchannel-logout. This declares that the JWT is a Logout Token. The corresponding member value MUST be a JSON object and SHOULD be the empty JSON object {}.
sid
OPTIONAL. Session ID - String identifier for a Session. This represents a Session of a User Agent or device for a logged-in End-User at an RP. Different sid values are used to identify distinct sessions at an OP. The sid value need only be unique in the context of a particular issuer. Its contents are opaque to the RP. Its syntax is the same as an OAuth 2.0 Client Identifier.

A Logout Token MUST contain either a sub or a sid Claim, and MAY contain both. If a sid Claim is not present, the intent is that all sessions at the RP for the End-User identified by the iss and sub Claims be logged out.

The following Claim MUST NOT be used within the Logout Token:

nonce
PROHIBITED. A nonce Claim MUST NOT be present. Its use is prohibited to make a Logout Token syntactically invalid if used in a forged Authentication Response in place of an ID Token.

Logout Tokens MAY contain other Claims. Any Claims used that are not understood MUST be ignored.

A Logout Token MUST be signed and MAY also be encrypted. The same keys are used to sign and encrypt Logout Tokens as are used for ID Tokens. NOTE: The Logout Token is compatible with the Security Event Token (SET) [RFC8417] (Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, “Security Event Token (SET),” July 2018.) specification.

A non-normative example JWT Claims Set for a Logout Token follows:

  {
   "iss": "https://server.example.com",
   "sub": "248289761001",
   "aud": "s6BhdRkqt3",
   "iat": 1471566154,
   "jti": "bWJq",
   "sid": "08a5019c-17e1-4977-8f42-65a12843ea02",
   "events": {
     "http://schemas.openid.net/event/backchannel-logout": {}
     }
  }


 TOC 

2.5.  Back-Channel Logout Request

The OP uses an HTTP POST to the registered back-channel logout URI to trigger the logout actions by the RP. The POST body uses the application/x-www-form-urlencoded encoding and must include a logout_token parameter containing a Logout Token from the OP for the RP identifying the End-User to be logged out.

The POST body MAY contain other values in addition to logout_token. Values that are not understood by the implementation MUST be ignored.

The following is a non-normative example of such a logout request (with most of the Logout Token contents omitted for brevity):

  POST /backchannel_logout HTTP/1.1
  Host: rp.example.org
  Content-Type: application/x-www-form-urlencoded

  logout_token=eyJhbGci ... .eyJpc3Mi ... .T3BlbklE ...


 TOC 

2.6.  Logout Token Validation

Upon receiving a logout request at the back-channel logout URI, the RP MUST validate the Logout Token as follows:

  1. If the Logout Token is encrypted, decrypt it using the keys and algorithms that the Client specified during Registration that the OP was to use to encrypt ID Tokens. If ID Token encryption was negotiated with the OP at Registration time and the Logout Token is not encrypted, the RP SHOULD reject it.
  2. Validate the Logout Token signature in the same way that an ID Token signature is validated, with the following refinements.
  3. Validate the iss, aud, and iat Claims in the same way they are validated in ID Tokens.
  4. Verify that the Logout Token contains a sub Claim, a sid Claim, or both.
  5. Verify that the Logout Token contains an events Claim whose value is JSON object containing the member name http://schemas.openid.net/event/backchannel-logout.
  6. Verify that the Logout Token does not contain a nonce Claim.
  7. Optionally verify that another Logout Token with the same jti value has not been recently received.

If any of the validation steps fails, reject the Logout Token and return an HTTP 400 Bad Request error. Otherwise, proceed to perform the logout actions.



 TOC 

2.7.  Back-Channel Logout Actions

After receiving a valid Logout Token from the OpenID Provider, the RP locates the session(s) identified by the iss and sub Claims and/or the sid Claim. The RP then clears any state associated with the identified session(s). The mechanism by which the RP achieves this is implementation specific. If the identified End-User is already logged out at the RP when the logout request is received, the logout is considered to have succeeded.

In the case that the RP is also an OP serving as an identity provider to downstream logged-in sessions, it is desirable for the logout request to the RP to likewise trigger downstream logout requests. This is achieved by having the RP/OP send logout requests to its downstream RPs as part of its logout actions.

Refresh tokens issued without the offline_access property to a session being logged out SHOULD be revoked. Refresh tokens issued with the offline_access property normally SHOULD NOT be revoked. NOTE: An open issue for the specification is whether to define an additional optional parameter in the logout token, probably as a value in the event-specific parameters JSON object, that explicitly signals that offline_access refresh tokens are also to be revoked.



 TOC 

2.8.  Back-Channel Logout Response

If the logout succeeded, the RP MUST respond with HTTP 200 OK. If the logout request was invalid, the RP MUST respond with HTTP 400 Bad Request. If the logout failed, the RP MUST respond with 501 Not Implemented. If the local logout succeeded but some downstream logouts have failed, the RP MUST respond with HTTP 504 Gateway Timeout.

The RP's response SHOULD include Cache-Control directives keeping the response from being cached to prevent cached responses from interfering with future logout requests. It is RECOMMENDED that these directives be used:

  Cache-Control: no-cache, no-store
  Pragma: no-cache


 TOC 

3.  RP-Initiated Logout Functionality

This specification incorporates the RP-initiated logout functionality specified in Section 5 of OpenID Connect Session Management 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” January 2017.) [OpenID.Session] by reference. All the same metadata values and messages are used by the RP to request that the OP log out RPs and then possibly redirect back to the initiating RP as are used in that specification. Therefore, they are not repeated here.



 TOC 

4.  Security Considerations

The signed Logout Token is required in the logout request to prevent denial of service attacks by enabling the RP to verify that the logout request is coming from a legitimate party.

The kinds of Relying Parties that can be logged out by different implementations will vary. Implementations should make it clear, for instance, whether they are capable of logging out native applications or only Web RPs.

OPs are encouraged to use short expiration times in Logout Tokens, preferably at most two minutes in the future, to prevent captured Logout Tokens from being replayable.



 TOC 

5.  IANA Considerations



 TOC 

5.1.  OAuth Dynamic Client Registration Metadata Registration

This specification registers the following client metadata definitions in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters] (IANA, “OAuth Parameters,” .) established by [RFC7591] (Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, “OAuth 2.0 Dynamic Client Registration Protocol,” July 2015.):



 TOC 

5.1.1.  Registry Contents



 TOC 

6.  References



 TOC 

6.1. Normative References

[IANA.JWT.Claims] IANA, “JSON Web Token Claims.”
[IANA.OAuth.Parameters] IANA, “OAuth Parameters.”
[JWT] Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” RFC 7519, DOI 10.17487/RFC7519, May 2015.
[OpenID.Core] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” November 2014.
[OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” November 2014.
[OpenID.FrontChannel] Jones, M., “OpenID Connect Front-Channel Logout 1.0,” January 2017.
[OpenID.Registration] Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” November 2014.
[OpenID.Session] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” January 2017.
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005.
[RFC6749] Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” RFC 6749, DOI 10.17487/RFC6749, October 2012.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing,” RFC 7230, DOI 10.17487/RFC7230, June 2014.


 TOC 

6.2. Informative References

[RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, “OAuth 2.0 Dynamic Client Registration Protocol,” RFC 7591, DOI 10.17487/RFC7591, July 2015.
[RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, “Security Event Token (SET),” RFC 8417, DOI 10.17487/RFC8417, July 2018.


 TOC 

Appendix A.  Acknowledgements

The OpenID Community would like to thank the following people for their contributions to this specification:

John Bradley (ve7jtb@ve7jtb.com), Ping Identity

Brian Campbell (bcampbell@pingidentity.com), Ping Identity

Pedro Felix (pmhsfelix@gmail.com), individual

Phil Hunt (phil.hunt@oracle.com), Oracle

Michael B. Jones (mbj@microsoft.com), Microsoft

Todd Lainhart (lainhart@us.ibm.com), IBM

Torsten Lodderstedt (t.lodderstedt@telekom.de), Deutsche Telekom

Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.



 TOC 

Appendix B.  Notices

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

Appendix C.  Document History

[[ To be removed from the final specification ]]

-05

-04

-03

-02

-01

-00



 TOC 

Authors' Addresses

  Michael B. Jones
  Microsoft
Email:  mbj@microsoft.com
URI:  http://self-issued.info/
  
  John Bradley
  Ping Identity
Email:  ve7jtb@ve7jtb.com
URI:  http://www.thread-safe.com/