CSP Session Management

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.SessionOpens in a new tab object. The CSP server makes this object available via the 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:

Creates a new session ID number.
Performs licensing checks, as appropriate.
Creates a new instance of the %CSP.SessionOpens in a new tab object (which is persistent).
Invokes the OnStartSession method of the current session event class (if present).
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.SessionOpens in a new tab 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.SessionOpens in a new tab 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.)

The session times out because it did not receive any requests within the specified session timeout period.
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.
The session is explicitly ended programmatically on the server (by setting the %CSP.SessionOpens in a new tab 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.
The session can be logged out using the %CSP.SessionOpens in a new tab object's Logout method

When a session ends, the CSP server deletes the persistent %CSP.SessionOpens in a new tab 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
CacheUserName	From the login page, contains the username to log in; for example, CacheUserName="fred"
CachePassword	From the login page, contains the password of the user designated by CacheUserName; for example, CachePassword="fredspwd".
CacheOldPassword	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.
CacheRepeatPassword	Not used.
CacheLogin	Not used.
CacheLogout	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	CacheSecurityToken contains the value of a submitted security token from the Login Security Token page, such as CacheSecurityToken="12345678".
CacheSecuritySubmit	The presence of this name indicates that the user is submitting a security token whose value is associated with CacheSecurityToken.
CacheSecurityCancel	The presence of this name indicates that the user has cancelled out of the Login Security Token page.
CacheLoginPage	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.
CacheNoRedirect	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.SessionOpens in a new tab 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.SessionOpens in a new tab 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.SessionOpens in a new tab object Data property in the same way you would use any other 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.SessionOpens in a new tab object:

 Write $Get(%session.Data("MyData")) // this should print 22

The ability to store application-specific data within the %CSP.SessionOpens in a new tab 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.SessionOpens in a new tab 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 an 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 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 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 set to 900 seconds (15 minutes). You can change this default for a CSP application in the Management Portal. Navigate to System Administration > Security > Applications > Web Applications. Select the application and click Edit. You can also set it from within an application by setting the value of the %CSP.SessionOpens in a new tab 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.SessionEventsOpens in a new tab class. You can specify the name of this class via the EventClass property of the %CSP.SessionOpens in a new tab 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 on individual pages using either hidden form fields or URL parameters
Storing data in cookies on the client
Storing data in the %CSP.SessionOpens in a new tab object on the server
Storing data within the Caché database

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:

<form>
<input type="HIDDEN" name="DATA" value="#(data)#">
<input type="SUBMIT">
</form>

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.ResponseOpens in a new tab 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.RequestOpens in a new tab 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.SessionOpens in a new tab 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.SessionOpens in a new tab 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.SessionOpens in a new tab 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.SessionOpens in a new tab object.

You can manually encrypt values on the server using the Encrypt method of the %CSP.PageOpens in a new tab 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.PageOpens in a new tab 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.RequestOpens in a new tab 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.PageOpens in a new tab class.

If you are passing a link as an argument to a function, always use the Link method of the %CSP.PageOpens in a new tab class, rather than the #url()# directive, as in the following example:

window.showModalDialog('#(..Link("locks.csp"))#','',windowFeatures);

This example of using #url()# as an argument to a function does not work:

window.showModalDialog('#url(locks.csp)#','',windowFeatures);

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)#';
}
</script>

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.PageOpens in a new tab 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.PageOpens in a new tab 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:

ENCODED=0 — Query parameters are not encrypted
ENCODED=1 — Query parameters are encrypted and passed within CSPToken
ENCODED=2 — Same as '1' except any unencrypted parameters are removed from the %request object before calling the Page method. This ensures that only encrypted parameter are available in the %CSP.RequestOpens in a new tab object.

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

<html>
<body>
Select an account:<br>
<a href="account.csp?ACCOUNTID=100">Checking</a>
<a href="account.csp?ACCOUNTID=105">Saving</a>
</body>
</html>

