Shared Geo Resolution via Auth Session Notes

[BenLad17]

Summary

Introduce a public utility class (e.g. GeoSessionUtils) that centralises reading and writing of resolved geo data to the AuthenticationSessionModel as authNotes. This allows other authenticators in the same flow to access geo context without performing their own GeoIP lookup.

Motivation

Currently, geo data resolved during authentication is not accessible to other authenticators running later in the same flow. A common use case is a 2FA authenticator that sends a push notification or email OTP to the user. By reading the resolved geo data from the session, it could enrich the message with location context to help the user recognise a legitimate login attempt:

"A login attempt was detected from Frankfurt, Germany. If this was you, please approve."

Without a shared mechanism, such an authenticator would have to either perform its own GeoIP lookup or have no location context at all.

Proposed Change

1. GeoSessionUtils public utility class

A utility class that wraps reading and writing geo data to the auth session, and exposes an enum of well-known note keys:

public class GeoSessionUtils {

    public enum GeoSessionNote {
        IP("geoaware.ip"),
        COUNTRY("geoaware.country"),
        CITY("geoaware.city"),
        REGION("geoaware.region"),
        LATITUDE("geoaware.latitude"),
        LONGITUDE("geoaware.longitude");

        private final String key;
        GeoSessionNote(String key) { this.key = key; }
        public String getKey() { return key; }
    }

    public static boolean isResolved(AuthenticationSessionModel session) {
        return session.getAuthNote(GeoSessionNote.IP.getKey()) != null;
    }

    public static void writeGeoData(AuthenticationSessionModel session, GeoData data) {
        session.setAuthNote(GeoSessionNote.IP.getKey(), data.getIp());
        session.setAuthNote(GeoSessionNote.COUNTRY.getKey(), data.getCountry());
        // etc.
    }

    public static GeoData readGeoData(AuthenticationSessionModel session) {
        // read all notes and return as GeoData
    }
}

Third-party authenticators can use this class to access geo data via the documented GeoSessionNote keys without depending on any internal implementation.

2. All GeoAware authenticators write to the session

All GeoAware authenticators should write their resolved geo data to the auth session via GeoSessionUtils, and skip writing if data is already present:

if (!GeoSessionUtils.isResolved(authSession)) {
    GeoData data = geoIpProvider.resolve(ip);
    GeoSessionUtils.writeGeoData(authSession, data);
}
GeoData data = GeoSessionUtils.readGeoData(authSession);

3. Event listener reuses session data where available

The LOGIN event listener should also check GeoSessionUtils before resolving. If a GeoAware authenticator already ran in the flow, the listener reuses that data. If not (e.g. no GeoAware authenticator is in the flow), it falls back to its own lookup as today:

if (GeoSessionUtils.isResolved(authSession)) {
    geoData = GeoSessionUtils.readGeoData(authSession);
} else {
    geoData = geoIpProvider.resolve(ip);
}
// persist to DB entity as usual

4. New GeoAware IP Enricher authenticator

For admins who want geo data available to downstream authenticators but do not need any GeoAware policy enforcement (block, alert, disable account), a new lightweight authenticator should be provided.

It does exactly one thing: resolve geo data and write it to the auth session via GeoSessionUtils. It can be placed early in any flow so that all subsequent authenticators, including the existing GeoAware IP and GeoAware Device, have access to the resolved data.

Acceptance Criteria

• GeoSessionUtils utility class is introduced with GeoSessionNote enum, isResolved(), writeGeoData(), and readGeoData() methods
• All existing GeoAware authenticators write resolved geo data to the auth session via GeoSessionUtils
• The LOGIN event listener reuses auth session data via GeoSessionUtils if already resolved during the flow
• A new GeoAware IP Enricher authenticator is introduced that only resolves and writes geo data without any policy enforcement
• GeoSessionUtils and GeoSessionNote are documented for third-party authenticator authors