Microsoft

mbj@microsoft.com http://self-issued.info/

Ping Identity

ve7jtb@ve7jtb.com http://www.thread-safe.com/

OpenID Connect Working Group 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 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.

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 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 and OpenID Connect HTTP-Based Logout 1.0 specifications use front-channel communication. 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 HTTP-Based Logout 1.0.

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

This specification uses the terms "Client", "Client Identifier", and "Redirection URI" defined by OAuth 2.0, the term "User Agent" defined by RFC 7230, the terms "Session" and "Session ID" defined by OpenID Connect HTTP-Based Logout 1.0 and the terms defined by OpenID Connect Core 1.0 and JSON Web Token (JWT). This specification also defines the following term: JSON Web Token (JWT) similar to an ID Token that contains Claims about the logout action being requested.

If the OpenID Provider supports OpenID Connect Discovery 1.0, it uses this metadata value to advertise its support for back-channel logout: 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: 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.

Relying Parties supporting back-channel-based logout register a back-channel logout URI with the OP as part of their client registration. The domain, port, and scheme of this URL MUST be the same as that of a registered Redirection URI value. The back-channel logout URI MUST be an absolute URI as defined by Section 4.3 of . The back-channel logout URI MAY include an application/x-www-form-urlencoded formatted query component, per Section 3.4 of , 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, it uses this metadata value to register the back-channel 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: 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.

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.

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 . The following Claims are used within the Logout Token: REQUIRED. Issuer Identifier, as specified in Section 2 of . REQUIRED. Subject Identifier, as specified in Section 2 of . REQUIRED. Audience(s), as specified in Section 2 of . REQUIRED. Expiration time, as specified in Section 2 of . REQUIRED. Unique identifier for the token, as specified in Section 9 of . REQUIRED. Value declaring that this JWT is only to be used as a Logout Token. In particular, this JWT cannot be used in any context where an ID Token is used. The value of this Claim MUST be the JSON boolean value true. OPTIONAL. Session ID - String identifier for a Session. This represents a Session of an OP at an RP to a User Agent or device for a logged-in End-User. Its contents are unique to the OP and opaque to the RP. Its syntax is the same as an OAuth 2.0 Client Identifier. The following Claim MUST NOT be used within the Logout Token: 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.

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

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

Upon receiving a logout request at the back-channel logout URI, the RP MUST validate the Logout Token as follows: 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. Validate the Logout Token signature in the same way that an ID Token signature is validated. Validate the iss, aud, and exp Claims in the same way they are validated in ID Tokens. Verify that the Logout Token contains a logout_only Claim with the value true. Verify that the Logout Token does not contain a nonce Claim. 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.

After receiving a valid Logout Token, the RP locates the session identified by the iss and sub Claims and optionally the sid Claim. The RP then clears any state associated with the identified session. 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.

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:

This specification incorporates the RP-initiated logout functionality specified in Section 5 of OpenID Connect Session Management 1.0 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.

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.

This specification registers the following Claim in the IANA "JSON Web Token Claims" registry established by .

Claim Name: logout_only Claim Description: Logout Only Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Specification Document(s): of this specification

This specification registers the following client metadata definitions in the IANA "OAuth Dynamic Client Registration Metadata" registry established by :

Client Metadata Name: backchannel_logout_uri Client Metadata Description: RP URL that will cause the RP to log itself out when sent a Logout Token by the OP Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Specification Document(s): of this specification Client Metadata Name: backchannel_logout_session_required Client Metadata Description: 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 Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Specification Document(s): of this specification

Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Nomura Research Institute, Ltd. Ping Identity Microsoft Illumila Nomura Research Institute, Ltd. Ping Identity Microsoft Microsoft Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Illumila Microsoft

mbj@microsoft.com http://self-issued.info/

Ping Identity

ve7jtb@ve7jtb.com http://www.thread-safe.com/

Nomura Research Institute

n-sakimura@nri.co.jp http://nat.sakimura.org/

IANA IANA

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 Michael B. Jones (mbj@microsoft.com), Microsoft Todd Lainhart (lainhart@us.ibm.com), IBM Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.

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.

[[ To be removed from the final specification ]] -01 Cleaned up some text left over from the HTTP-Based Logout spec. Clarified the conditions under which HTTP 504 Gateway Timeout is returned. -00 Wrote the initial version based on working group discussions. The structure of this specification is intentionally similar to the OpenID Connect HTTP-Based Logout 1.0 specification.