How to intercept identity provider back-channel logout calls to BFF internal logout uri ?

[sisco70]

Hi,

I have another question :-)

Within my BFF (which implements Spring Cloud Gateway) I would like to intercept back-channel logout calls coming from my Keycloak instance (v. 26.0.7).

I would like to be able to perform some sort of callback.
Is something already provided in spring-addons-starter-oidc or do I need to implement a custom AbstractGatewayFilterFactory ?

          back-channel-logout:
            enabled: true
            internal-logout-uri: ${client-uri}/logout/connect/back-channel/${client-id}

Thank you very much

[ch4mpy]

All that spring-addons-starter-oidc does regarding Back-Channel Logout is easing configuration when using a reverse proxy (which is a pretty frequent configuration in systems using Back-Chanel Logout).

For instance, let's consider:

• A Keycloak instance running in Docker on port 8079. In the compose file, the Keycloak container is configured with "host.docker.internal:host-gateway" among its extra_hosts.
• An OAuth2 BFF launched in debug mode from an IDE on the host machine on port 8080.
• A Nginx reverse-proxy running in Docker and configured on ports 80 and 443, with a self-signed SSL certificate for 443.

The OAuth2 client for the BFF is configured in Keycloak with a Back-Channel Logout of http://host.docker.internal:8080/logout/connect/back-channel/oauth2-gateway (using localhost would loop to Keycloak's container itself and result in a failure to contact the BFF).

The BFF is configured with internal-logout-uri: ${client-uri}/logout/connect/back-channel/${registration-id} (be careful with the client-id in your question, you'd better use a registration id). Using ${client-uri} avoids host resolution issues for host.docker.internal which is known by Keycloak in docker, but not by the BFF on the host machine. Note that using http://localhost:${server.port} instead of ${client-uri} should work as well as this URI is used for a loop from the BFF to itself, and there is no need to go through the reverse-proxy for that.

When logging out from Keycloak user account management UI at https://localhost/auth/realms/{realmId}/account, a Back-Channel Logout event is sent by Keycloak to the BFF (skipping the reverse proxy and its self-signed certificate which might not be added to the cacerts of the container JRE Keycloak is running into). This request:

• must be processed by the security filter chain with oauth2Login (be careful that the security-matchers actually match /logout/connect/back-channel/${registration-id})
• is anonymous (be careful that it is added to the permitAll under client properties) . This is a direct communication from Keycloak to the BFF, and as the user's browser can't be used, there is no session cookie

The BFF finds the session using the information from the token contained in the Back-Channel Logout request body and loops to itself, but this time with the session cookie to end the session, just as if it was an authorized request from the user's agent, instead of an anonymous request from the Keycloak server.

So, you'll have to choose which of the 2 Back-Channel Logout requests to hook into (the anonymous request from Keycloak or the authorized internal loop). And I'm afraid that you'll have to dive into Spring Security implementation to figure out how.

May I ask what you are trying to do with this callback?

[sisco70]

My legacy web application (.war) deployed on a Wildfly application server has an entrypoint to be called on logout (to perform internal cleanup tasks).
I would like to make sure that it is always called back (from the BFF) even if the session expires, or if in SSO some other confidential client in my realm has performed a logout.

Just for reference, I attach my docker-compose (without services for legacy backend) and my BFF's application.yml.

I have Keycloak and BFF in the same internal docker network, using HTTPS everywhere with my custom, self-signed root CA.
I have a doubt... I can log out internally, without having to add in the permit-all: /logout/connect/back-channel/

services:
  nginx:
    image: nginx:1.26
    container_name: "nginx"
    hostname: "biv.lan"
    networks:
      - backend_lan
    depends_on:
      - bff
    ports:
      - "443:443"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
      - ./nginx/custom_proxy.conf:/etc/nginx/custom_proxy.conf
      - ./nginx/proxy_params:/etc/nginx/proxy_params
      - ./nginx/images:/var/www/img/
      - ./certs/biv.crt:/etc/nginx/biv.crt
      - ./certs/biv.key:/etc/nginx/biv.key

  bff:
    build:  
      context: ./bff
    container_name: "bff"
    hostname: "bff.lan"
    networks:
      - backend_lan  
    depends_on:
      keycloak:
        condition: service_healthy
    #ports:
    #  - "5005:5005"  
    environment:
      TZ: "Europe/Rome"
      #JAVA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
    volumes:
      - ./bff/config/application.yaml:/opt/config/application.yaml
      - ./certs/bff.key:/opt/bff.key
      - ./certs/bff.crt:/opt/bff.crt
  

  keycloak_db:
    image: postgres:16-alpine
    container_name: keycloak_db
    hostname: "auth.db.lan"
    networks:
      - backend_lan
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 5s
      timeout: 5s
      retries: 5 
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD_FILE: /run/secrets/KC_DB_PASSWORD
    secrets:
       - KC_DB_PASSWORD
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped


  keycloak:
    image: quay.io/keycloak/keycloak:26.0.7
    container_name: keycloak
    hostname: "auth.lan"
    networks:
      - backend_lan
    depends_on:
      keycloak_db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/9000;echo -e 'GET /health/ready HTTP/1.1\r\nhost: http://localhost\r\nConnection: close\r\n\r\n' >&3;if [ $? -eq 0 ]; then echo 'Healthcheck Successful';exit 0;else echo 'Healthcheck Failed';exit 1;fi;"]
      start_period: 20s
      interval: 5s
      retries: 10
      timeout: 5s
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_BOOTSTRAP_ADMIN_PASSWORD} 
      KC_DB: postgres
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      KC_DB_URL: 'jdbc:postgresql://auth.db.lan:5432/keycloak'
      KC_HOSTNAME: 'https://biv.lan/auth'
      KC_HTTP_RELATIVE_PATH: '/auth'
      KC_HTTPS_PORT: 9443
      KC_HTTPS_CERTIFICATE_FILE: '/opt/keycloak/conf/auth.crt'
      KC_HTTPS_CERTIFICATE_KEY_FILE: '/opt/keycloak/conf/auth.key'
      KC_HEALTH_ENABLED: true
    command: 
      - start
      #- --import-realm
    volumes:
      - ./keycloak/conf/myca.crt:/opt/keycloak/conf/truststores/myca.crt
      - ./certs/auth.crt:/opt/keycloak/conf/auth.crt
      - ./certs/auth.key:/opt/keycloak/conf/auth.key
      #- ./keycloak/realm-export.json:/opt/keycloak/data/import/realm.json

