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.
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.
property Debug as %Boolean [ InitialExpression = 0 ];
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.
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()
property KeepAlive as %Boolean [ InitialExpression = 1 ];
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.
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 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.
property Preserve as %Integer [ InitialExpression = 0 ];
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.
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.
property UseSessionCookie as %Integer [ InitialExpression = 1 ];
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.
method BrowserNameGet() as %String [ Language = objectscript ]
method BrowserPlatformGet() as %String [ Language = objectscript ]
method BrowserVersionGet() as %String [ Language = objectscript ]
method CompleteTwoFactorLogin(EnteredToken As %String, apperr As %Status) as %Status [ Language = objectscript ]
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
method DeletePersistentHeader(name As %String) [ Language = objectscript ]
Remove a persistent header from the session Note that name is not case sensitive
method EventClassAdd(class As %String, namespace As %String) as %Status [ Language = objectscript ]
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.
method EventClassClear() as %Status [ Language = objectscript ]
Remove all event classes from the event class list
method EventClassExists(class As %String, namespace As %String) as %Boolean [ Language = objectscript ]
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.
method EventClassGet() as %String [ Language = objectscript ]
method EventClassList(ByRef Array As %String) as %Status [ Language = objectscript ]
Return an array of Array(namespace,classname)="" of the currently defined event classes
method EventClassRemove(class As %String, namespace As %String) as %Boolean [ Language = objectscript ]
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.
final method Get(index As %String, default As %String = "") as %String [ Language = objectscript ]
Get the value of the user data at index. This is equivalent to:
Write $Get(%session.Data(index),default)
It is faster to access the property directly rather than use the Get()
and Set() methods. These are kept for backward compatibility.
method GetLinkTargets(link As %String, ByRef targetUsername As %String, ByRef targetAppName As %String, ByRef targetNamespace As %String) as %Integer [ Language = objectscript ]
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
determin 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.
It is assumed the GetLinkTargets is called from a context in which
%request is available, ie, from callpage in the CSP Server
Definitions:
Source application - application in which the current caller is being run
Current user - ($Username) the user currently logged into the Source Application
Target Application - the application pointed to by the link
Target User - the computed username under which the user will be logged
into the Target Application
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:
The target application is a member of an authenticated by-id group. That group's
authenticated user is the Target User.
If the target application will be in the current session, the CSP server has already
handled logic for determing the user.
The session's user is not UnknownUser. The target user is $Username.
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
method GetPersistentHeader(name As %String) as %String [ Language = objectscript ]
Return the value of the persistent session name header.
Note that name is not case sensitive
method GlobalReplace(source As %String, dest As %String) [ Language = objectscript ]
final method IsDefined(index As %String) as %Boolean [ Language = objectscript ]
Tests if a name-value pair name is defined in the user data.
This has been deprecated in favour of the faster syntax:
Write $Data(%session.Data(index))
final method Kill(index As %String = "") [ Language = objectscript ]
Remove the index from the user data Data. This
has been deprecated in favour of the faster syntax:
Kill %session.Data(index)
; Or if index=""
Kill %session.Data
method Lock(timeout As %Integer) as %Status [ Language = objectscript ]
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.
method Logout(force As %Integer = 0) [ Language = objectscript ]
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
method LogoutAll(username As %String = "") [ Language = objectscript ]
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.
method NewSessionSet(val As %Boolean) as %Status [ Language = objectscript ]
final method Next(index As %String = "") as %String [ Language = objectscript ]
Return the next index in the user data Data. This
has been deprecated in favour of the faster syntax:
Write $Order(%session.Data(index))
method ReferrerSet(val As %String) as %Status [ Language = objectscript ]
private final method Reset() [ Language = objectscript ]
Resets this %CSP.Session object to its initial state
method RunNamespaceFind(application As %String) as %String [ Language = objectscript ]
method RunNamespaceGet() as %String [ Language = objectscript ]
method RunNamespaceSet(val As %String, app As %String) as %Status [ Language = objectscript ]
final method Set(index As %String, value As %String) [ Language = objectscript ]
Set the value of the user data at index to value. This is
equivalent to:
Set %session.Data(index)=value
It is faster to access the property directly rather than use the Get()
and Set() methods. These are kept for backward compatibility.
method SetPersistentHeader(name As %String, value As %String) [ Language = objectscript ]
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.
method Unlock(save As %Boolean = 1) as %Status [ Language = objectscript ]
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.
method UsernameGet() as %String [ Language = objectscript ]
Get method for Username property.
private classmethod collate(source As %String, dest As %String) [ Language = objectscript ]