Sessions and user state

Orchestrator instances keep track of sessions and user state. It is important to remember that a Maverics session contains much more than just the user’s authentication state. Because of this, it should not be confused with authentication sessions represented in a session cookie or session database.

For example, an Orchestrator may redirect a user to an identity provider such as Azure AD for authentication. Upon success, it retrieves additional attributes from a directory service, database, or an API-exposed service. The authenticated session, user attributes, and any other information associated with the request make up the state of the user and is held in the Maverics session. This state is used by components within the Orchestrator to extend a cloud identity service such as Azure AD to protect on-premises applications or migrate users and their credentials from on-premises identity systems to a cloud identity system.

Configuration options

session declares the set of configuration options for session management.

Cookie

cookie is an optional field used to define settings for the HTTP cookie that is used to tie a user back to their session.

Domain

domain is an optional field that specifies the hosts to which the session cookie will be sent. This should normally be set only when proxying to multiple apps on the same domain. If not set, the cookie domain attribute will be set to the hostname requested by the client.

For example, if domain is set to example.com, the user agent will include the cookie in the Cookie header when making HTTP requests to example.com and all subdomains of *.example.com.

Name

name is an optional field that specifies the name of the session cookie used by the Maverics Orchestrator. The default session cookie name is maverics_session.

Disable HTTP Only

disableHTTPOnly is an optional field that disables the HttpOnly cookie attribute. Defaults to false. If set to true, the session cookie will not have the HttpOnly attribute, allowing the cookie to be accessed via client side scripts.

Disable Secure

disableSecure is an optional field that disables the Secure cookie attribute. Defaults to false. If set to true, the session cookie will not have the Secure attribute, allowing the browser to send the cookie over an unencrypted HTTP request.

Max Lifetime

maxLifetimeSeconds is an optional field that represents the maximum number of seconds that can elapse post-authentication before a session’s authentication state becomes invalidated. If a negative value is specified, the session will remain authenticated indefinitely. If no value is specified, the default is 24 hours.

Idle Timeout

idleTimeout is an optional field that represents the number of seconds a session may remain idle before timing out. If no value is set, or IdleTimeout is set to 0, then the session idle timeout is disabled.

Eval Session Max Lifetime

evalSessionMaxLifetimeSE is an optional field to define a Service Extension that determines how sessions reaching their max lifetime are handled. maxLifetimeSeconds is still used for individually expiring attributes.

Eval Session Idle Timeout

evalSessionIdleTimeoutSE is an optional field to define a Service Extension that determines how session idle timeouts are handled. If this Service Extension is defined, then the idleTimeout value is ignored.

Cache Size

cacheSize is an optional field that limits the number of sessions maintained in memory. When the session cache has reached its maximum size, and a new session is requested, the session management removes the least recently used session from the cache to make room for the new one. If cacheSize is not set, a default value of 50000 users sessions will be used.

Examples

Base Configuration

session:
  cookie:
    domain: example.com
    disableHTTPOnly: false
    disableSecure: false
  maxLifetimeSeconds: 3600
  idleTimeout: 1800

Session Expiration via Service Extension

A Service Extension allows complete flexibility over the process of controlling a user’s session lifespan.

Session timeouts are checked before any checks for authentication. If evalSessionMaxLifetimeSE or evalSessionIdleTimeoutSE returns true, the user’s current session will be deleted, and the user will be required to re-authenticate to any IDPs which were on that session.

The `evalSessionMaxLifetimeSE` Service Extension

This Service Extension returns a boolean value indicating that the user’s session has reached its maximum lifetime, allowing for custom behavior during the check. Typically, this can be determined using the time that the session was created, passed in as a parameter. The value at maxLifetimeSeconds is still used to invalidate specific IDP’s claims and authentication status.

session:
  cookie:
    domain: example.com
  maxLifetimeSeconds: 3600
  evalSessionMaxLifetimeSE:
    funcName: EvalMaxLifetime
    file: /etc/maverics/extensions/session.go

/etc/maverics/extensions/session.go

package main

import (
	"net/http"
	"time"
)

func EvalMaxLifetime(rw http.ResponseWriter, req *http.Request, createdAt time.Time) bool {
	// If the session has reached its maximum lifespan then force logout.
	if createdAt.Before(time.Now().Add(-time.Duration(3600) * time.Second)) {
		http.Redirect(rw, req, "https://example.com/single-logout", 302)
		return true
	}
	return false
}

The `evalSessionIdleTimeoutSE` Service Extension

This Service Extension returns a boolean value indicating the user’s session has been idle and has timed out. Typically, this can be determined using the last access time that is passed as a parameter to the Service Extension. If this Service Extension is defined, then the IdleTimeout value is ignored.

session:
  cookie:
    domain: example.com
  evalSessionIdleTimeoutSE:
    funcName: EvalIdleTimeout
    file: /etc/maverics/extensions/session.go