%CSP.Session

Specifies the timeout value for the session in seconds.

If no user requests are received within the specified time period, then the session will end. The default value comes from the CSP application setting for the application that the session starts in which is set in the configuration manager, this is often 900 seconds or 15 minutes. Note that if you start a session in one applicaiton and move to another application the AppTimeout will not be changed to the new applications timeout value, if you wish to modify this when the application changes you can use the session events 'OnApplicationChange' method.

For no timeout, set this property to 0.

Stored the CSP application name so we can detect when the CSP application has changed. This is required so we can revalidate the user against any security permissions the other application requires that the first application does not. This is not set until the security context for this application is validated.

This property contains the browser name based on parsing the HTTP_USER_AGENT CGI variable. This property is set once when the session is created. Possible values are "IE", "Mozilla", "Netscape", "Safari" and "". Not all possible browsers are suppported and the value "" is used for unknown browsers. "Mozilla" is used for all Mozilla based browsers such as Mozilla and Firefox.

This property contains the browser operating system based on parsing the HTTP_USER_AGENT CGI variable. This property is set once when the session is created. Possible values are "Windows", "Macintosh", "X11" and "". Not all possible browsers are supported and the value "" is used for unknown browsers.

This property contains the browser version based on parsing the HTTP_USER_AGENT CGI variable. This property is set once when the session is created. The version is "" or in the format "major.minor". Not all possible browsers are supported and the value "" is used for unknown browsers.

Used by the CSP Gateway to store the session Id on the browser. Do not alter this property.

The data/time the session was created in UTC

The place users can preserve any data within a session. You can set values into this multidimensional property using: This is faster than using the Get() and Set()

This is true when this CSP session is being debugged, and false otherwise. It is set automatically by the CSP dispatch engine and you should not alter its value yourself.

A flag that you set to '1' to terminate this session upon completion of this request.

If set then use this page as the error page rather than the one obtained from the CSP application settings.

The name of the application event class to be called in response to certain CSP events. This should be a class derived from %CSP.SessionEvents. At present the events that are fired are for creation of a new session (OnStartSession), deletion of a session (OnEndSession) and the timeout of an existing session by the CSP daemon (OnTimeout). You can set the event class for a CSP application in the CSP options of the configuration manager. Note that if you set the EventClass inside a CSP page then as the session has already been created at this point it will not fire the OnStartSession event, if the EventClass is set in the CSP application settings then it will fire the start session event as it knows which event class to call before it creates the session.
Note that this adds this event class to the list unless it is already present and will not replace any existing event class. Setting this to "" will not have any effect, if you wish to remove an EventClass then call EventClassRemove()

If we are passed an 'Authorization' HTTP header the value is stored here to avoid attempting to login with this multiple times, for internal use only.

If true and the CSP gateway supports this then use the HTTP keep alive support to reuse the TCP/IP connection for any additional HTTP requests. If possible you should also supply the Content-Length header otherwise the CSP gateway will have to buffer the output in order to add the length of the message to the header. The default for this property is true to keep the connection alive where possible except for HTTP/1.0 responses where we will use the default for HTTP/1.0 which is to close the connection on each request.

Stores the encryption key used to validate and secure the communication with the browser. This key never leaves the server.

The language (RFC 1766 format) in which pages in this CSP session are to be displayed. The %session Language attribute is used as the default language for csp:text, span and div tags if %response.Language is not set. If %session.Language is not set by the program, then it will default to the best fit with the HTTP_ ACCEPT_LANGUAGE CGI variable.

The date/time when this session was last modified in UTC

Internal property that hold the name of the license that this session is associated with

The namespace this session was created from. This is set automatically when the class is created to the current namespace. It is used by the session daemon so that it can swap to the right namespace to run the timeout method on applications.

Indicates whether this is the first request of the session (True) or a subsequent request (False).

A flag specifying the level of state preservation required by this session. You can change the value of this flag at any time.

This can take one of the following values:

• 0 The only state information that is preserved is the information in the %session object.
• 1 The entire state of the session process is preserved from one request to the next. This means that you tie up this process for just this one user. As it uses the same process all local variables, locks, etc. are preserved from one request to the next.

Process Id

If a session has Preserve=1 this contains the process id in which the session is running.>

Original referrer when session was created, copied from the HTTP_REFERER %request value

If set then run this session in the namespace given rather than the one determined by the CSP application. If the application then switches applications again it will revert to the namespace determined by the CSP application.

Internal property to determine if we should send the 'secure' flag with the sessionId cookie

The session id value for this session.

The session id is a system-assigned unique value that identifies this session.

