--- title: Setting up PingFederate session revocation by user identifier description: Starting with PingFederate 10.3, you can revoke a user's sessions with their authentication sources by submitting a user identifier, such as the mail or userPrincipalName attribute value. component: solution-guides page_id: solution-guides:single_sign-on_use_cases:htg_setup_pf_session_revocation canonical_url: https://docs.pingidentity.com/solution-guides/single_sign-on_use_cases/htg_setup_pf_session_revocation.html revdate: April 29, 2024 page_aliases: ["single_sign-on_use_cases:htg_setup_pf_session_revocation_adapter.adoc", "single_sign-on_use_cases:htg_setup_pf_session_revocation_session.adoc", "single_sign-on_use_cases:htg_setup_pf_session_revocation_oauth_client.adoc", "single_sign-on_use_cases:htg_setup_pf_session_revocation_token.adoc", "single_sign-on_use_cases:htg_setup_pf_session_revocation_api.adoc"] section_ids: component: Component configuring-adapter-settings: Configuring adapter settings about-this-task: About this task steps: Steps choose-from: Choose from: configuring-session-settings: Configuring session settings about-this-task-2: About this task steps-2: Steps configuring-an-oauth-client: Configuring an OAuth client about-this-task-3: About this task steps-3: Steps configuring-an-access-token-manager: Configuring an access token manager about-this-task-4: About this task steps-4: Steps using-the-api: Using the API --- # Setting up PingFederate session revocation by user identifier Starting with PingFederate 10.3, you can revoke a user's sessions with their authentication sources by submitting a user identifier, such as the `mail` or `userPrincipalName` attribute value. For example, you have a terminated user, and their user account has been disabled in your directory. However, they still have an authentication session with PingFederate on their device that would allow them to single sign-on (SSO) into applications until that session is no longer valid. You can easily revoke their sessions so that any attempt to do so fails. This process works both for sessions stored in memory across hosts and for persistent sessions stored in an external database. ## Component PingFederate 10.3 and later. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The following sections call out the configuration options that relate specifically to session revocation by user identifier. The rest of the configuration is left to you. | ## Configuring adapter settings ### About this task In this example, you are configuring an HTML Form Adapter. For more information, see [HTML Form Adapter](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_html_form_adapt.html). ### Steps 1. In the PingFederate administrative console, go to **Authentication → Integration → IdP Adapters**. 2. Do one of the following: #### Choose from: * Create a new HTML Form Adapter by clicking **Create New Instance**. * Edit an existing HTML Form Adapter by clicking the name of the adapter in the **Instance Name** list. 3. On the **IdP Adapter** tab, for **Session State**, click **None**. The HTML Form Adapter can keep the session state itself, but you need to track the session at the server level. ![Screen capture that shows the Session State option in the IdP Adapter tab.](_images/voy1663872575048.png) 4. On the **Adapter Attributes** tab, in the **Unique User Key Attribute** list, select **userPrincipalName**. This is the attribute value that you would submit to find and revoke a user's sessions. In this example, you are using the `userPrincipalName` attribute from Active Directory, but you could use something like `mail` if you prefer. ![Screen capture showing the Unique User Key Attribute set to userPrincipalName in the Adapter Attributes tab.](_images/brl1663872883083.png) 5. If this is a new adapter, complete the rest of the configuration settings. 6. Save your HTML Form Adapter. ## Configuring session settings ### About this task The authentication source must have sessions enabled. If it doesn't, there isn't anything to revoke, but your users will be asked to authenticate every time they use that authentication source. You can enable sessions for all sources or for specific sources only. For more information, see [Configuring authentication sessions](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_config_auth_sessions.html). ### Steps 1. In the PingFederate administrative console, go to **Authentication → Policies → Sessions**. 2. If you want to enable authentication sessions for all sources, in the **Authentication Sessions** area, select the **Enable Authentication Sessions For All Sources** checkbox. 3. If you want to enable authentication sources for specific sources only, in the **Overrides** area, configure one or more authentication sources as shown in the following image. ![Screen capture showing the Authentication Sessions area and the Overrides area on the Sessions page.](_images/ugj1663876987836.png) 4. Save your session configuration. ## Configuring an OAuth client ### About this task To use the Session Management API, you'll need an OAuth client enabled. For session revocation, the client must use authentication. In this example, you are using client secret, but you can choose TLS or private key JSON Web Token (JWT). For more information about configuring OAuth clients, see [Configuring OAuth clients](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_configuring_oauth_clients.html). ### Steps 1. In the PingFederate administrative console, go to **Applications → OAuth → Clients**. 2. Click **Add Client**. 3. For **Client Authentication**, select the **Client Secret** option. 4. For **Client Secret**, select **Change Secret**, and then enter a secret or click**Generate Secret**. ![Screen capture showing the Client Authentication area with the Client Secret option selected.](_images/zvb1663947343284.png) 5. For **Redirect URIs**, in the**Redirection URIs** field, enter **http\://localhost**, and click **Add**. 6. For **Bypass Authorization Approval**, select the **Bypass** checkbox to bypass the approval page. 7. For **Allowed Grant Types**, select the **Implicit** checkbox to use the implicit grant type. ![Screen capture showing the Redirect URIs area, and the Bypass Authorization Approval Bypass option and Allowed Grant Types Impact option selected.](_images/rey1663947520055.png) 8. For **Session API Endpoints**, select the **Allow Access to Session Revocation API** and **Allow Access to Session Management API** checkboxes. ![Screen capture showing the Sessions Endpoints API area in the Client window.](_images/ntn1664469565273.png) 9. Save your OAuth client configuration. ## Configuring an access token manager ### About this task To use the Session Management API, you'll need an access token manager configured to include session identifiers in its tokens. In the access token management settings, select the checkbox to include the session identifier. For more information, see [Access token management](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_access_token_management.html). ### Steps 1. In the PingFederate administrative console, go to **Applications → OAuth → Access Token Management**. 2. Click **Create New Instance**. 3. On the **Session Validation** tab, select the **Include Session Identifier in Access Token** checkbox. ![Screen capture showing the Include Session Identifier in Access Token option on the Session Validation tab.](_images/sma1663958038556.png) 4. Save your access token manager instance. ## Using the API In this example, you are using Postman to use the API. You can use CURL or build your own app if you prefer. For testing, we logged into a basic SAML application using the adaptor that we configured for sessions and the unique user key. | | | | - | ----------------------------------------------------------------------------------------------------- | | | If you need a SAML testing app, see [PingFacile Facile Decoder](https://decoder.pingidentity.cloud/). | Using Postman, you can get the user's sessions with the unique user key that you've selected: `userPrincipalName` in this example. This is a GET request, and you can see that the @ sign in the user identifier is encoded because it's being sent in the URL. ![Screen capture showing the example GET request, \`https://pingfed-idp.ad.jibboo.org:9031/pf-ws/rest/sessionMgmt/users/jsmith%40ad.reba.org.\`](_images/bkt1664480511636.png) Replace the PingFederate service host name and port with yours, and `jsmith%40ad.reba.org` with the appropriate user identifier. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In the **Headers** tab, include the `X-XSRF-Header` key with a value of **PingFederate** as shown in the following image.![Screen capture of the contents of the Headers tab in Postman with the X-XSRF-Header key and the value highlighted.](_images/bjm1664308706175.png) | The following figure shows the **Body** tab in Postman with the user's session displayed after the GET request was issued. ![Screen capture showing the session in the Body tab after the GET request was issued.](_images/xkl1664474358498.png) Now that you can see that the user has sessions, you can make a POST request to the revocation endpoint with the unique identifier. For example: ![Screen capture showing the example POST revocation request, \`https://pingfed-idp.ad.jibboo.org:9031/pf-ws/rest/sessionMgmt/users/jsmith%40ad.reba.org/revoke\`.](_images/zjz1664478401045.png) You won't receive any response body, but you will receive a `200 OK` status message. When you try the GET endpoint again, you'll find that there are no sessions for that user. ![Screen capture showing no sessions in the Body tab after the POST request was issued.](_images/yqz1664478565583.png)