Logi SecureKey Authentication
Logi SecureKey Authentication technology provides integration for applications requiring secure access to a Logi application or embedded Logi components. It enables a "single sign-on" environment while enhancing security: user authorization is established and requests are made to Logi applications or embedded components using a special security key. This topic discusses the use of SecureKey Authentication.
- Why use SecureKey Authentication?
- How SecureKey Authentication Works
- Configuring SecureKey in a Logi Application
- Getting User Roles and Rights
- Configuring the Parent Application
- Working within NAT or Proxy Environments
- Managing SecureKey Sessions
Logi SecureKey is an extension of Logi Security; if you're unfamiliar with Logi Security, first read Introduction to Logi Security.
Logi SecureKey Authentication is provided for use in scenarios where a Logi application or Logi components are integrated with or embedded into a non-Logi application (the "Parent" application), which conducts the initial user authentication.
Sometimes called "single sign-on", this arrangement allows users to login once to the Parent application and yet have their security information propagated to other integrated applications, creating a seamless and secure user experience. This, of course, means that users can't be allowed to "go around" the Parent application and directly access the other applications. In the stateless world of web applications, this requires some special mechanisms to ensure security and they are provided for Logi applications through our SecureKey technology.
The "authentication" part of SecureKey Authentication refers to the method used by the two applications to verify the validity of requests from users; this is a secondary authentication that occurs separately from the typical standard user login authentication.
Generally, there are four steps involved in the typical SecureKey Authentication transaction. In the following example scenario, a Logi application is embedded in an iFrame within its Parent application.
- The Parent application initially authenticates the user (the "single sign-on"), as shown above. The user successfully logs into the Parent application; the exact method it uses to determine that a user is valid is irrelevant to this process, except that user Roles and/or Rights, if applicable, should be retrieved as part of the authentication.
- After the Parent application authenticates the user, the page that includes the embedded Logi application loads, as shown above. The Parent application sends the Logi application a request for a SecureKey token. The request includes the user ID, any user Roles and/or Rights, and (pre-v12.1.188) the user's machine IP address (the "client browser IP address").
When it receives the request for a SecureKey token, the Logi application first verifies that the request came from a valid source. This is done by automatically determining the Parent app's server IP address and ensuring that it's in a pre-configured list of approved addresses. If so, the Logi application stores the user information from the request and returns a unique SecureKey token to the Parent application.
- The Parent application then sends the original report request to the Logi application, appending the SecureKey token.
- Upon receiving the request, the Logi application automatically determines the client browser IP address and uses it, along with the SecureKey token, to authenticate the request. If authenticated, a session is started for the user and any Roles and Rights (stored in Step #2) associated with the token are used to authorize access to the correct reports, data, and other resources. The requested report is then generated and returned into the iFrame.
When the Logi application session is started for the user, the SecureKey tokenexpires and cannot be used again. Any subsequent reports requested from within the context of the Logi application will use the user's session to control access to reports, data, and resources. The user is then communicating directly from his or her browser to the Logi application for reports and the Parent application is no longer involved, as long as the Logi app session persists.
Developers need to ensure that the Parent application does not try to reuse the expired SecureKey token!
If the user's Logi application session ends, and he or she subsequently wants to access reports again, then the process of requesting and using a new SecureKey token will have to be repeated.
Once a SecureKey token is used, it cannot be used again in a different session, and "sharing" tokens across clients isn't possible, as the client browser IP address is referenced within the key when it's created, making it valid only for the client that made the initial request.
SecureKey Information Storage
Normally, the information associated with a SecureKey token (User Name, Roles, Rights, browser IP address, etc.) is stored as a web server "application scope" variable.
However, if you're using a clustered server configuration, you can specify a physical folder for temporary storage of SecureKey information as XML files. Using a shared network folder for this purpose allows common access to the SecureKey information by the clustered servers. This shared folder is specified in the SecureKey Shared Folder attribute of the Security element, in the Logi application's _Settings definition. The SecureKey files created by this option are deleted whenever the automatic "temporary cache file clean-up" occurs (which is configurable - see Temporary Cache File Management).
Implementing SecureKey Authentication in a Logi application builds upon existing techniques for implementing Logi Security.
In the example shown above, a Security element has been added to the application's _Settings definition and configured with typical settings for a SecureKey implementation. The relevant attributes are:
|Authentication Source||(Required) Select SecureKey from the drop-down list of available values.|
|Authentication Client Addresses||
Specifies the IP address of the web/application server making the SecureKey requests (not the end-user's IP address), identified as the "Parent App Server" in the first four images above.
This value can be determined by "pinging" the application server from the web server hosting your Logi applications. If one computer serves both purposes and the Logi apps are being called using localhost in the URL, enter 127.0.0.1 for this value (or ::1 in IPv6). If multiple servers will be making SecureKey requests, multiple IP addresses can be entered here, separated by commas.
Computer names may be used, and IP addresses with wildcard masks. To use wildcards, specify an IP address, the space character, then the wildcard mask. |
For example, to allow all addresses in the range of 172.16.*.*, specify:
We do not recommend using partial wildcard masks; however, if this set up is absolutely required, you can provide a partial mask as long as it conforms to the pattern where the last part (3 digits) in the IP is less than the last part (3 digits) in the mask. See below for an example.
Generic information is available about defining IP address wildcard masks. SecureKey requests from servers with IP addresses not in this Authentication Client Addresses list are rejected.
|Cache Roles and Rights||When Authentication Source is set to SecureKey and this value is left blank, the setting defaults to Session; SecureKey will not work if it's set to False.|
|Restart Session||When set to True, all security-related session variables are cleared with each new login attempt. This prevents session variables that were established during one user's session from being used during a subsequent user's session.|
|Specifies a database Connection element ID, enabling the temporary storage of SecureKey tokens in a relational database rather than in the file system. The temporary values are stored in a database table named rdSecureKey, which is automatically created the first time a SecureKey is used. See this section below for more information.|
|SecureKey Shared Folder||As discussed earlier, this attribute allows SecureKey to be used with clustered server configurations in web farms and web gardens by saving information in commonly-accessible files. The account used by (or impersonated by) the Logi application must have network access rights to read, write, and delete files in this folder. Set the SecureKey Shared Folder value to a network path, such as: //mySharedServer/SecureKeyFolder. Files in the SecureKey shared folder are automatically deleted over time, so do not use this folder to also store other files. If using this attribute for development diagnostics, enter a fully-qualified path on the web server. You can use the @Function.AppPhysicalPath~ token here as part of the path.|
|Security Enabled||Must be set to True to enable security.|
About IP Addresses
Due to the stateless nature of browser interactions, IP addresses play an important role in ensuring security. Developers are occasionally confused about the two IP addresses used with SecureKey authentication, so here's some additional explanation:
Authentication Client Address
This address ensures that the Parent application and the Logi application are allowed to talk to one another. It's the IP address of the server hosting the Parent application. It is not the IP address of the end-user computer used to request reports through the Parent application.
Computer names may be used, and IP addresses with wildcard masks. To use wildcards, specify an IP address, the space character, then the wildcard mask. For example, to allow all addresses in the range of 172.16.*.*, specify: 172.16.0.0 0.0.255.255.
This address is never passed in a URL when requesting a SecureKey from the Logi application. Instead, the Logi application automatically determines the address of incoming SecureKey requests from the Parent application and, if it matches one of the IP addresses specified in the Security element's Authentication Client Address attribute, then the Logi application will accept and begin processing the SecureKey request.
We do not recommend using partial wildcard masks; however, if this set up is absolutely required, you can provide a partial mask as long as it conforms to the pattern where the last part (3 digits) in the IP is less than the last part (3 digits) in the mask. For example:
10.158.48.128 0.0.0.218 will work, but
10.158.48.128 0.0.0.105 will not work.
You can use the the DHCP service, provided here, to set max and min IPs within the desired subnet.
Client Browser Address
This address is used to verify that each report request to the Logi application is coming from a source that has been authenticated by the Parent application. It's the IP address of the end-user computer used to request reports through the Parent application. It is not the IP address of the server hosting the Parent application.
This address is passed in the URL of every request for a SecureKey. It should not be specified in the Security element's Authentication Client Address attribute. The Logi application automatically determines the address of incoming report requests and, if it matches the IP addresses associated with the specified SecureKey, access to the Logi application is allowed.
This query string value is no longer required.
During development, it's not at all unusual for the Parent application to be hosted by a web server that's on the same machine as the browser used to make test requests. In this case, the Authentication Client Address and the Client Browser Address are very likely going to be the same, such as 127.0.0.1 or ::1. This can contribute to the confusion over these two addresses, and perhaps produce a rude surprise when the applications are deployed and the addresses change. We highly recommend testing SecureKey implementations using a separate machine to represent the "end-user machine" in order to avoid this confusion.
In clustered environments, the SecureKey Shared Folder is usually used to store SecureKeys so that all computers in the cluster are aware of them. It's also possible to store them instead in a database table, for additional security and to get the file system out of the process. The Security element's SecureKey Database Connection ID attribute is used to enable the feature and to provide a connection to the database, which must be on one of these supported database servers:
- MS SQL Server
The table, rdSecureKey, is automatically created in the database when the feature is enabled and the first SecureKey request is received. SQL scripts for creating the table are also available in <applicationFolder>\rdTemplate\rdSecureKey. Temporary SecureKey records, like the temporary files in the file system, are automatically deleted from the table after they expire.
Do not set the SecureKey Sessionless attribute to True when enabling this feature; an error will result.
Your Logi application may need to use any security Roles or Rights available as part of the SecureKey information. Various security-related elements are used for this purpose, as follows:
If user Roles information is included in the SecureKey request from the Parent application (as described in the following section), then subsequent report requests will cause that information to be automatically available in the Security element, as shown above, left.
If user Roles information is not included in the SecureKey request but is desired, it can still be retrieved from a datasource, using a User Roles element and a datalayer, as shown above, right. The data returned into the datalayer should have either a Role value in the first column of each row, or be a single row with one column containing multiple Roles in a comma-delimited list.
If user Rights information is included in the SecureKey request from the Parent application (as described in the following section), then subsequent report requests will cause that information to also be automatically available in the Security element.
If user Rights information is not included in the SecureKey request but is desired, it can be retrieved in several ways, all of which begin with the addition of the User Rights element:
The examples shown above include a User Roles element, but it's not necessary if Roles are supplied to the Security element via the SecureKey request. The separate techniques and elements used to retrieve the Rights are described below:
|Rights From Roles||Builds the list of Rights directly from the Roles values. The Roles and Rights are the same.|
|Rights From DataLayer||Builds the list of Rights directly from its child datalayer. The data returned should include a Right in the first column of each row, or multiple Rights in a single row in a comma-separated list.|
Right From Role
Defines each Right individually, with one Right From Role element for each right. The element's ID is the Right value, which corresponds to Security Right ID attributes in elements in report definitions. Right From Role works with user Roles: if a user has a Role that is returned by this element's child datalayer, then he is allowed the Right specified by the element's ID. The child datalayer should retrieve data with a Role value in the first column of each row, or multiple Roles in a single row in a comma-separated list.
These elements may be used in any combination; the Rights
retrieved by each are combined together into a comprehensive rights list.
The Parent application is responsible for authenticating the user (the "single sign-on") when he or she first connects. The authentication process should produce a valid user ID and optional lists of Roles (which correspond to Roles established in the Logi application) and/or Rights.
The ClientBrowserAddress query string value is no longer required.
When the user first requests a report or web page from the Logi application, the Parent application issues a SecureKey request to the Logi application's authentication service, using this basic format:
The URL may also optionally include a list of Roles and/or Rights, using this format:
The rdGetSecureKey.aspx service called in the URL expects or accepts these standard query string values in the URL:
|Username||(Required) The user ID authenticated during the single sign-on process. In your Logi application this can be referenced using @Function.Username~. This token is available for the current user's session and may be referenced in any Logi definition file, including within other child elements of Security, such as Roles and/or Rights.|
|ClientBrowserAddress||(Required) The IP address of the requesting user's computer. This IP address is not the address of the Parent application server. In the Parent application, this IP address should be determined dynamically; in the example code provided below, for example, the address is determined using Request.UserHostAddress. This query string value is no longer required. For Java applications, this must be in IPv4 format (such as 127.0.0.1) and, if the server supports both IPv4 and IPv6, you may need to force the IPv4 connection by setting this Java Option: -Djava.net.preferIPv4Stack=true. See the next section of this topic for additional information relevant to NAT or proxy environments.|
|Roles||(Optional) A comma-separated list of the security roles for this user, determined during the single sign-on process. This comma-separated list becomes your list of Logi application user Roles. The list can be referenced using @Function.UserRoles~ throughout the Logi application, and may be used to assign user rights within the security element.|
|Rights||(Optional) A comma-separated list of the security rights for this user, determined during the single sign-on process. This comma-separated list becomes your list of Logi application user Rights. The list can then referenced as @Function.UserRights~ throughout the Logi application.|
You may also create your own custom query string variables to send other information into the Logi application:
These extra values will be assigned to session variables in the Logi application and can be accessed using @Session tokens. For example, @Session.myCustomParam1~ would equal 10 and @Session.myCustomParam2~ would equal 120. Remember that theses tokens are case-sensitive and you will need to match the spelling in the query string exactly when using them.
The ClientBrowserAddress query string value is no longer required.
Using POST vs GET
For additional security, or if you have a lot of custom query string variables or really long values, you may elect to POST the URL and its query parameters. The Logi application will examine the HTTP request for them automatically, regardless of whether they were sent using HTTP POST or GET.
Using the SecureKey
The Logi application's authentication service returns a SecureKey to the Parent application, which then redirects the user's request to the Logi application, passing the SecureKey as an additional query string parameter. The URL for this redirect will look something like this, using the two keywords rdReport and rdSecureKey:
The following Visual Basic.NET code provides an example of the two things you'll need to do in a Parent application: request a SecureKey and redirect the user's report request using the SecureKey.
Your Parent application may have multiple links to the Logi application, so the following code is an example of a function that can be called from the click event handlers for any of those links. It assumes the user name, user Roles, and user Rights have been placed into session variables as part of the login authentication process and that the Logi application base URL has been specified in the Web.config file.
Public Function getSecureKey() As String
' define parts of the SecureKey request URL
' Logi application base URL is set in Web.config file
Dim strLogiAppBaseURL As String = ConfigurationManager.AppSettings("LogiAppBaseURL")
Dim strGetKeyURL As String = "/rdTemplate/rdGetSecureKey.aspx?Username=" & Session("UserName") & "&Roles="_
& Session("UserRoles") & "&Rights=" & Session("UserRights")
Dim strClientAddr As String = "&ClientBrowserAddress=" & Request.UserHostAddress
' define web request and response receiver
Dim webRequest As Net.HttpWebRequest
Dim webResponse As Net.WebResponse|
webRequest = Net.HttpWebRequest.Create(strLogiAppBaseURL & strGetKeyURL & strClientAddr)
' send the SecureKey request to the Logi app
webResponse = webRequest.GetResponse()
Catch ex As Exception
' if server has Basic or NTLM authentication, try to set creds from the current process
If ex.Message.IndexOf("401") <> -1 Then
webRequest.Credentials = Net.CredentialCache.DefaultCredentials
webResponse = webRequest.GetResponse()
' receive the response and return it as function result
Dim sr As New IO.StreamReader(webResponse.GetResponseStream())
getSecureKey = sr.ReadToEnd()
The event handler code for the links to the Logi application might look like this:
Protected Sub lbtnReports_Click(ByVal sender As Object, ByVal e As EventArgs) Handles lbtnReports.Click
' identify the Logi report definition to be displayed by this menu item or link
Dim strLogiDefName As String = "Default"
' get the Logi application base URL, which is set in the Web.config file
Dim strLogiAppBaseURL As String = ConfigurationManager.AppSettings("LogiAppBaseURL")
' get a SecureKey for this request
Dim strSecureKey As String = getSecureKey()
'redirect to Logi app
Response.Redirect(strLogiAppBaseURL & "/rdPage.aspx?rdReport=" & strLogiDefName _
& "&rdSecureKey=" & strSecureKey)
Additional coding examples in other languages are available in SecureKey Coding Examples.
Debugging SecureKey Requests
It can be very helpful, when developing applications, to view the information being sent between the Parent application and the Logi application during the SecureKey request.
To do this, temporarily provide a value for the Security element's SecureKey Shared Folder. This will cause SecureKeys to appear there as XML files, so you can see when they're created. You can open and examine them in order to determine what's being passed in the SecureKey requests.
We also offer a SecureKey test program (.NET environment only) which is available for download from DevNet; it displays the SecureKey information in a test exchange: http://downloads.logianalytics.com/info/TestSecurekey.zip
If a company has set up a firewall with NAT'd addresses or another form of network proxy that sends all traffic to the Logi application through a single IP address or a range of IP addresses, then client IP address checking in SecureKey needs to be suppressed because individual user locations will not be unique. This can be achieved by modifying the Parent application's request to the Logi application so that it passes a Client Browser Address value of 0.0.0.0. For example:
When using this approach, security can be further enhanced by limiting requests to those from certain parts of the network by using an IP address mask in the web server's security configuration. For IIS, this is accomplished in the IIS Manager's Directory Security tab; for Tomcat this is accomplished by adjusting some of its XML configuration files. The ClientBrowserAddress query string value is no longer required.
Logi SecureKey allows you to securely authenticate from the parent application and establish a session in the Logi application. Once a user is finished working with the Logi application, you want to ensure that the session is terminated. Here are three related considerations:
Application Server Time-out Configuration
Automatic sessiontime-out after a period of inactivity is managed in the web server and, for example, the IIS default setting is 20 minutes. You may want to adjust this to a shorter interval in order to increase session security, which is done in a variety of ways. For example, for IIS, this is set in IIS Manager tool or in the web.config or machine.config files; for Tomcat, it's set in the web.xml file. While this, by itself, is not completely secure (it still presents a window of opportunity until the time-out occurs), it's a good practice that helps minimize security exposure.
Session Exit Elements
The Action.Exit and Response.Exit elements immediately end the current session and redirect the browser to a URL. In Logi Info, you can initiate this from your parent application by browsing directly to a process task in the Logi app, which runs Response.Exit. Otherwise, both actions are usually initiated by a user action, such as clicking a "Logout" button or link (however, user behavior in this regard may not always be reliable).
Restart Session Attribute
The Security element's Restart Session attribute causes previous session information to be cleared with each new SecureKey authentication attempt. Turning this feature on is the recommended method of ensuring that users do not "piggyback" onto a previous user's session.
This requires, however, that your parent application be designed correctly: the authentication routine in the parent app always needs to include a Logi SecureKey authentication request. It should not, for example, include code that tests to see if a Logi session exists and then skips issuing a new SecureKey request if it does. Ensuring that there's a new SecureKey request with each report request will guarantee that other sessions that are not valid (such as those created by using browser bookmarks or shared links) will be rejected and redirected back to the parent app for authentication. It will also ensure that different users on the same machine/browser will also have to authenticate properly (providing that the original user logs out of the parent application session).