Back-channel logout support for OpenID Connect clients and servers in 24.0.0.2-beta

David Mueller on Feb 13, 2024

announcements , release , beta , security ,

Post available in languages:

OpenID Connect clients and servers in Open Liberty now support back-channel logout. Back-channel logout allows OpenID Connect servers to directly notify OpenID Connect clients of a user logout so each OpenID Connect client can also log the user out locally.

Previously, OpenID Connect servers could notify OpenID Connect clients that a user logged out only by using iframes that were embedded in the OpenID Connect client’s web page. If the web page wasn’t active, the OpenID Connect client wasn’t notified of the logout that occurred on the OpenID Connect server. Back-channel logout solves this problem through direct communication between the OpenID Connect server and clients.

Back-channel logout support for OpenID Connect clients

With this release, back-channel logout support for OpenID Connect clients is enabled by default when the OpenID Connect Client feature or the Social Media Login feature is enabled. When either of these features are enabled and an openidConnectClient or a socialLogin element is defined in the server.xml file, back-channel logout endpoints are also automatically enabled on the OpenID Connect client. The OpenID Connect server sends back-channel logout requests to these endpoints to log out the user at the OpenID Connect client.

The OpenID Connect server needs the absolute URI of the back-channel logout endpoint to send the back-channel logout requests. The following back-channel logout endpoints are enabled for those features:

OpenID Connect Client: /oidcclient/backchannel_logout/{oidcClientId}
Social Media Login: /ibm/api/social-login/backchannel_logout/{socialLoginId}

For example, the following OpenID Connect Client feature configuration enables the /oidcclient/backchannel_logout/oidcClientId back-channel logout endpoint on the OpenID Connect client:

<featureManager>
    <feature>openidConnectClient-1.0</feature>
</featureManager>
...
<openidConnectClient id="oidcClientId" ... />

Similarly, the following Social Media Login feature configuration enables the /ibm/api/social-login/backchannel_logout/socialLoginId back-channel logout endpoint on the OpenID Connect client:

<featureManager>
    <feature>socialLogin-1.0</feature>
</featureManager>
...
<oidcLogin id="socialLoginId" ... />

Back-channel logout support for OpenID Connect servers

To enable back-channel logout for OpenID Connect servers, specify the backchannelLogoutUri attribute for OAuth clients that are defined in a localStore element in the server.xml file.

Also, the OpenID Connect server waits for a default of 180 seconds before the back-channel logout request times out. You can specify a custom duration by using the backchannelLogoutRequestTimeout attribute for the openidConnectProvider element.

The following server.xml file example demonstrates how to specify the back-channel logout URI that an OpenID Connect server uses to make back-channel logout requests, with a timeout of 60 seconds.

<featureManager>
    <feature>openidConnectServer-1.0</feature>
</featureManager>

...

<openidConnectProvider
    id="OidcConfigSample"
    backchannelLogoutRequestTimeout="60s"
    oauthProviderRef="OAuthConfigSample" ... />

<oauthProvider id="OAuthConfigSample" ... >
    <localStore>
        <client
            name="client01"
            backchannelLogoutUri="http://localhost:9080/oidcclient/backchannel_logout/client01"
            ... />
    </localStore>
</oauthProvider>

Now, when the OpenID Connect server’s logout or end_session endpoint is invoked, the OpenID Connect server also sends back-channel logout requests to log out the user at the OpenID Connect clients. The OpenID Connect server’s logout endpoint is /oidc/endpoint/{oidcProviderId}/logout and the end_session endpoint is /oidc/endpoint/{oidcProviderId}/end_session. In the previous example, the server’s logout endpoint is /oidc/endpoint/OidcConfigSample/logout and the end_session endpoint is /oidc/endpoint/OidcConfigSample/end_session

Alternatively, you can enable back-channel logout for an OpenID Connect server by defining the backchannel_logout_uri metadata value to specify the OpenID Connect client’s back-channel logout URI when the OAuth client is dynamically registered by using the OpenID Connect provider’s client registration endpoint.

Optionally, you can add an id_token_hint query parameter that contains an ID Token that is issued by that OpenID Connect server to the endpoint request as a query parameter to help determine the user to log out. This configuration is useful in scenarios where the logout or end_session request is made without the user’s OpenID Connect server SSO cookie.

For example, if the OpenID Connect server is hosted on http://localhost:9081 and the user’s OpenID Connect server SSO cookie is available, then invoking either of the following endpoints causes the OpenID Connect server to also send back-channel logout requests to the configured back-channel logout URIs:

Logout endpoint: http://localhost:9081/oidc/endpoint/{oidcProviderId}/logout
End session endpoint: http://localhost:9081/oidc/endpoint/{oidcProviderId}/end_session

If the user’s OpenID Connect server SSO cookie is not available, such as when you invoke the endpoints by using a curl command, then an ID token that belongs to the user must be appended to the request by using the id_token_hint query parameter.

Logout endpoint with ID token hint: http://localhost:9081/oidc/endpoint/{oidcProviderId}/logout?id_token_hint={id_token}
End session endpoint with ID token hint: http://localhost:9081/oidc/endpoint/{oidcProviderId}/end_session?id_token_hint={id_token}

Back-channel logout for SAML-configured OpenID Connect servers

Back-channel logout is also enabled for OpenID Connect servers that are configured with a SAML Identity Provider (IdP) by using the SAML Web Single Sign-On feature. A logout at the IdP also triggers the OpenID Connect server to send back-channel logout requests to the configured OpenID Connect clients.

Learn more

For more information about the Open Liberty configuration options, see the following resources:

For more information about the back-channel logout specification, see OpenID Connect Back-Channel Logout 1.0.

Try it now

To try out this feature, update your build tools to pull the Open Liberty All Beta Features package instead of the main release. The beta works with Java SE 21, Java SE 17, Java SE 11, and Java SE 8.

If you’re using Maven, you can install the All Beta Features package by using:

<plugin>
    <groupId>io.openliberty.tools</groupId>
    <artifactId>liberty-maven-plugin</artifactId>
    <version>3.10</version>
    <configuration>
        <runtimeArtifact>
          <groupId>io.openliberty.beta</groupId>
          <artifactId>openliberty-runtime</artifactId>
          <version>24.0.0.2-beta</version>
          <type>zip</type>
        </runtimeArtifact>
    </configuration>
</plugin>

You must also add dependencies to your pom.xml file for the beta version of the APIs that are associated with the beta features that you want to try. For example, the following block adds dependencies for two example beta APIs:

<dependency>
    <groupId>org.example.spec</groupId>
    <artifactId>exampleApi1</artifactId>
    <version>7.0</version>
    <type>pom</type>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>example.platform</groupId>
    <artifactId>example.example-api</artifactId>
    <version>11.0.0</version>
    <scope>provided</scope>
</dependency>

Or for Gradle:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'io.openliberty.tools:liberty-gradle-plugin:3.8'
    }
}
apply plugin: 'liberty'
dependencies {
    libertyRuntime group: 'io.openliberty.beta', name: 'openliberty-runtime', version: '[24.0.0.2-beta,)'
}

Or if you’re using container images:

FROM icr.io/appcafe/open-liberty:beta

Or take a look at our Downloads page.

If you’re using IntelliJ IDEA, Visual Studio Code or Eclipse IDE, you can also take advantage of our open source Liberty developer tools. These tools enable effective development, testing, debugging, and application management all from within your IDE.

For more information on using a beta release, refer to the Installing Open Liberty beta releases documentation.

We welcome your feedback

Let us know what you think on our mailing list. If you hit a problem, post a question on StackOverflow. If you hit a bug, please raise an issue.

See all blog posts