Property to determine how strictly to restrict the domain of the sessionId cookie. Options are None (0), Lax (1), and Strict (2), where Strict means the cookie can only be used within the current application. Defaults to the CSP application's corresponding setting. Applications default to Strict unless otherwise configured. Note that None is invalid for insecure (HTTP) connections.

Indicates whether sessions should be maintained using cookies or not. There are three possible values:

• 0 - Never use cookies. This will pass the CSPCHD parameter around in all the url links and as hidden fields in the <FORM> elements.
• 1 - Auto detect cookie support. This will start by trying to insert a cookie into the browser, if this fails it will switch to mode 0 and never use cookies for this session. The initial page will send both cookies to the browser and it will include the CSPCHD parameter in all links and forms.
• 2 - Always use cookies. This will only use cookies so if the browser does not accept the cookie then the session state will not be maintained.

Contains the HTTP_USER_AGENT CGI variable passed in the initial session request.

Property to determine which SameSite attribute to send with user-created cookies. Options are None (0), Lax (1), and Strict (2). Defaults to the CSP application's corresponding setting. Applications default to Strict unless otherwise configured. Note that None is invalid for insecure (HTTP) connections.

The username this CSP session is logged in as.

Remove the escalation role added by EscalateLogin(). If there is no current escalation role, this method does nothing. After this the sessions's security context will be returned to the user's initial login roles.

If this application has a Two-Factor-Authentication enabled, when this method allows you to finish the second part of the authentication. For example, a security token was sent during the initial login attempt, Login^%CSP.Session(). You must obtain this security code (an 8-character numeric string) and call CompleteToFactorLogin() to complete authencation for this user. Note: This should only be called if Login^%CSP.Session() returns a status of $$$CSPPendingTwoFactorAuthentication Returns: $$$CSPSecondFactorLoginFailed if request's application was not Two-Factor-Authentication enabled Returns: $$$OK if login was completed Returns: $$$CSPSecurityTokenMismatch is a token was found, but did not match the entered token, else returns the error code which cause the completion to fail

Remove a persistent header from the session Note that name is not case sensitive

Escalate the CSP session to the specified escalation role. The role must be one of the current user's configured EscalationRoles.

Add an event class to the list of classes we will callback. If the class is already present we will remove it and add this at the front of the list. The namespace is optional and will default to the current namespace.

Remove all event classes from the event class list

Return true if this event class is present in the current session event list or false otherwise. The namespace is optional and will default to the current namespace.

Return an array of Array(namespace,classname)="" of the currently defined event classes

Remove an event class from the set of event classes we will run on session events. The namespace is optional and will default to the current namespace. Returns true if it removed the class and false if it did not. If class is null then it will remove all event classes defined in this namespace.

Get the value of the user data at index. This is equivalent to: It is faster to access the property directly rather than use the Get() and Set() methods. These are kept for backward compatibility.

CheckLinkAccess determines whether the target user is permitted to view a given CSP or Zen page based on the security requirements for the relevant target Web application, the underlying page class, and any custom resources applied to the link.

Positive return values indicate that there is already enough information to determine if the link should be enabled (Target variables may be undefined.). Negative values indicate that further processing needs to be done. Checking that the Target User can be logged into the Target Application and/or checking if the link's page has target resources which the Target User must have privileges to.

Returns 0 if the link is not to a csp application. (enable)

Returns 1 if the user is permitted access to the page. (enable)

Returns 2 if could not determine Target User. Clicking on link will bring up login page. (choice: enable or disable)

Returns 3 if the user doesn't have access to the CSP application.(disable)

Returns 4 if the user doesn't have resources specific to the page.(disable)

Returns -1 if check both if the Target User can log into the Target Application and check the Page's resources if any.

Returns -2 just check for access to the link's Page's resources, if any.

1. It is assumed the GetLinkTargets is called from a context in which %request is available, ie, from callpage in the CSP Server
2. Definitions:
   1. Source application - application in which the current caller is being run
   2. Current user - ($Username) the user currently logged into the Source Application
   3. Target Application - the application pointed to by the link
   4. Target User - the computed username under which the user will be logged into the Target Application
   5. Target Page: the page portion of the link, e.g., /csp/app/mypage.csp: mypage.csp

This method is meant to be called from the link's containing page within the context of the CSP server. The containing page is part of a session's current application.

We must be able to detemine which target user will be used to check privileges. The target user cannot be determined if the source and target applications are different and the target is neither part of an active by-id group nor sharing-sessions with the source application.

Applications share sessions when:

• The source and target are the same application.
• The link to the target page contains CSPSHARE=1.
• Source and target applications have the same Session Cookie Path.

