Using Caché Server Pages (CSP)
CSP Session Management
[Back] [Next]
Go to:

HTTP is a stateless protocol; every request has no knowledge of previous requests. While this works well for web sites that provide users with simple static content, it makes it difficult to develop interactive, dynamic web applications. To help with this, CSP provides what is called session management.

Sessions with CSP.Session
A session represents a series of requests from a particular client to a particular application over a certain period of time.
CSP provides session tracking automatically; you do not have to do anything special to enable it. CSP applications can inquire and modify aspects of their session by means of the %CSP.Session object. The CSP server makes this object available via the Caché ObjectScript %session variable. For information on sharing authentication sessions or data among applications, see Authentication Sharing Strategies
Session Creation
A session starts when an HTTP client makes its first request to a CSP application.
When a new session is created, the CSP server does the following:
  1. Creates a new session ID number.
  2. Performs licensing checks, as appropriate.
  3. Creates a new instance of the %CSP.Session object (which is persistent).
  4. Invokes the OnStartSession method of the current session event class (if present).
  5. Creates a session-cookie in order to track subsequent requests from the HTTP client during the course of the session. If the client browser has disabled cookies, CSP automatically uses URL rewriting (placing a special value into every URL) in order to track sessions.
For the first request of a session, the NewSession property of the %CSP.Session object is set to 1. For all subsequent requests it is set to 0:
 If (%session.NewSession = 1) {
    // this is a new session
Session ID
A CSP application can find its particular session ID via the SessionId property of the %CSP.Session object:
 Write "Session ID is: ", %session.SessionId
Session Termination and Cleanup
A session ends for one of the following reasons. (For more information on logging out see the section Logout or End Session in this book.)
  1. The session times out because it did not receive any requests within the specified session timeout period.
  2. The recommended way to logout of a CSP session is to link to the application home page passing a URL that contains the string, CacheLogout=end. This ends the current session – releases any license acquired, deletes existing session data, and removes the security context of the session – before it attempts to run the home page.
  3. The session is explicitly ended programmatically on the server (by setting the %CSP.Session object's EndSession property to 1. For example, you may wish to end a session if the client is stopped or navigates to a new site.
  4. The session can be logged out using the %CSP.Session object's Logout method
When a session ends, the CSP server deletes the persistent %CSP.Session object and decrements the session license count, if appropriate. If the session ended because of a timeout or server action, it also invokes the OnEndSession method of the session event class (if it is present).
Certain Zen components, notably tablePane, store temporary data in ^CacheTemp.zenData, and this is typically cleaned up automatically by the default Event Class. However, if you define your own custom event class, you must explicitly call %ZEN.Controller.OnEndSession() in the OnEndSession() callback method in your event class. Otherwise the temp data is not cleaned up.
Reserved CSP Parameters
The table shows reserved parameters and their uses.
Reserved CSP Parameters
Parameter Use
From the login page, contains the username to log in; for example, CacheUserName="fred"
From the login page, contains the password of the user designated by CacheUserName; for example, CachePassword="fredspwd".
If passed in with CacheUserName and CachePassword, it contains the current password for the user. The security routines changes the user's password to a new value, the one from CachePassword, such as, CacheOldPassword="fredsAboutToBeChangedPwd". After the password is changed, the user is logged in using the new password.
Not used.
Not used.
CacheLogout with no value or any value other than "cookie" causes the session for this request to be logged out (but not destroyed.) Logging out destroys the current Login Cookie and removes any two-factor security tokens being held in limbo for this session.
CacheLogout="cookie" destroys the current Login Cookie.
CacheSecurityToken contains the value of a submitted security token from the Login Security Token page, such as CacheSecurityToken="12345678".
The presence of this name indicates that the user is submitting a security token whose value is associated with CacheSecurityToken.
The presence of this name indicates that the user has cancelled out of the Login Security Token page.
Login pages, including custom login pages, contain two sub-pages: one for login and one for returning the security token value. The page checks the value of CacheLoginPage to determine which subpage to display. CacheLoginPage=1 indicates the Login subpage should be displayed.
A page P is requested, but it is unauthenticated, so the Login page is displayed. After the user submits the information from the login page, usually the page request for P is redirected back to the browser. (This stops the browser from asking the user to press the <Resend> button before its shows P.) This behavior can be short-circuited by passing CacheNoRedirect=1
%CSP.Session Object
The %CSP.Session object contains information about the current session as well as a way to control aspects of the session programmatically.
User Session Data — Data Property
You can store application-specific information within the %CSP.Session object using its Data property. Data is a multidimensional array property that lets you associate specific pieces of information in a multidimensional array. The contents of this array are automatically maintained over the lifetime of the session.
You can use the %CSP.Session object Data property in the same way you would use any other Caché ObjectScript multidimensional array.
For example, if the following code is executed within an OnPage method:
 Set %session.Data("MyData") = 22
Then a subsequent request to the same session (regardless of which class handles the request) sees this value within the %CSP.Session object:
 Write $Get(%session.Data("MyData")) // this should print 22
The ability to store application-specific data within the %CSP.Session is a very powerful feature but should be used correctly. Refer to the section State Management for a further discussion.
Setting User Session Data — Set Command
To store data (only literal data — not object references) in the %CSP.Session object, use the Set command. Every node within the Data array can contain a string of up to 32K characters.
 Set %session.Data("MyData") = "hello"
 Set %session.Data("MyData",1) = 42
Retrieving User Session Data — Write Command
You can retrieve data from the Data property as part of a Caché ObjectScript expression:
 Write %session.Data("MyData")
 Write %session.Data("MyData",1) * 5
If you refer to a node of the Data array that has no value, there is an <UNDEFINED> (undefined) error at runtime. To avoid this, use the Caché ObjectScript $Get function:
 Write $Get(%session.Data(1,1,1)) // return a value or ""
Deleting User Session Data — Kill Command
To remove data from the Data property, use the Caché ObjectScript Kill command:
 Kill %session.Data("MyData")
Session Timeout
CSP sessions automatically track how much time has elapsed since they have received a request from a client. If this elapsed time exceeds a certain threshold then the session automatically times out.
By default, the session timeout is to 900 seconds (15 minutes). You can change this default for a CSP application in the Management Portal; [Home] > [Security] > [Web Applications] page. Select the application and click Edit. You can also set it from within an application by setting the value of the %CSP.Session object AppTimeout property:
 Set %session.AppTimeout = 3600 // set timeout to 1 hour
To disable session timeouts, set the timeout value to 0.
Note that if a session changes CSP applications during its life span, its timeout value will not be updated according to the default timeout defined in the application that the session moved into. For example, if a session starts out in CSP Application A, with a default timeout of 900 seconds, and then moves into CSP Application B, which has a default timeout of 1800 seconds, the session will still timeout after 900 seconds.
If you want an application change to result in the session timeout being updated to that of the new application, use a session event class, override the OnApplicationChange callback method, and add code to handle the update of the AppTimeout property of the %session object.
Timeout Notification — OnTimeout Method
When a CSP application timeout occurs, the CSP server can notify the application by invoking the OnTimeout method of a specified %CSP.SessionEvents class. You can specify the name of this class via the EventClass property of the %CSP.Session object.
By default, there is no event class defined and a timeout simply ends the current session.
State Management
As HTTP is a stateless protocol. Applications written for the web have to use special techniques to manage the application context or state. CSP provides a number of mechanisms for state management. Each of these may be appropriate for specific circumstances.
Tracking Data between Requests
The basic problem of state management within a web application is keeping track of information between successive HTTP requests. There are a number of techniques available for this including:
Storing Data within a Page
To store state information within a page, you must place it so that a subsequent request from this page includes the information.
If the page makes a request via a hyperlink, then the data should be placed within the URL for the hyperlink. For example, here is a hyperlink containing state information defined within a .csp file:
<a href="page2.csp?DATA=#(data)#">Page 2</A>
When the CSP serves the page containing this link, the expression #(data)# is replaced with the value of the server variable data in the text sent to the client. When the user selects this link to page2.csp, the CSP server has access to the value of DATA via the %request object. If needed, CSP can encode such data. Refer to Authentication and Encryption for more details.
If the page contains a form, you can place state information within hidden fields:
<input type="HIDDEN" name="DATA" value="#(data)#">
<input type="SUBMIT">
As with the hyperlink example, when this form is sent to the client, the expression #(data)# is replaced with the value of the variable data. When the user submits this form, the value of DATA is available via the %request object.
To automatically insert values into all links and forms, use %response.Context.
Storing Data in Cookies
Another technique for storing state information is to place it within a cookie. A cookie is a name-value pair stored within the client. Every subsequent request from the client includes all of the previous cookie values.
To set a cookie value, override the page cookie value within the %CSP.Response object:
Class MyApp.Page Extends %CSP.Page

ClassMethod OnPreHTTP() As %Boolean
    Do %response.SetCookie("UserName",name)
     Quit 1
The server can later retrieve this information using the %CSP.Request object's Cookies property.
Storing information within a cookie is useful for information that you want to remember past the end of a session. (To do this, you must set an expiration date as, by default, cookies end when the browser closes.) For example, you could remember a username in a cookie so that in a subsequent session they would not have to reenter this information. See an HTML manual for information regarding different kinds of cookies and their formats.
Storing Data in the Session — Data Property
As discussed in an earlier section, you can store state information in the session %CSP.Session object using its Data property. Any information placed into the %session object is available for the remainder of the current session (or until it is removed from the %session object).
The %session object is a good place to store simple information that is useful across the duration of a session, such as the current user's name. The %session object is not good for information that must live beyond the scope of the current session. It is also not a good place for information that is dependent on the navigation path taken by the user through the application. Users are typically free to jump about web applications at will and this can lead to trouble if an application makes assumptions about the specific path taken by a user.
Storing Data in the Database
If you have more complex information to associate with a user, it is probably best to store it within the built-in Caché database. One way to do this is to define one or more persistent classes within the database and store their object ID values within the %session object for subsequent access.
Server Context Preservation — Preserve Property
Typically the only processing context preserved by the CSP server from one request to the next is held within the %session object. The CSP server provides a mechanism for preserving the entire processing context variables, instantiated objects, database locks, open devices between requests. This is referred to as context preserving mode. You can turn context preservation on or off within a CSP application at any time by setting the value of the %CSP.Session object Preserve property. Note that tying a process to one session results in a lack of scalability.
Authentication and Encryption
It is fairly common to place state information on pages sent to the HTTP client. When subsequent requests are made from these pages, the state information is sent back to the server. Many times, it is important that state information be placed on a web page in such a way that a) viewers of the HTTP source cannot determine the value of the state information and that, b) the server can verify that the returning information was, in fact, send out from the same server and session. Via its encryption services, CSP provides an easy-to-use mechanism to accomplish this.
Session Key
CSP can encrypt and decrypt data on the server using an encryption key. Every CSP session has a unique session key (accessible via the %CSP.Session object Key property) that is used to encrypt data for a session. This mechanism is secure because the session key is never sent to an HTTP client; it remains on the CSP server as part of the %CSP.Session object.
You can manually encrypt values on the server using the Encrypt method of the %CSP.Page class. You can subsequently decrypt this value using the Decrypt method.
Encrypted URLs and CSPToken
In certain circumstances (described below) a class generated from a .csp file automatically encrypts URL values sent to the client (for manually created classes, you must invoke the Link method of the %CSP.Page class to perform this action).
For example, suppose a .csp file contains an anchor tag defining a link to another page:
<a href="page2.csp?PI=314159">Page 2</a>
If this URL is encrypted, the following may be sent to the client:
<a href="page2.csp?CSPToken=8762KJH987JLJ">Page 2</a>
When the user selects this link, the encrypted parameter CSPToken is sent to the CSP server. The server then decrypts it and place its decrypted contents into the %request object. If the encrypted value has been modified or sent from a different session then the server throws an error. You can use the %CSP.Request class IsEncrypted method to determine whether a parameter value was originally encrypted.
The CSP compiler automatically detects all the places where a URL can occur within an HTML document and performs encryption as needed (based on the class parameters of the target page as described in the following section). If you are creating a page programmatically you can get the same behavior using the Link method of the %CSP.Page class.
If you are passing a link as an argument to a function, always use the Link method of the %CSP.Page class, rather than the #url()# directive, as in the following example:
This example of using #url()# as an argument to a function does not work:
If you need to provide an encrypted URL within a .csp file in a place that is not detected by the CSP compiler, use the #url()# directive. For example, in a client-side JavaScript function, where the link is a parameter, you can use:
<script language=JavaScript>
function NextPage()
    // jump to next page
    CSPPage.document.location = '#url(nextpage.csp)#';
