OpenID Connect
Back-Channel Logout 1.0 - draft 07Microsoftmbj@microsoft.comhttps://self-issued.info/Yubicove7jtb@ve7jtb.comhttp://www.thread-safe.com/OpenID Connect Working GroupOpenID 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 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", "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 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.
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.
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, with the following refinements.
Validate the iss,
aud,
and iat
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.
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.
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 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 .
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 document
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 document
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/aFile extension(s): n/aMacintosh 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
OpenID Connect Core 1.0NAT.ConsultingYubicoMicrosoftGoogleStripeOpenID Connect Discovery 1.0NAT.ConsultingYubicoMicrosoftIllumilaOpenID Connect Dynamic Client Registration 1.0NAT.ConsultingYubicoMicrosoftOpenID Connect RP-Initiated Logout 1.0MicrosoftGoogleMicrosoftNAT.ConsultingYubicoOpenID Connect Front-Channel Logout 1.0MicrosoftOpenID Connect Session Management 1.0GoogleMicrosoftNAT.ConsultingYubicoMicrosoftJSON Web Token (JWT)Microsoftmbj@microsoft.comhttps://self-issued.info/Ping Identityve7jtb@ve7jtb.comhttp://www.thread-safe.com/Nomura Research Instituten-sakimura@nri.co.jphttps://nat.sakimura.org/JSON Web Token ClaimsIANAOAuth ParametersIANAMedia TypesIANA
The OpenID Community would like to thank the following people for
their contributions to this specification:
John Bradley (ve7jtb@ve7jtb.com), YubicoBrian Campbell (bcampbell@pingidentity.com), Ping IdentityVladimir Dzhuvinov (vladimir@connect2id.com), Connect2idPedro Felix (pmhsfelix@gmail.com), individualJoseph Heenan (joseph@authlete.com), AuthletePhil Hunt (phil.hunt@oracle.com), OracleMichael B. Jones (mbj@microsoft.com), MicrosoftTodd Lainhart (lainhart@us.ibm.com), IBMTorsten Lodderstedt (torsten@lodderstedt.net), yes.comNat Sakimura (nat@nat.consulting), NAT.ConsultingFilip Skokan (panva.ip@gmail.com), Auth0Hans Zandbelt (hans.zandbelt@zmartzone.eu), ZmartZoneCopyright (c) 2022 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 ]]
-07
Fixed #1468 - Support explicit typing of Logout Tokens.
The nature of the support is intentionally parallel to
the way that explicit typing of Request Objects is supported in RFC 9101.
Updated contributor affiliations.
Updated many spec URLs from http to https.
-06
Fixed #1030 - Specify the use of HTTPS URIs.
Fixed #1031 - Specify sid ID Token claim for use in Back-Channel Logout.
Fixed #1176 - Verify that the sid Logout Token claim matches this claim in an ID Token.
Added Implementation Considerations section.
Fixed #1049 - Include a reference to the OP when the Logout Token is encrypted.
-05
Referenced the final Security Event Token (SET) specification.
Fixed #1085 - Split RP-Initiated Logout into its own specification.
Registered the AS metadata values backchannel_logout_supported
and backchannel_logout_session_supported.
Updated affiliations and acknowledgements.
-04
Stated that
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.
This addresses issue #1000.
Defined logout behaviors for refresh tokens issued with and without
the offline_access property.
Removed the requirement that the domain, port, and scheme of the
backchannel_logout_uri URL
MUST be the same as that of a registered Redirection URI value.
Updated the Logout Token syntax to match
draft-ietf-secevent-token-00.
-03
Changed from using a logout_only Claim
to using a logout event in the Logout Token.
The Logout Token is compatible with draft-hunt-idevent-token-03.
-02
Renamed HTTP-Based Logout to Front-Channel Logout.
-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.