Who is the target user?

Since this is called from with a CSP session, there are the following situations:

1. The target application is a member of an authenticated by-id group. That group's authenticated user is the Target User.
2. If the target application will be in the current session, the CSP server has already handled logic for determing the user.
   1. The session's user is not UnknownUser. The target user is $Username.
   2. The session's user is UnknownUser
      • If the target application is the same as the source application, the Target User is UnknownUser.
      • If the target application is different, the target user is the user from the session's Sticky-context. If the session has no sticky-context, the Target User will be UnknownUser

CheckLinkAccess Policies

• If the Target Application is not a CSP Application, return ENABLE/UNKNOWN
• If the Source and Target application are the same, return CHECK_RESOURCES_ONLY.
• If the Target Application is not enabled, return NO_APP_ACCESS
• If the Target Application is part of an authenticated By-ID group, set Target User to group's User, return CHECK_ALL
• If the Target Application is part of an authenticated By-Session group, set Target User to group's User, return CHECK_ALL
• If the Target Application is neither in an authenticated by-id group nor in the Source Application's session, return ENABLE/UNKNOWN
• If an exception occurs, return NO_ACCESS_TO_RESOURCE

Return the value of the persistent session name header. Note that name is not case sensitive

Tests if a name-value pair name is defined in the user data. This has been deprecated in favour of the faster syntax:

Remove the index from the user data Data. This has been deprecated in favour of the faster syntax:

Lock the ^%cspSession global to prevent other InterSystems IRIS processes accessing this objects storage. By default the ^%cspSession global is locked so you only need to call this in rare cases where you use the Unlock() and you wish to reaquire the lock afterwards.

Login with this username and password, returns a status code to show if it worked or not. This method also trades license units at the same time so this CSP session will be logged in as a named user. If you pass type=1 then this will trade licenses only and not login as this user. After the login completes it also updates the property Username to match the $username value this session is logged in as. The property LicenseId is also updated to be the license identifier that this session is logged in with.
If a login fails then the property Username and property LicenseId will remain at their previous values. If you pass oldpassword then this will attempt to change the password of username from oldpassword to password and login as this user. Note new status return values: CSP applications can be two-factor-enabled. If the current application is one such, then if Login() successfully authenticates the username/password, it does not return $$$OK, but rather $$$CSPPendingTwoFactorAuthentication. During Two-Factor Authentication, an 8-character numeric security string will be sent to the user's cellphone. You must obtain this string from the user and call CompleteTwoFactorLogin^%CSP.Session() to complete authentication of this user. Also note that if the login SUCCEEDS (status returned will be $$$OK), but you were unable to secure a license, the new apperr parameter will have the value of $$$CSPErrorTradeLicense. In such a case, you may have to call the Login function again to trade a license. If you are calling merely to trade a license (type=1), then if the license trade fails, Login will return a status of $$$CSPErrorTradeLicense.

This call logs out the current session. The EndSession is not set to 1. This call uses the stored security context from the Event Class Context to call "OnLogout" Event Class callbacks, so the caller of Logout() must have sufficient privileges to call $System.Security.Users.ImportSecurityContext() if callbacks exist. The OnLogout callback may set EndSession to 1, if desired. The Session is logged out only if there are no callbacks, the "OnLogout" callbacks return $$$OK, or 'force' is true. If the caller has the %All role, the login cookie will also be destroyed and any pending second factor tokens for this session will be deleted. Note: Caller must do a %SaveData() on the session instance

Logout all CSP sessions for the indicated user. Callbacks can't stop logout The login cookie and any pending-second-factor logins are cancelled. Note: username="" implies username=$username. Note: $Roles must have "%All" to call this Note: LogoutAll calls %SaveData on the changed sessions.

Return the next index in the user data Data. This has been deprecated in favour of the faster syntax:

Set the value of the user data at index to value. This is equivalent to: It is faster to access the property directly rather than use the Get() and Set() methods. These are kept for backward compatibility.

Set a persistent HTTP header values in the %session object so it will be output for every response from this session. If there is already a header with this name then this will overwrite this prioir header.

Unlock the ^%cspSession global so that another process can access this objects storage at the same time. Normally all accesss to the session object is serialised so that only one process can modify the session object at any time. So if you are using frames for example the same CSP user will make requests to get all frames at once, but these will be serialised on the application server side. If you know that a frame will take a while to generate but you do not wish this to hold up the generation of the other frames and you do not need to modify the session object you can call Unlock to unlock this session object so other processors can access it. This should be used with care. The save is for internal use only, by default when you call Unlock if the session is modified we will save the changes before unlocking the session.

Get method for Username property.