Cookie handling

The cookie mechanism allows the browser to permanently keep the password, eliminating the need to login when the user revisits the application.

How does the cookie mechanism work?

If the user name and password are valid, the REST service program creates a new cookie to be sent to the browser in the HTTP response. An instantaneous redirection is done, this valid cookie is checked by the service (it returns to step 2 of the workflow) and the connection is accepted (step 3a of the workflow). The next time the user starts the application, the SSO service program will check the validity of this cookie. According to the cookie's expiration, the application may start automatically without requiring the user to login again or returning a new login page.

The cookie is set via the HTTP header “Set-Cookie” and requires a name-value pair that can be sent to the browser by a request on the form.

CALL req.setResponseHeader("Set-Cookie", myCookie)

Where myCookie is a string containing a name-value pair, with optional parameters, for example:

LET myCookie = COOKIE_NAME, "=",
               CookieEncrypt(user,pwd,expiredDate,key), "; ",
              "Path=", getCookiePath(path)

Note that the following information should also be set:

A expiration date for the cookie (cookie attributes "max-age" or "expires").
A path for limiting the validity of the cookie to the current application (cookie attribute “path”).

Cookie expiration date handling

The date of expiration is usually defined by the cookie attribute “max-age”. It represents a value in seconds relative to the current date and time. For instance, max-age=3600 means that the cookie will expire in 1 hour.

The max-age attribute is not supported by Internet Explorer. The service could use the attribute “expires”, however it requires an absolute GMT hour and Genero currently doesn't handle this format.

To solve this problem, the expiration date is directly included (and encrypted) inside the cookie value.

The cookie structure

To ease the understanding of this example, the cookie has a simple structure:

'name=value;Path=path_value'

The name of the cookie is hard-coded in the SSOUserFunctions.4gl code with the COOKIE_NAME constant.
value of the cookie is an encrypted combination of username, password and expiration date, separated by a given separator. Once decrypted, value of the cookie can be something like 'userName="myuser";password="mypassword";expirationDate="12/12/2018"'.
The separator and the name of attributes can be changed by the constants C_USERNAME (for the username attribute), C_PASSWORD (for the password attribute), C_EXPIRATION (for the expiration date attribute) and C_SEP (for the separator) in theSSOUserFunctions.4gl module.
Path remains the normal “Path” cookie attribute. path_value should correspond to what is after “http://host:port” in the URL.

How the cookie is handled in the Simple SSO service

The cookie needs to be checked initially by the Simple SSO service (step 2 of the workflow) in order to know if the application can be executed directly or if the end user needs to login again.

There are three options.

The cookie is valid (step 3a of the workflow).
The connection is accepted immediately and the application executed. For checking if the cookie is valid, the service needs to retrieve the content of the “Cookie” HTTP header. Once this content has been retrieved, the service decrypts the value of the expiration date. If the expiration date is later than the current date (CURRENT value), the connection is accepted using HTTP code 307 and the description _GENERO_INTERNAL_DELEGATE_.
The cookie is no longer valid as the cookie expiration date has expired (step 3b of the workflow).
A cookie cannot be valid if the date has expired. The cookie is set to a new value (in our example, the user and password values are set to -1 before being encrypted in this new cookie value) and a redirection is done on the same URL. After redirection, the cookie is decrypted and values “-1” are found for login and password. They are considered as invalid and the user is redirected again to the login page. Specifically, in our sample, it's redirected to an XHTML login page indicating “the session has expired”.
The cookie is NULL (step 3b of the workflow).
For the initial connection, the cookie is NULL. It can be redirected to a simple “Welcome” page rather than the login page.

Expiration date of the cookie

When the cookie is created, it is handled like this:

If the “keeping password” box has been checked (password kept), the expiration date is set by default to one year later.
If “keeping password” box has not been checked (password not kept), the expiration date is almost instantaneous (10 seconds by default, so that the cookie remains only valid one time for redirection)

It can be easily changed by the constants C_EXPIRATION_COOKIE_CHECKED (value in years) and C_EXPIRATION_COOKIE_UNCHECKED (value in seconds) of the SSOUserFunctions.4gl module.