networks:
  backend_lan:
    driver: bridge
    ipam:
      config:
          - subnet: 192.168.99.0/24
            gateway: 192.168.99.1

volumes:
  postgres_data:

# From .env file
secrets:
  KC_DB_PASSWORD:
    environment: KC_DB_PASSWORD

BFF application.yml

# External visibile with NGINX
reverse-proxy-uri: https://biv.lan/bff

# internal host
client-uri: https://bff.lan:7443

# Wildfly
bivdt-uri: http://wf26.lan:8080

issuer: https://biv.lan/auth/realms/autostrade
client-id: bff-client
client-secret: 
username-claim-json-path: $.preferred_username
authorities-json-path: $.realm_access.roles

server:
  port: 7443
  ssl:
    bundle: "web-server"
  http2:
    enabled: true
  compression:
    enabled: true

spring:
  threads:
    virtual:
      enabled: true
  web:
    resources:
      static-locations: 'classpath:/static/'
  ssl:
    bundle:
      pem:
        web-server:
          keystore:
            certificate: 'file:/opt/bff.crt'
            private-key: 'file:/opt/bff.key'

  cloud:
    gateway:
      default-filters:
        - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin
      # For my legacy app are not needed 
      #- TokenRelay=
      #- SaveSession
      routes:
        - id: bivdt
          uri: ${bivdt-uri}
          predicates:
            - Path=/BIVDT/**
          filters:
            - StripPrefix=1
            # Custom filter for legacy app
            - PrincipalHeader=.............

  security:
    oauth2:
      client:
        provider:
          keycloak:
            issuer-uri: ${issuer}
            user-name-attribute: preferred_username
        registration:
          bff-client:
            provider: keycloak
            authorization-grant-type: authorization_code
            client-id: ${client-id}
            client-secret: ${client-secret}
            scope: 
              - openid
              - profile
              - roles 
              #- offline_access
com:
  c4-soft:
    springaddons:
      oidc:
        ops:
          - iss: ${issuer}
            username-claim: ${username-claim-json-path}
            authorities:
              - path: ${authorities-json-path}
        client:
          client-uri: ${reverse-proxy-uri}
          login-uri: ${reverse-proxy-uri}/oauth2/authorization/${client-id}?post_login_success_uri=%2FBIVDT%2F
          back-channel-logout:
            enabled: true
            internal-logout-uri: ${client-uri}/logout/connect/back-channel/${client-id}
          security-matchers:
            - /**
          permit-all:
            - /login/**
            - /oauth2/**
          #  - /logout/connect/back-channel/**
          csrf: cookie-accessible-from-js
          oauth2-redirections:
            rp-initiated-logout: ACCEPTED
          #post-logout-redirect-path:

logging:
  level:
    org:
      springframework:
        security: DEBUG
        cloud: DEBUG

```

[ch4mpy]

even if the session expires

This looks like the key point: what you are ultimately interested in are session events. Logout events are just one of the possible causes for sessions being destroyed.

If working with a single instance BFF, the servlet version of Spring Cloud Gateway can greatly help because you could listen to the container's SessionDestroyedEvent using a Spring ApplicationListener.

If working with a clustered BFF, you should also look into Spring Session project. When the gateway is distributed for scalability or high availability, so should its sessions. As a session deletion event should be emitted only once for the cluster and not once per instance (or replica, pod, or whatever you name what is part of the same clustered BFF), the callback to other components of the system should be triggered from the shared sessions handling (Spring Session).

[ch4mpy]

Why do you have this feeling? It was introduced only recently (after JDK 21 virtual threads), so I doubt it will be dropped anytime soon.

I wish you good luck to hook into WebFlux sessions. Maybe with the Spring Session project? You'll need this one anyway if you want to implement horizontal scaling or high availability for the BFF.

[sisco70]

I need to do some testing to get a better idea.

I was thinking of doing some testing by extending ReactiveSessionRepository and doing it in the save() method.

Maybe to come to the same conclusion as you... :-D

Regarding a shared session repository (Redis for example).
What if instead you had a central Keycloak (outside the subnet and NGINX) with multiple BFFs (each registered as a confidential client) with their own separate sessions? Would that work?

[ch4mpy]

For distinct BFFs (as opposed to a single distributed BFF), each should have its own:

• confidential client
• Back-Channel Logout callback URL
• if distributed (each BFF is composed of potentially several instances), redis session store (sessions are shared across a given BFF instances, not across all BFFs)

In this configuration, when one of the BFFs runs an RP-Initiated Logout, Keycloak will send a Back-Channel Logout to all BFFs so that each can end its session. For distributed BFFs, Spring Session will handle complexity regarding instances.

[sisco70]

Maybe there's a typo..

I don't understand the third point.. sorry

[ch4mpy]

If you have X BFFs, each with Yx "instances", you should have X Redis session stores.

If it's a vocabulary issue, you can replace "instances" with "replications", "pods", or whatever, as long as it is part of the same clustered Spring application using Spring Session