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
evalMaxLifetimeSE
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
evalIdleTimeoutSE
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
evalMaxLifetimeSE
or evalIdleTimeoutSE
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 evalMaxLifetimeSE
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
evalMaxLifetimeSE:
funcName: EvalMaxLifetime
file: /etc/maverics/extensions/session.go
/etc/maverics/extensions/session.go
package main
import (
"net/http"
"time"
"github.com/strata-io/service-extension/orchestrator"
)
func EvalMaxLifetime(
api orchestrator.Orchestrator,
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 evalIdleTimeoutSE
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
evalIdleTimeoutSE:
funcName: EvalIdleTimeout
file: /etc/maverics/extensions/session.go
/etc/maverics/extensions/session.go
package main
import (
"net/http"
"time"
"github.com/strata-io/service-extension/orchestrator"
)
func EvalIdleTimeout(
api orchestrator.Orchestrator,
rw http.ResponseWriter,
req *http.Request,
lastAccess time.Time,
) bool {
// If the session becomes idle then force logout.
if lastAccess.Before(time.Now().Add(-time.Duration(1800) * time.Second)) {
http.Redirect(rw, req, "https://example.com/single-logout", 302)
return true
}
return false
}