Source for account.csp

<html>
<csp:class private=1 encoded=2>
<body>
Account Balance: <b>$#(..GetBalance())#</b>
</body>

<script language="Cache" method="GetBalance" arguments=""
        returntype="%Integer">
    // 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
</script>

</html>

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

<html>
<body>

Select an account:<br>
<a href="account.csp?CSPToken=fSVnWw0jKIs">Checking</a>
<a href="account.csp?CSPToken=1tLL6NKgysXi">Saving</a>
</body>
</html>

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.cspOpens in a new tab 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 pageOpens in a new tab.

Double-click protectedentry.cspOpens in a new tab.
Enter 500 in the BALANCE: field
Click View Balance
The protected.csp page is displayed saying Your Account Balance is: 500
Notice that the URL contains an encrypted CSPToken (everything after CSPTaken=). This is the 500 that you entered encrypted.
Navigate to the end of this URL and enter &BALANCE=8000 and press Enter.
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:

Sharing authentication: If applications do not share authentication, the user must log in to each application that is linked to by another application separately. Shared authentication allows the user to enter all linked applications with a single login.
Sharing data: The applications may want to share and to coordinate global state information.

This section describes the following:

Authentication Approaches

This section describes the following approaches to authentication. Options to implement them are found in the Management Portal by navigating to System Administration > Security > Applications > Web Applications.

One-Time Sharing: Login Cookies. All applications with the same id share authentication. This corresponds to the CSP Application option Login Cookies.
Continuous Sharing: Authentication Groups By ID or Session
- By Session. This corresponds to two CSP Application options. The Session Cookie Path option makes applications with the same session-path-cookie share a session and its authentication. If the CSPSHARE option is set as CSPSHARE=1, then when the user clicks a link (in a source application) to a target application, then the target application is placed in the same session as the source application

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:

The login cookie is updated to a new user whenever the user logs in with a password.
Login cookies are not generated for an unauthenticated login (as UnknownUser).
Login cookies are not generated when logging in through API calls.
Login cookie sessions are independent once that session has been authenticated. So logging out or timing out in one session does not affect the other sessions.
Authentication from a Login-Cookie application cannot be shared with a password-only (non-Login-Cookie) application. For authenticated applications in a group, for consistent behavior, use Login Cookies for all or for none.

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:

Session Cookie Path: All applications with exactly-matching session cookie paths are placed into the same session.
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 navigating to System Administration > Security > Applications > Web Applications on the Management Portal and giving them a group name in the Group by Id field. 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.

CSPSHARE

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:

Whether the User-Agent is the same as that of previous requests from this sessionId
If cookies are being used, whether this sessionId comes from a cookie or from a CSPCHD parameter

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:

#(..Link(%request.URL_"?CSPSHARE=1"))#

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:

For the first request to a new session;
When there is an application change within the session;
When the application is part of a By-id group and the session's current security context does not match that of the group's sticky context;
When the request contains a username/password pair.

It attempts to get new authentication information sequentially in the following order:

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.)
Sticky Login: Get the Application's group's sticky context. If no sticky login and group-by-session, use session's current context.
Login Cookie: Use if one exists and is enabled for this application.
Unauthenticated: Use Unknown User if enabled for application.
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.SessionOpens in a new tab 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.

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.
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.
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.
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.)
Try not to put unauthenticated-only applications in By-ID groups.
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.
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.
When a group loses its authentication, refreshing or going to an open page from a group application requires that the user re-login.
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.
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.
Logging out does not destroy the session, so any session data continues to exist.
One cannot have same application logged in to two different users in different tabs of the same browser.
Authentication is shared within a single browser only. This runtime identifier is stored in the %Session object.
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:

If the source and target applications have the same group ID.
If the target page is in the same application as the source page.
If the target page application's Session Cookie Path matches the source application's Session Cookie Path.

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.