Configuring OpenID Connect Back-Channel Logout using WSO2 Identity Server

Piraveena Paralogarajah
6 min readAug 11, 2018

OpenID Connect Back-channel logout specification provides a way for a RP (Relying Party ) to trigger logout in all RPs in a back-channel way. For an instance, if there are two RP applications relying on WSO2 Identity Server, when an end user logs-out of one of the applications, he/she can be automatically logged out of the other one as well.In OpenID Connect (OIDC), there are three logout mechanisms.

  1. OpenID Connect Session Management.
  2. OpenID Connect Back-channel Logout.
  3. OpenID Connect Front-channel logout.

Our WSO2 Identity Server already supports logout by OpenID Connect Session Management.

Since the OIDC Session management and front-channel logout uses user agent for communication, OIDC Back-channel logout is more reliable and secured than the others.

In this blog, you can read

1. Basic Steps of OIDC back-channel logout mechanism

2. Importance of logout token and sid value

3. How to configure OIDC Back-channel logout with WSO2 Identity Server

4. How to play OIDC Back-channel logout with playground2 sample?
* How to process implicit flow?
* How to process authorization code flow?

1. Basic Steps of OIDC back-channel logout mechanism

Back-channel logout flow in a nutshell
  1. Initially RP needs to register a logout endpoint with OP.
  2. sid claim (session Id) indicating the session of RP at OP should be injected in to ID Token. (sid claim value should be equal to all RPs belong to the same browser session)
  3. When a logout request is triggered by an RP, OP will find the session of RP and get the sid value corresponding to that browser session.
  4. OP find all session participants belong to that sid value and create a jwt logout token which is similar to ID token.
  5. OP will sign the logout token and send it to RP in back-channel.
  6. RP will validate the token and logout the session corresponding to the sid claim value.

2. Importance of logout token and sid value

OpenID Connect Back-channel logout depends on a logout token. It is a JSON Web Token (JWT) token. When a logout is triggered by a RP, all the other RP’s will receive that logout token. That logout token consists a sid claim (session ID) and all the RPs receive that sid value should logout the session at OpenID Provider(OP) corresponding to that sid value.

In back-channel logout flow, sid claim is stored in OIDCSession Store in such a way that all RPs belong to same browser session will have the same sid value. When a logout request comes from a RP, then OP will find the sid value belongs to that session. Later the OP will generate Logout token for all RPs belong to the same browser session by inserting sid claim. After logout token is generated, OP will send logout token to the registered logout endpoint URLs of all RPs.

3. How to configure OIDC Back-channel logout with WSO2 Identity Server?

  1. Go to this github repo ,git a clone and Run the script file.

Or else

git clone https://github.com/wso2-extensions/identity-inbound-auth-oauth.gitcd identity-inbound-auth-oauthgit checkout feature-oidc-backchannel-logoutmvn clean install -Dmaven.test.skip=truegit clone https://github.com/piraveena/product-is.gitcd product-isgit checkout oidc-back-channel-logoutmvn clean install -Dmaven.test.skip=true

(or else if you go to wso2 product-is repository to clone, checkout to ‘feature-oidc-backchannel-logout’ branch and change the oauth version as 5.5.149-SNAPSHOT in the pom.xml file. Then build it)

2. OAuth component will be built first and then product-is will be built.

3. Get wso2 product-is server pack from product-is>distribution>target directory. It will be as wso2is-5.4.0-SNAPSHOT.zip

3. Extract that zip file and get wso2is-5.4.0-SNAPSHOT directory.

4. Go to the directory wso2is-5.4.0-SNAPSHOT> dbscripts> identity> h2.sql.

5. Add a database column for back-channel logour url. ( BACKCHANNELLOGOUT_URL VARCHAR (1024)) in IDN_OAUTH_CONSUMER_APPS table.

BACKCHANNELLOUGUT_URL column need to be added in IDN_AUTH_CONSUMER_APPS

6. Go to the directory wso2is-5.4.0-SNAPSHOT>bin . Start the server with the command sh wso2server.sh -Dsetup

7. Go to management console (https://localhost:9443/carbon/) .

8. Add a service provider as playground2 .

9. Goto ‘Inbound Authentication Configuration’ > ‘OAuth/OpenID Connect Configuration’ and click ‘Configure’ and provide

the back-channel logout url as http://localhost:8080/playground2/logoutcallback-url as http://localhost:8080/playground2/oauth2client
Playground2 application settings

10. Check the Identity provider in the management console. At the bottom of OpenID Connect Configuration list, the back-channel logout of the identity provider is mentioned. This is the back-channel logout endpoint of the Identity server where all the logout request go.

Resident Identity provider

4. How to play OIDC Back-channel logout with playground2 sample?

  1. Since we already build the product-is, we can find the playground2 sample in product-is directory.
  2. Go to product-is source directory>modules>samples>oauth2>playground2>target. Get playground2.war sample.
  3. Depoly that in tomcat and start the tomcat.
  4. Invoke http://localhost:8080/playground2/ url and should get the page below
Home page of playground2 sample

5. Click import photos

A. How to process implicit flow?

  1. Click import photos as shown in the section-4 ( How to play OIDC Back-channel logout with playground2 sample?). You will be redirected to a new page of playground2 and Provide below inputs and click ‘Authorize’
Authorization Grant Type :
implict
Client Id :
Client ID of the playground2 application registered
Scope :
openid
Implicit Response Type : ID token only / or ID token and access tokenCallback URL :
http://localhost:8080/playground2/oauth2client
Authorize Endpoint :
https://localhost:9443/oauth2/authorize
Logout Endpoint :
https://localhost:9443/oidc/logout
Credentials of playground2 sample

2. Login page will prompt. Provide the username and password and sign in.

Login page of WSO2 identity server

3. You will get a consent page. Click ‘Approve’

Login Consent page prompted by the WSO2 IS server

4. You will get ID token and you can view sid claim found in the ID token.

Claims including sid and their values found in ID token

5. Click ‘logout’ button and you will be directed to a consent page. Then click ‘Yes’

Logout consent page prompted by the WSO2 IS server

6. playground2 is logged out now using OIDC back-channel mechanism.

Success message after OIDC back-channel logout

B. How to process for Authorization code flow?

  1. Click import photos as shown in the section-4 ( How to play OIDC Back-channel logout with playground2 sample?). You will be redirected to a new page of playground2 and Provide below inputs and click ‘Authorize’
Authorization Grant Type :
Authorization code
Client Id :
Client ID of the playground2 application registered
Scope :
openid
Implicit Response Type : ID token only / or ID token and access tokenCallback URL :
http://localhost:8080/playground2/oauth2client
Authorize Endpoint :
https://localhost:9443/oauth2/authorize
Logout Endpoint :
https://localhost:9443/oidc/logout
Credentials of playground2 sample

2. Login page will prompt. Provide the username and password and sign in.

Login page of WSO2 identity server

3. You will get a consent page. Click ‘Approve’

Login Consent page prompted by the WSO2 IS server

4. Once the authentication is success, OP will redirect back to the client application with the authorization code.

Redirected back to the callback url of playground2 sample

5. You can logout after getting the access token .

6. If you click logout button, you will be redirected to the consent page.

Logout consent page

6. After clicking ‘Yes’, your logout process will be successful.

Success message after OIDC back-channel logout

--

--

Piraveena Paralogarajah

Software Engineer @WSO2, CSE Undergraduate @ University of Moratuwa, Former Software Engineering Intern @ WSO2