Self-Issued Consulting

michael_b_jones@hotmail.com https://self-issued.info/

Yubico

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

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. 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 Front-Channel Logout 1.0 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. The OpenID Connect RP-Initiated Logout 1.0 specification complements these specifications by defining a mechanism for a Relying Party to request that an OpenID Provider log out the End-User. This specification can be used separately from or in combination with OpenID Connect RP-Initiated Logout 1.0, OpenID Connect Session Management 1.0, and/or OpenID Connect Front-Channel Logout 1.0. The previous version of this specification is: OpenID Connect Back-Channel Logout 1.0 (final)

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 "Authorization Server", "Client", and "Client Identifier" defined by OAuth 2.0, the term "User Agent" defined by RFC 7230, the terms "Session" and "Session ID" defined by OpenID Connect Front-Channel 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. The sid (session ID) Claim used in ID Tokens and as a Logout Token parameter has the following definition (which is identical to the corresponding definition in OpenID Connect Front-Channel Logout 1.0): 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.

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 . 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. This URL SHOULD use the https scheme and MAY contain port, path, and query parameter components; however, it MAY use the http scheme, provided that the Client Type is confidential, as defined in Section 2.1 of OAuth 2.0, and provided the OP allows the use of http RP URIs. 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 . OPTIONAL. Subject Identifier, as specified in Section 2 of . REQUIRED. Audience(s), as specified in Section 2 of . REQUIRED. Issued at time, 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. 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 {}. 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: 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. If the Logout Token is encrypted, it SHOULD replicate the iss (issuer) claim in the JWT Header Parameters, as specified in Section 5.3 of . It is RECOMMENDED that Logout Tokens be explicitly typed. This is accomplished by including a typ (type) Header Parameter with a value of logout+jwt in the Logout Token. See for a discussion of the security and interoperability considerations of using explicit typing. NOTE: The Logout Token is compatible with the Security Event Token (SET) specification, but uses a more specific typ (type) value.

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

The OP should not retransmit a Back-Channel Logout Request unless the OP suspects that previous transmissions may have failed due to potentially recoverable errors (such as network outage or temporary service interruption at either the OP or RP). In this case, the OP SHOULD delay retransmission for an appropriate amount of time to avoid overwhelming the RP. In all other cases, the OP SHOULD NOT retransmit a Back-Channel Logout Request. (Note that this is the same retransmission logic as specified in Push-Based Security Event Token (SET) Delivery Using HTTP.)

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, with the following refinements. Validate the alg (algorithm) Header Parameter in the same way it is validated for ID Tokens. Like ID Tokens, selection of the algorithm used is governed by the id_token_signing_alg_values_supported Discovery parameter and the id_token_signed_response_alg Registration parameter when they are used; otherwise, the value SHOULD be the default of RS256. Additionally, an alg with the value none MUST NOT be used for Logout Tokens. Validate the iss, aud, iat, and exp Claims in the same way they are validated in ID Tokens. Verify that the Logout Token contains a sub Claim, a sid Claim, or both. 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. 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. Optionally verify that the iss Logout Token Claim matches the iss Claim in an ID Token issued for the current session or a recent session of this RP with the OP. Optionally verify that any sub Logout Token Claim matches the sub Claim in an ID Token issued for the current session or a recent session of this RP with the OP. Optionally verify that any sid Logout Token Claim matches the sid Claim in an ID Token issued for the current session or a recent session of this RP with the OP. 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 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.

If the logout succeeded, the RP MUST respond with HTTP 200 OK. However, note that some Web frameworks will substitute an HTTP 204 No Content response for an HTTP 200 OK when the HTTP body is empty. Therefore, OPs should be prepared to also process an HTTP 204 No Content response as a successful response. If the logout request was invalid or the logout failed, the RP MUST respond with HTTP 400 Bad Request. The response MAY include an HTTP body consisting of a JSON object with error and error_description parameters conveying the nature of the error that occurred, which can assist with debugging. These error response parameters are used as specified in Section 5.2 of OAuth 2.0. Like in OAuth 2.0, the parameters are included in the entity-body of the HTTP response using the application/json media type. Also like in OAuth 2.0, the error parameter is REQUIRED when a response body is present and the error_description parameter is OPTIONAL. An error value of invalid_request MAY be used to indicate that there was a problem with the syntax of the logout request. Note that the information conveyed in the response body is intended to help debug deployments; it is not intended that implementations use different error values to trigger different runtime behaviors. The RP's response SHOULD include the Cache-Control HTTP response header field with a no-store value, keeping the response from being cached to prevent cached responses from interfering with future logout requests. An example of this is:

This specification defines features used by both Relying Parties and OpenID Providers that choose to implement Back-Channel Logout. 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 Back-Channel Logout are defined by this specification.

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.

