|
1 | | - |
2 | | -{% if product_name == "WSO2 Identity Server" %} |
3 | 1 | # Implement back-channel logout |
4 | 2 |
|
5 | | -Back-channel logout allows users to be logged out from a client application through direct communication of logout requests between the client application and the authorization server. |
6 | | - |
7 | | -## How it works |
8 | | - |
9 | | -The underlying message flow of OpenID Connect (OIDC) back-channel logout is as follows: |
10 | | - |
11 | | -1. A user logout is initiated by either the client application or the authorization server. |
12 | | -2. The authorization server identifies all client applications associated with the user's session. |
13 | | -3. The authorization server generates a logout token, a special JWT containing specific claims, and sends it with a logout request to the logout endpoints of the identified client applications. |
14 | | -4. Upon receiving the logout token, each client application validates it and then invalidates the corresponding user session. |
| 3 | +{% if product_name == "WSO2 Identity Server" %} |
15 | 4 |
|
16 | | -## Prerequisites |
17 | | -To get started, you need to: |
18 | | - |
19 | | -- [Register two OIDC application with {{ product_name }}]({{base_path}}/guides/applications/register-oidc-web-app/). Application names used in this guide are `Playground_app1` and `Playground_app2` |
| 5 | +Back-channel logout, defined in the OpenID Connect (OIDC) specification, allows logging out of client applications without user interaction. Unlike front-channel logout that relies on the user's browser to notify each client application, back-channel logout happens entirely through server-to-server communication between the authorization server and the client applications. |
20 | 6 |
|
21 | | -- [Download two instances of the playground application](https://github.com/wso2/samples-is/releases/download/v4.5.2/playground2.war) as this guide uses the playground sample app. Rename the second file as `playground3.war`. |
| 7 | +For protocol details, see the OpenID specification: [OpenID Connect Back-Channel Logout 1.0](https://openid.net/specs/openid-connect-backchannel-1_0.html). |
22 | 8 |
|
23 | | -- Configure the sample applications; |
| 9 | +## How it works |
24 | 10 |
|
25 | | - 1. Copy the downloaded playground.war file into `<TOMCAT_HOME>/apache-tomcat-<version>/webapps` folder. |
26 | | - 2. Start the Tomcat server. |
27 | | - 3. If required, update the `<param-value>` parameters for the `serverUrl`, `username` and `password` in the `WEB-INF/web.xml` file. |
28 | | - 4. Restart the Tomcat server, if you have done any changes to the `WEB-INF/web.xml` file. |
| 11 | + |
29 | 12 |
|
30 | | -## Configure back-channel logout |
| 13 | +The underlying message flow of OIDC back-channel logout happens as follows: |
31 | 14 |
|
32 | | -- To configure back-channel logout for `Playground_app1`: |
| 15 | +1. The client application initiates a user logout. |
| 16 | +2. {{ product_name }} identifies all the client applications associated with the user's session. |
| 17 | +3. {{ product_name }} generates a logout token, a special JWT (JSON Web Token) containing specific claims and sends it with a logout request to the logout endpoints of all the client applications. |
| 18 | +4. Upon receiving the logout token, each client application validates the token and proceeds to invalidate the corresponding user session. |
33 | 19 |
|
34 | | - 1. On the WSO2 Identity Server Console, go to **Applications** and select your OIDC application. |
35 | | - 2. Go to the **Protocol** tab and enter the following details: |
| 20 | +## Configure back-channel logout URL |
36 | 21 |
|
37 | | - | Field Name | Value | |
38 | | - |---------------|-------| |
39 | | - | Grant type | Implicit | |
40 | | - | Back channel logout URL | http://localhost:8080/playground3/bclogout | |
| 22 | +Follow the steps below to register the back-channel endpoint of your application with {{product_name}}. |
41 | 23 |
|
42 | | - 3. Click **Update** to save your configurations. |
| 24 | +!!! note "Before you begin" |
43 | 25 |
|
44 | | -- To configure back-channel logout for `Playground_app2`: |
| 26 | + [Register your OIDC application]({{base_path}}/guides/applications/) in {{product_name}}. |
45 | 27 |
|
46 | | - 1. On the WSO2 Identity Server Console, go to **Applications** and select your OIDC application. |
47 | | - 2. Go to the **Protocol** tab and enter the following details: |
| 28 | +1. On the {{ product_name }} Console, go to **Applications** and select your OIDC application. |
48 | 29 |
|
49 | | - | Field Name | Value | |
50 | | - |---------------|-------| |
51 | | - | Grant type | Implicit | |
52 | | - | Back channel logout URL | http://localhost:8080/playground2/bclogout | |
| 30 | +2. Go to the **Protocol** tab, and under **Logout URLs**, enter the **Back channel logout URL**. |
53 | 31 |
|
54 | | - 3. Click **Update** to save your configurations. |
| 32 | + {: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"} |
55 | 33 |
|
56 | | -## Try it out |
| 34 | +3. Click **Update** to save your configurations. |
57 | 35 |
|
58 | | -1. Access the **Playgrpund_app1** application using the following URL: http://localhost:8080/playground2/. |
| 36 | +## Set up your client application |
59 | 37 |
|
60 | | -2. Click **Import Photos**. |
| 38 | +To complete the back-channel logout flow, you must set up the client application so that it can perform the following required actions. |
61 | 39 |
|
62 | | -3. Enter the following details: |
| 40 | +1. **Receive back-channel logout requests** - The client application must expose an endpoint that accepts POST requests from the authorization server to handle logout requests. You need to [register this endpoint with {{product_name}}](#configure-back-channel-logout-url). |
63 | 41 |
|
64 | | - | Field name | Value | |
65 | | - |-------------|-------| |
66 | | - | **Authorization Grant Type** | `Implicit` | |
67 | | - | **Client ID** | The OAuth Client ID received when registering the Playground_app1 in WSO2 Identity Server. | |
68 | | - | **Callback URL** | `http://localhost:8080/playground2/oauth2client` | |
69 | | - | **Authorize Endpoint** | `https://localhost:9443/oauth2/authorize` | |
| 42 | +2. **Validate the logout token** - The following is an example of the logout token sent by the {{ product_name }} to a client application: |
70 | 43 |
|
71 | | -4. Click **Authorize**. You will be redirected to the WSO2 Identity Server login page. |
| 44 | + ``` json |
| 45 | + { |
| 46 | + "iss": "{{product_url_sample}}/oauth2/token", |
| 47 | + "sub": "aa21e449-****-****-****-****a6a3961f", |
| 48 | + "aud": "w_Hwp05dF****_****9SNwpflAa", |
| 49 | + "iat": 1609911868, |
| 50 | + "exp": 1609911988, |
| 51 | + "jti": "16159e3e-****-****-****-b0782ab33d58", |
| 52 | + "sid": "15043ffc-****-****-****-9b107f7da38c", |
| 53 | + "events": { |
| 54 | + "http://schemas.openid.net/event/backchannel-logout": {} |
| 55 | + } |
| 56 | + } |
| 57 | + ``` |
72 | 58 |
|
73 | | -5. Enter the credentials of your user account and click Sign In. You will now receive an ID Token. |
| 59 | + Your client application must perform JWT token validation as defined in the [OIDC back-channel logout specification](https://openid.net/specs/openid-connect-backchannel-1_0.html#Validation). A summary of the validations is below. |
74 | 60 |
|
75 | | -6. Access the **Playground_app2** application using the follwoing URL: http://localhost:8080/playground3/ |
| 61 | + - `iss`: Must match your trusted issuer. |
76 | 62 |
|
77 | | -7. Repeat steps 2-5 for **Playground_app2** application with the following values: |
| 63 | + - `aud`: Must match your application's client ID. |
78 | 64 |
|
79 | | - | Field name | Value | |
80 | | - |-------------|-------| |
81 | | - | **Authorization Grant Type** | `Implicit` | |
82 | | - | **Client ID** | The OAuth Client ID received when registering the Playground_app2 in WSO2 Identity Server. | |
83 | | - | **Callback URL** | `http://localhost:8080/playground3/oauth2client` | |
84 | | - | **Authorize Endpoint** | `https://localhost:9443/oauth2/authorize` | |
| 65 | + - `iat` and `exp`: Must be within a valid timeframe. |
85 | 66 |
|
86 | | -8. Click **Logout** on one of the applications. You will be prompted to consent to the logout. |
| 67 | + - `events`: Must contain the http://schemas.openid.net/event/backchannel-logout claim. |
87 | 68 |
|
88 | | -9. Provide consent. You will receive confirmation of sucessful logout. |
| 69 | + - `sid`: Must be present to identify the session. |
89 | 70 |
|
90 | | -10. Now, go to the other application and reload the page. Note that you are redirected to the login page of the playground application and you will see that the **Logged in user** has changed to `null`. |
91 | 71 |
|
92 | | -You have successfully configured and tried out OIDC back-channel logout. You can check out the Tomcat logs on the terminal window to see the back-channel logout flow. |
| 72 | +3. **Terminate the user session** - Once the client validates the token and determines it to be valid, the client should use the `sid` claim to locate and terminate the user's session. |
93 | 73 |
|
94 | | -{% endif %} |
| 74 | +{% endif %} |
0 commit comments