Skip to main content

Authentication Sharing Strategies

This page describes how to configure multiple CSP-based web 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.

Authentication Approaches

The following approaches are available for sharing authentication.

  • One-time sharing of login cookies. All applications with the same id share authentication.

  • Continuous sharing by sharing sessions (having a By-Session group). In this system, 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 are run in sessions. Each session has a security context associated with it.

    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.

  • Continuous sharing by matching group identifiers. This is called a By-ID group. In this system, the group shares a security context. The applications are usually in separate sessions.


    In this system, the group does not manage user data, only authentication.

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. This corresponds to the web application option 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.

By-Session Groups (Session-Sharing)

One way to share authentication and data between applications is to define a by-Session group). In this system, 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.

When applications share a session, they share both authentication and data via the session object.

Sharing a session has potential issues. Session events are picked up only from the original web 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 web application with a different security context may require a login; the login might alter the security context of running pages in the original web application. Before choosing to use By-Session groups, please read Considerations in Choosing Your Strategy below.

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.


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, a sessionId cannot be passed through a URL, even if the application has been configured to only use cookies, if the “Prevent Login CSSRF attack” option has been checked. InterSystems recommends employing this behavior.

If the “Prevent Login CSSRF attack” option has not been checked and CSPSHARE=1, CSP performs no checks and a user can construct a link to another web 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 InterSystems IRIS detects that cookies are enabled.

See Considerations about CSPSHARE for more information.

By-ID Groups

Another way to share authentication and data between applications is to define a by-ID group, as follows:

  1. Navigating to System Administration > Security > Applications > Web Applications on the Management Portal.

  2. Give the applications a common 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.

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:

  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.SessionOpens in a new tab API, then only username/password is tried. After login, update the group’s sticky login unless just logged in as UnknownUser.

Log Out 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 log out 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 web application requires authentication, there is no session and no authenticated user. In this case, IRIS 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.

Considerations for Login Cookies

When deciding whether or not to share via Login Cookies, consider the following points:

  • 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.

Considerations for Groups

This section contains some points to consider when you are creating authentication groups to share authentication.

  • 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 Web 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 Considerations about CSPSHARE.)

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.

FeedbackOpens in a new tab