As described in Section 2.8 of , attackers may attempt to use a JWT issued for one purpose in a context that it was not intended for. The mitigations described for these attacks can be applied to Logout Tokens. One way that an attacker might attempt to repurpose a Logout Token is to try to use it as an ID Token. As described in , inclusion of a nonce Claim in a Logout Token is prohibited to prevent its misuse as an ID Token. Another way to prevent cross-JWT confusion is to use explicit typing, as described in Section 3.11 of . One would explicitly type a Logout Token by including a typ (type) Header Parameter with a value of logout+jwt (which is registered in . Note that the application/ portion of the application/logout+jwt media type name is omitted when used as a typ Header Parameter value, as described in the typ definition in Section 4.1.9 . Including an explicit type in issued Logout Tokens is a best practice. Note however, that requiring explicitly typed Logout Tokens will break most existing deployments, as existing OPs and RPs are already commonly using untyped Logout Tokens. However, requiring explicit typing would be a good idea for new deployment profiles where compatibility with existing deployments is not a consideration.

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

This specification registers the following metadata names in the IANA "OAuth Authorization Server Metadata" registry established by .

Metadata Name: backchannel_logout_supported Metadata Description: Boolean value specifying whether the OP supports back-channel logout, with true indicating support Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Specification Document(s): of this specification Metadata Name: backchannel_logout_session_supported Metadata Description: 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 Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Specification Document(s): of this specification

This section registers the application/logout+jwt media type in the IANA "Media Types" registry in the manner described in , which can be used to indicate that the content is a Logout Token. Type name: application Subtype name: logout+jwt Required parameters: n/a Optional parameters: n/a Encoding considerations: binary; A Logout Token is a JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters. Security considerations: See of this specification Interoperability considerations: n/a Published specification: of this specification Applications that use this media type: Applications that use Logout Tokens to achieve back-channel logout Fragment identifier considerations: n/a Additional information: Magic number(s): n/a File extension(s): n/a Macintosh file type code(s): n/a Person & email address to contact for further information: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Intended usage: COMMON Restrictions on usage: none Author: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Provisional registration? No

In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations. NAT.Consulting Yubico Self-Issued Consulting Google Disney NAT.Consulting Yubico Self-Issued Consulting Illumila NAT.Consulting Yubico Self-Issued Consulting Microsoft Google Microsoft NAT.Consulting Yubico Microsoft Google Microsoft NAT.Consulting Yubico Microsoft JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. IANA IANA Microsoft Yubico This second document defines the general structure of the MIME media typing system and defines an initial set of media types. [STANDARDS-TRACK] This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. This specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration. This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. This specification defines the Security Event Token (SET) data structure. A SET describes statements of fact from the perspective of an issuer about a subject. These statements of fact represent an event that occurred directly to or about a security subject, for example, a statement about the issuance or revocation of a token on behalf of a subject. This specification is intended to enable representing security- and identity-related events. A SET is a JSON Web Token (JWT), which can be optionally signed and/or encrypted. SETs can be distributed via protocols such as HTTP. JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security tokens that contain a set of claims that can be signed and/or encrypted. JWTs are being widely used and deployed as a simple security token format in numerous protocols and applications, both in the area of digital identity and in other application areas. This Best Current Practices document updates RFC 7519 to provide actionable guidance leading to secure implementation and deployment of JWTs. This specification defines how a Security Event Token (SET) can be delivered to an intended recipient using HTTP POST over TLS. The SET is transmitted in the body of an HTTP POST request to an endpoint operated by the recipient, and the recipient indicates successful or failed transmission via the HTTP response. JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification.

The OpenID Community would like to thank the following people for their contributions to this specification: John Bradley (ve7jtb@ve7jtb.com), Yubico Brian Campbell (bcampbell@pingidentity.com), Ping Identity Andrii Deinega (andrii.deinega@gmail.com), GlobalLogic Vladimir Dzhuvinov (vladimir@connect2id.com), Connect2id Pedro Felix (pmhsfelix@gmail.com), individual Joseph Heenan (joseph@authlete.com), Authlete Phil Hunt (phil.hunt@independentid.com), Independent Identity, Inc. Michael B. Jones (michael_b_jones@hotmail.com), Self-Issued Consulting (was at Microsoft) Todd Lainhart (lainhart@us.ibm.com), IBM Torsten Lodderstedt (torsten@lodderstedt.net), independent (was at yes.com) Nat Sakimura (nat@nat.consulting), NAT.Consulting Filip Skokan (panva.ip@gmail.com), Auth0 Hans Zandbelt (hans.zandbelt@zmartzone.eu), ZmartZone

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