Private Pages
CSP provides the notion of a private page. A private page can only be navigated to from another page within the same CSP session. Private pages are useful for applications where you want to restrict access to certain pages.
For example, suppose there is a private page called private.csp (one of the CSP sample pages). A user cannot navigate directly to private.csp (for example, by typing in its URL). A user can only navigate to private.csp from a link contained within another CSP page. The link contained in the referring CSP page cannot be an absolute URL, starting with http://. Only paths relative to the referring page are properly encrypted/tokenized by the private pages method. That is: The first two links below pass the same token to the target private page, test2.csp.
<A HREF='test2.csp'>Link to private page - relative path</A> <BR>
<A HREF='/csp/samples/test2.csp'>
       Link to private page - full application path</A> <BR>
This link is hashed differently and fails access.
<A HREF='http://myserver/csp/samples/test2.csp'>
        Link to private page - absolute path</A>
The user also cannot bookmark a private page for later use because the encrypted token used to protect the private page is only valid for the current session.
Private pages work as follows. The %CSP.Page subclass responsible for the page has its class parameter PRIVATE set to 1. A URL requesting this page must contain a valid, encrypted CSPToken value in its query string. Any links to this page processed by CSP automatically have an encrypted CSPToken value.
Encoded URL Parameters
In a manner similar to private pages, you can specify that the URL parameters of a CSP page are to be encoded by setting the value of the %CSP.Page class parameter ENCODED. ENCODED can be set to 0, 1, or 2. Any links to a page whose ENCODED class parameter is 1 or 2 automatically have any URL parameters encoded within the encrypted CSPToken value. If ENCODED is set to 2, then values must be encoded; if 1, it is possible to mix encoded and unencoded values.
The three settings for ENCRYPTED are:
Note that because ENCODED=2 removes unencrypted parameters from the url it can disable components such as the Zen <form> element.
Example of ENCODED=2
For example, suppose you have two .csp pages. One page (list.csp) displays a list of bank accounts as hyper-links and a second page (account.csp) displays information about a specific account. account.csp expects a URL parameter named ACCOUNTID to determine which account to display. We do not want to publish account numbers on the client and we do not want unauthorized access to account.csp or the ability to display any other account number. We can do this by setting the account.csp ENCODED parameter to 2. Here are the relevant .csp files:
Source for list.csp
Select an account:<br>
<a href="account.csp?ACCOUNTID=100">Checking</a>
<a href="account.csp?ACCOUNTID=105">Saving</a>
Source for account.csp
<csp:class private=1 encoded=2>
Account Balance: <b>$#(..GetBalance())#</b>

