Session Properties

For each session, the server stores a set of session properties that describe various attributes of the session.

There are two types of session property. Fixed properties are assigned by the server. User-defined properties are assigned by the application.

Many operations use session filter expressions that use session properties to select sessions.

A privileged client can monitor other sessions, including changes to their session properties, using a addSessionPropertiesListener:forProperties:completionHandler: (PTDiffusionClientControlFeature) session properties listener. When registering to receive session properties, special key values of allFixedProperties (PTDiffusionSession) and allUserProperties (PTDiffusionSession) can be used.

Each property is identified by a key. Most properties have a single string value. The exception is the $Roles fixed property which has a set of string values.

Fixed properties are identified by keys with a '$' prefix. The available fixed session properties are:

Key	Description
$ClientIP	The Internet address of the client in string format.
$ClientType	The client type of the session. One of ANDROID, C, DOTNET, IOS, JAVA, JAVASCRIPT_BROWSER, MQTT, PYTHON, or OTHER.
$Connector	The configuration name of the server connector that the client connected to.
$Country	The country code for the country where the client's Internet address was allocated (for example, NZ for New Zealand). Country codes are as defined by Java's Locale class (ISO 3166 alpha-2 country code or UN M.49 numeric-3 area code). If the country code could not be determined, this will be a zero length string.
$GatewayType	Gateway client type. Only set for gateway client sessions. If present it indicates the type of gateway client (e.g. Kafka).
$GatewayId	The identity of a gateway client session. Only present if the $GatewayType session property is present.
$Language	The language code for the official language of the country where the client's Internet address was allocated (for example, en for English). Language codes are as defined by Java's Locale class (ISO 639 alpha-2 or alpha-3 language code, or registered language subtags up to 8 alpha letters (for future enhancements)). If the language could not be determined or is not applicable, this will be a zero length string.
$Latitude	The client's latitude, if available. This will be the string representation of a floating point number and will be NaN if not available.
$Longitude	The client's longitude, if available. This will be the string representation of a floating point number and will be NaN if not available.
$MQTTClientId	The MQTT client identifier. Only set for MQTT sessions. If present, the value of the $ClientType session property will be MQTT.
$Principal	The security principal associated with the client session.
$Roles	Authorisation roles assigned to the session. This is a set of roles represented as quoted strings (for example, "role1","role2"). The utility method PTDiffusionRolesFromString can be used to parse the string value into a set of roles.
$ServerName	The name of the server to which the session is connected.
$SessionId	The session identifier. Equivalent to description (PTDiffusionSessionId).
$StartTime	The session's start time in milliseconds since the epoch.
$Transport	The session transport type. One of WEBSOCKET, HTTP_LONG_POLL, TCP, or OTHER.

All user-defined property keys are non-empty strings. The characters ' ', '\t', '\r', '\n', '"', ''', '(', ')' are not allowed.

Session properties are initially associated with a session as follows:

1. When a client starts a new session, it can optionally propose user-defined session properties (see PTDiffusionMutableSessionConfiguration::properties). Session properties proposed in this way must be accepted by the authenticator. This safeguard prevents abuse by a rogue, unprivileged client.
2. The server allocates all fixed property values.
3. The new session is authenticated by registered authenticators. An authenticator that accepts a session can veto or change the user-defined session properties and add new user-defined session properties. The authenticator can also change certain fixed properties.

Once a session is established, its user-defined session properties can be modified by clients with viewSession (PTDiffusionGlobalPermission) and modifySession (PTDiffusionGlobalPermission) permissions using the PTDiffusionClientControlFeature feature. A privileged client can also modify its own session properties.

If a session re-authenticates (see changePrincipal:credentials:completionHandler: (PTDiffusionSecurityFeature)), the authenticator that allows the re-authentication can modify the user-defined session properties and a subset of the fixed properties as mentioned above.