Search documentation of phoenix_kit

# PhoenixKit.Utils.SessionFingerprint (phoenix_kit v1.6.19)

View Source

Session fingerprinting utilities for preventing session hijacking.

This module provides functions to create and verify session fingerprints based on IP address and user agent data. These fingerprints help detect when a session token is being used from a different location or device than where it was created.

## Security Considerations

- IP addresses can change (mobile users, VPNs, etc.), so strict enforcement may impact legitimate users
- User agents can be spoofed, but provide an additional layer of verification
- This is defense-in-depth: fingerprinting complements, not replaces, other security measures

## Configuration

You can configure the strictness level in your application config:

    config :phoenix_kit,
      session_fingerprint_enabled: true,
      session_fingerprint_strict: false  # true = force re-auth, false = log warnings

## Examples

    # Create a fingerprint from a connection
    fingerprint = SessionFingerprint.create_fingerprint(conn)

    # Verify a fingerprint
    case SessionFingerprint.verify_fingerprint(conn, stored_ip, stored_ua_hash) do
      :ok -> # Fingerprint matches
      {:warning, :ip_mismatch} -> # IP changed, but might be legitimate
      {:warning, :user_agent_mismatch} -> # User agent changed
      {:error, :fingerprint_mismatch} -> # Both changed, likely hijacked
    end

# Summary

## Functions

create_fingerprint(conn)

Creates a session fingerprint from a Plug.Conn connection.

fingerprinting_enabled?()

Checks if session fingerprinting is enabled in the application config.

get_ip_address(conn)

Extracts the IP address from a connection.

hash_user_agent(conn)

Extracts and hashes the user agent from a connection.

strict_mode?()

Checks if strict fingerprint verification is enabled.

verify_fingerprint(conn, stored_ip, stored_ua_hash)

Verifies a session fingerprint against the current connection.

# Functions

# create_fingerprint(conn)

Creates a session fingerprint from a Plug.Conn connection.

Returns a map with `:ip_address` and `:user_agent_hash` keys.

## Examples

    iex> create_fingerprint(conn)
    %{ip_address: "192.168.1.1", user_agent_hash: "a1b2c3d4..."}

# fingerprinting_enabled?()

Checks if session fingerprinting is enabled in the application config.

## Examples

    iex> fingerprinting_enabled?()
    true

# get_ip_address(conn)

Extracts the IP address from a connection.

Handles proxied connections by checking X-Forwarded-For and X-Real-IP headers, falling back to the direct connection IP.

## Examples

    iex> get_ip_address(conn)
    "192.168.1.1"

# hash_user_agent(conn)

Extracts and hashes the user agent from a connection.

Returns a SHA256 hash of the user agent string for privacy and storage efficiency.

## Examples

    iex> hash_user_agent(conn)
    "a1b2c3d4e5f6..."

# strict_mode?()

Checks if strict fingerprint verification is enabled.

When strict mode is enabled, fingerprint mismatches will force re-authentication. When disabled, mismatches only log warnings.

## Examples

    iex> strict_mode?()
    false

# verify_fingerprint(conn, stored_ip, stored_ua_hash)

Verifies a session fingerprint against the current connection.

Returns:

- `:ok` if fingerprint matches
- `{:warning, :ip_mismatch}` if only IP changed
- `{:warning, :user_agent_mismatch}` if only user agent changed
- `{:error, :fingerprint_mismatch}` if both changed
- `:ok` if stored fingerprint is nil (backward compatibility)

## Examples

    iex> verify_fingerprint(conn, "192.168.1.1", "abc123")
    :ok

    iex> verify_fingerprint(conn, "10.0.0.1", "abc123")
    {:warning, :ip_mismatch}