<script language="Cache" method="GetBalance" arguments=""
    // server-side method to lookup account balance
    New id
    Set id = $Get(%request.Data("ACCOUNTID",1))
    If (id = 100) {
        Quit 157
    ElseIf (id = 105) {
        Quit 11987
    Quit 0

The CSP server sends the following HTML to the client when list.csp is requested:

Select an account:<br>
<a href="account.csp?CSPToken=fSVnWw0jKIs">Checking</a>
<a href="account.csp?CSPToken=1tLL6NKgysXi">Saving</a>
Notice that only the encrypted values for ACCOUNTID are sent to the client.
When account.csp is processed, it sees the decrypted value for ACCOUNTID (referenced in its GetBalance method).
Example of ENCODED=1
The difference between ENCODED=2 and ENCODED=1 is that with a ENCODED=2, any text that is added to the URL in an unencrypted form is thrown away. If ENCODED=1 is used, then the unencrypted text is passed through to the page. The page can then include code that specifies what to do with this unencrypted text.
The samples pages protected.csp and protectedentry.csp show an example of using ENCODED=1. The source for protected.csp shows that it checks to see if anything has been added to the URL that is not encrypted. If there is anything that is not encrypted, the page displays a scrolling marquee that says HACKER ALERT!
To see this, go the samples page.
  1. Double-click protectedentry.csp.
  2. Enter 500 in the BALANCE: field
  3. The protected.csp page is displayed saying Your Account Balance is: 500
  4. Notice that the URL contains an encrypted CSPToken (everything after CSPTaken=). This is the 500 that you entered encrypted.
  5. Navigate to the end of this URL and enter &BALANCE=8000 and press Enter.
  6. The protected.csp page is displayed. It accepted the unencrypted addition to the URL and acted on it by displaying the HACKER ALERT! marquee. If ENCODED had been set to 2, it would have ignored the unencrypted entry.
Authentication Sharing Strategies
This section describes how to create a set of applications to work as a group in two ways:
This section describes the following:
Authentication Approaches
This section describes the following approaches to authentication. Options to implement them are found on the [Home] > [Security] > [Web Applications] page.
One-Time Sharing: Login Cookies
Login Cookies hold information about the most recently logged-in user. If you want to keep your users from having to log in too often, but you want your applications to remain distinct and unconnected, use Login Cookies.
For Login Cookies, place each application in a separate session. Then authentication is shared only when an application is entered for the first time. Login Cookies applications do not form a group. So after login, changes in authentication in one application do not affect the other applications.
When a user logs in with a password, that authentication is saved in a cookie. If another application with Login Cookies enabled is entered (for the first time), it uses the authentication saved in the cookie. If the user jumps to a third application (for the first time) which does not have Login Cookies enabled, the user must enter a username/password.
See the section Considerations in Choosing Your Strategy for more information for deciding what strategy to use.
When deciding whether or not to use Login Cookies, here are some considerations:
Continuous Sharing: Authentication Groups By ID or By Session
With group sharing, the authentication of the group's applications moves as a unit. If a user in an application in a group logs in as a new user, all the applications move to that user. If one application logs out, they are all logged out.
Applications can be grouped together in two ways: By Session and By ID. By-Session groups share authentication and data. By-ID groups share authentication only.
Applications are run in CSP sessions. Each session has a security context associated with it. For more on CSP sessions, see the section About CSP Sessions in this book.
If several applications are placed in the same session, they share authentication. This is called a By-Session group (session-sharing). In addition, the session may contain user defined data. Applications can be made to share a session by having their Application Cookie Path match exactly or by using the CSPSHARE=1 flag when jumping via a link from one application to another.
Applications can be grouped by assigning the applications matching group identifiers. This is called a By-ID group. The group shares a security context. The applications are usually in separate sessions. The group does not manage user data, only authentication.
See the section Considerations in Choosing Your Strategy for more information.
By-Session Groups (Session-Sharing)
Sharing a session has potential issues. Session events are picked up only from the original CSP application. If the link goes to a page that requires different session events, then these session events do not run. Also, running a page in another CSP application with a different security context may require a login; the login might alter the security context of running pages in the original CSP application. Before choosing to use By-Session groups, please read Considerations in Choosing Your Strategy below.
When applications share a session, they share both authentication and data via the session object. There are two ways to share a session:
  1. Session Cookie Path: All applications with exactly-matching session cookie paths are placed into the same session.
  2. CSPSHARE: Putting CSPSHARE=1 in the link to the application page. Use this when the source application's Session Cookie Path is different from the target's Session Cookie Path.
If By-Session sharing is required, then the best solution is to name all applications so they can be given the same Session Cookie Path. You may have to rename your applications because the Session Cookie Path must be a substring of the application name.
If this cannot be done and session sharing is required, then you have to put the CSPSHARE parameter in links that jump from one application to another. The target application page is placed in the same session as the source application's pages. The source's session is determined either from the CSPCHD parameter or the session cookie.
See the section Considerations in Choosing Your Strategy for more information.
By-ID Groups
You can group your applications by giving them a group name in the Group by Id field on the [Home] > [Security] > [Web Application] page. This name groups opened applications together. Groups are in different sessions. The applications do not share data.
The group name is attached to an application, not a namespace. Applications with the same group name share authentication regardless of namespace.
Authentication is shared within a single browser only.
See the section Considerations in Choosing Your Strategy for more information.
When CSP receives a request from a browser it does a series of checks to see if the sessionId it receives is a valid one. These checks include:
If you pass a CSPSHARE=1 query parameter, CPS turns off this checking. Then you can construct a link to another CSP application and include the current sessionId, using CSPCHD=sessionId, so that this link runs in the same session as your existing page. In addition, if CSPSHARE=1 when you construct a link, CSP automatically inserts the CSPCHD=sessionId in to the link. If you manually insert a link with Write statements, you may need to insert the sessionId manually.
For example, if you have an application that requests an http page from an https page (or an https page from an http page), add CSPSHARE=1 to the link as follows:
CSPSHARE=1 forces the link construction to add CSPCHD to share the sessionId even if Caché detects that cookies are enabled.
See the section Considerations about CSPSHARE for more information.
Authentication Architecture
Security Context & Sticky Logins
Applications are run in sessions. A session requires a security context in which to run an application. The security context contains the authentication state.
By-Sessions and By-ID Groups have a sticky login which remembers the security context of the last application used in the session or group. If a user in a group application logs in as a different user, the sticky login is updated. (The sticky login is not updated if the user logs in to an unauthenticated application.)
When jumping to an application in a session, the session attempts to use the sticky login appropriate for the target application. If the sticky login does not match the session's current security context and the application can accept the authentication method in the sticky login, the session's security context is switched to that in the sticky context.
A session's sticky login is lost when the session is ended. The group's sticky login is lost when all the sessions containing any of the group's applications are ended.
After the initial login, a group has an associated sticky login object which it attempts to use when entering one of the group's applications. The sticky login is not updated when an application in the group is entered as UnknownUser as this would have the effect of moving all other applications in the group to the unauthenticated security context.
If the sticky login contains a two-factor authenticated user, that two-factor authentication is used for non-two-factor applications, so long as the username authentication matches in the two applications.
Cascading Authentication
The CSP Server uses precedence when attempting to obtain authentication information for an application. It attempts to get new authentication information in each of the following events:
It attempts to get new authentication information sequentially in the following order:
  1. Explicit Login: Checks to see if the user entered an authenticated username/password. If they did, the system updates the application's authentication group's context. (This sets the group's Sticky Login.)
  2. Sticky Login: Get the Application's group's sticky context. If no sticky login and group-by-session, use session's current context.
  3. Login Cookie: Use if one exists and is enabled for this application.
  4. Unauthenticated: Use Unknown User if enabled for application.
  5. Put up Login Page: If all the above fail, then request username/password from user. If called from the %CSP.Session API, then only username/password is tried. After login, update the group's sticky login unless just logged in as UnknownUser.
Logout or End Session
Authentication is lost when a session is logged out or ended. You can use the following %CSP.Session methods to logout or end a session:
Recommended: CacheLogout=end
The recommended way to logout of a CSP session is to link to the application home page passing a URL that contains the string, CacheLogout=end. This ends the current session – releases any license acquired, deletes existing session data, and removes the security context of the session – before it attempts to run the home page.
If this CSP application requires authentication, there is no session and no authenticated user. In this case, Caché does not run the home page logic but displays the login page instead. When the user submits a valid login this starts this new session and then displays the home page.
Set EndSession? =1
This kills the session. The session's sticky context is destroyed. OnEndSession is called. If the session contains a By-Session group, then the group is destroyed. If the session contains a By-Id application, then that application is removed from the group which continues to exist unless this was the only application in the group. Login cookies are unaffected. By-Session groups lose their data. However, for By-Id groups, the sticky-login for the group is unaffected by a singular destruction and the other members of the group remain logged in.
In addition, for By-Session groups, the destruction disperses the members of the group and if the member applications are reentered, it cannot be guaranteed that they will be reintegrated into the same new session or (if they were grouped using CSPSHARE) sent to diverse sessions.
Session Logout
The session is logged out. Its sticky context is destroyed. If the session contains a by-session group, then all the applications in the group lose their authentication. If the session contains an application from a by-id group, then group loses its sticky context and all the applications in the group are logged out.
In addition, OnLogout is called. The login cookie is destroyed.
The session continues to exist, so data is retained for By-Session groups.
Session Logout All
It is possible to log out all session currently authenticated as a particular user.
This zaps the login cookie.
The sessions continue to exist but have not authentication.
Considerations in Choosing Your Strategy
This section contains some points to consider when you are choosing your strategy. See the section One Time Sharing: Login Cookies for more information for deciding what strategy to use.
Considerations for Groups
This section contains some points to consider when you are creating authentication groups.
  1. Use session-sharing only when you decide that data must be shared via the session object. By-ID and Login Cookies-sharing are more robust and predictable.
  2. When creating groups, be as consistent as possible to create uniform behavior for your targeted users. Do not place an application in both a By-ID group and a By-Session group. Using the different authentication strategies may cause unexpected behavior. By-ID takes precedence over By-Session. So if an application has both, it stays synchronized By-ID.
  3. Use the same authentication types for all members of the group. In particular, if some applications in the group allow Login Cookies and others do not, then entering the group via a username/password authenticates the entire group, whereas entering it via a login cookie authenticates only some of the applications. This can cause confusion among your users about why sometime a login is required and other times not.
  4. The CSP server considers every application to be in an Authentication Group. A lone application in a session forms a single-entity By-Session authentication group.)
  5. Try not to put unauthenticated-only applications in By-ID groups.
  6. By-Session groups are fragile; using By-ID is a more robust approach. Since all the information about a group, including its shared data, is contained in a single session, the group can easily be lost. This is because a session can time-out, that is, after a specific amount of time the session is automatically destroyed. If the user steps away from his computer or uses an application which is not in the By-Session group, the session may timeout. If one of the applications in the group marks ENDSESSION=1, the group is dispersed.
  7. If the browser has open tabs containing pages from the dispersed applications, clicking on them may require multiple logins, especially if they were originally grouped using CSPSHARE=1. In any case, the data from the original session is permanently gone.
  8. When a group loses its authentication, refreshing or going to an open page from a group application requires that the user re-login.
  9. Ending a session containing a By-Session application requires that the user re-login when refreshing any page of any application in that by-session group. Killing a session containing a By-ID application does not require any logins unless that session's application was the only member of the group.
  10. Logging out a session logs out all members of the session's group, even if they are in different sessions. Refreshing any of the group's pages requires a new login. However, for By-ID groups, one login logs in the entire group. For By-Session groups, one login logs in the entire group as long the CSP Gateway is able to direct the dispersed applications back to a newly constructed session object.
  11. Logging out does not destroy the session, so any session data continues to exist.
  12. One cannot have same application logged in to two different users in different tabs of the same browser.
  13. Authentication is shared within a single browser only. This runtime identifier is stored in the %Session object.
  14. Grouping allows you to share authentication with users that are in the same group (By-ID) or the same session (By-Session). If you want to share authentication from applications that are outside your specified group, use Login Cookies. If you want to send authentication to applications outside your specified group, use CSPSHARE=1. (See the section “Considerations about CSPSHARE” in this book.)
Considerations about CSPSHARE
Use CSPSHARE as a last resort.
By-Session application links do not need CSPSHARE=1 in the following cases:
Sharing Data
By-Session groups can share data via the session object.
By-ID groups must manage their own data. If the data is stored, for example, in a global, the data could be keyed using the current user, $Username, or by the group's runtime ID. The CSP Server assigns each browser a browser-id cookie. When a By-Id group is created it is assigned a key which is the browser ID concatenated with the group ID. This creates a unique key, %CSP.Session.BrowserId, which can be used as a key under which to store data.