ACCESS::session

Description

The different permutations of the ACCESS::session command allow you to access or manipulate different portions of session information when dealing with APM requests.

Syntax

ACCESS::session data get
ACCESS::session data set [ ]
ACCESS::session exists
ACCESS::session remove

v11 Additions/Changes:
ACCESS::session create [-flow] <timeout> <lifetime>
ACCESS::session modify -sid <sid> [-timeout <timeout> <-lifetime <lifetime> | -remaining <remaining>>]
ACCESS::session sid
ACCESS::session exists [-sid <sid>]
ACCESS::session exists -state_{allow|deny|redirect|inprogress} -sid <sid>
ACCESS::session data get [-sid <sid>] [-secure | config] <key> -ssid <session_id>
ACCESS::session data set [-sid <sid>] [-secure] <key> [<value>]
ACCESS::session remove [-sid <sid>]

v11.4 Additions:
ACCESS::session create [-lifetime <lifetime>]  [-timeout <timeout>]

v13 Additions:
# Introduction of the -flow flag allows use against the current connection flow context rather than an explicit -sid parameter.

ACCESS::session data get

  • Returns the value of session variable.

ACCESS::session data set [ ]

  • Sets the value of session variable to be the given.

ACCESS::session exists

  • This commands returns TRUE when the session with provided sid exists, and returns FALSE otherwise. This command is allowed to be executed in different events other then ACCESS events. This command added in version 10.2

ACCESS::session remove

  • Removes (deletes) the user session and all associated session variables. Once this command is called, ACCESS_SESSION_CLOSED event is triggered.

ACCESS::session create

  • In versions prior to v11.4, the timeout and lifetime values are indicated directly following the command.

  • In v11.4+, the flags -timeout and -lifetime are supplied, and control the idle timeout and total session lifetime, respectively. Supplying them with a value of 0 (zero) disables that timeout check. The command will return the created SID.

  • In v13.0, a new -flow flag is added. When specified, it associates the created ACCESS session with the connection flow. This allows other ACCESS::session commands to be used without the -sid argument. The ACCESS session ID is automatically obtained from the connection flow.

ACCESS::session sid

  • Returns session id associated with current flow if it exists.

ACCESS::session modify

  • Modifies the timeout, lifetime, or remaining values of a session. -lifetime and -remaining cannot be used together.

    ===Examples===


when ACCESS_SESSION_STARTED {
   set user_subnet [ACCESS::session data get "session.user.clientip"]
   if { ![IP::addr $user_subnet equals 192.168.255.0/24] } {
       log local0. "Unauthorized subnet"
       ACCESS::session remove
   }
}

when ACCESS_POLICY_AGENT_EVENT {
    if { [ACCESS::policy agent_id] eq "lastLogon" } {
        # our limit in seconds
        set 2weeks 1209600
        # diff in 100 nanosecond increments between MS time attribute (year 1601) and start of epoch
        set offset 11644473600000
        set adtime "[ACCESS::session data get session.ad.last.attr.lastLogon]"
        # convert adtime to milliseconds
        set millisecs [expr {$adtime / 10000}]
        # subtract offset
        set lastlogintime [expr {$millisecs - $offset}]
        # convert to seconds because milliseconds for 'now' were negative (maybe vmware issue)
        set secs [expr {$lastlogintime / 1000}]
        set now [clock seconds]
        # finally calculate the difference
        set diff [expr {$now - $secs}]
        log local0. "lastLogon: $diff seconds from current time"
        if { $diff > $2weeks } {
            ACCESS::session data set session.custom.lastLogonWithin2Weeks 0
        } else {
            ACCESS::session data set session.custom.lastLogonWithin2Weeks 1
        }
    }
}

One scenario when this command is useful is when the admin tries to support non-standard browser HTTP application. Admins can verify the MRHSession cookie using this command and provide a customized response which tells the client to re-authenticate.
when HTTP_REQUEST {
    set apm_cookie [HTTP::cookie value MRHSession]
    if { $apm_cookie != "" && ! [ACCESS::session exists $apm_cookie] } {
        HTTP::respond 401 WWW-Authenticate "Basic realm=\"www.example.com\""
        return
    }
}

Insert a session variable into an HTTP header (the username in this example):
when ACCESS_ACL_ALLOWED {
   set user [ACCESS::session data get "session.logon.last.username"]
   HTTP::header insert "X-USERNAME" $user
}