Config - Sessions

JSON Configuration for Sessions

{
  "session": {
    "cookie.not.for.uri": "*.crl",
    "resolvers": [
      "io.ceptor.session.SessionResolverSSLClientCert",
      "io.ceptor.session.SessionResolverBearerToken",
      "io.ceptor.session.SessionResolverDomainRedirect",
      "io.ceptor.session.SessionResolverCookie"
    ],
    "cookie.no.cachecontrol.header.for": "*.crl|*.pdf",
    "http.cookiename": "sessionid",
    "https.cookiename": "sslsessionid",
    "cookie.path": "/",
    "sessionfixation.cookiename": "sslsessionid_sf",
    "cookie.use.httponly": true,
    "sessionfixation.addcookie": true,
    "sessionfixation.defense": true,
    "cookie.obfuscate": true,
    "cookie.use.domain": true,
	"cookie.samesite": "none",
    "resolve.script": null,
    "create.script": null,
    "remove.script": null,
    "apikey": {
      "headername": "ceptor-apikey"
    }
  }
}

Sessions configuration via Ceptor Console

Sessions are stored in the JSON object named session.

The configuration is split into 3 different sections.

Session Configuration

HTTP Session Cookie

Name of session cookie to use for unencrypted HTTP sessions. If the cookie session resolver is installed, and if requests are unencrypted, the session ID will be stored in this cookie.

Default is sessionid
JSON key: http.cookiename 

HTTPS Session Cookie

Name of session cookie to use for encrypted HTTPS sessions. For encrypted requests, session IDs will be stored in this cookie,

Default is sslsessionid
JSON key https.cookiename 

Cookies are httponly

If set, session cookies are marked as httponly, meaning javascript code is not able to retrieve them.

Default is true
JSON key: cookie.use.httponly 

Use domain in cookies

If set, session cookies will be set for the current domain - e.g. for http://www.ceptor.io the domain will be set to ceptor.io so the cookies are shared between all hosts of the domain.

Default is true
JSON key: cookie.use.domain 

Obfuscate sessionid

If set, Session ID is not sent in the clear, but obfuscated - note that obfuscation makes it larger but slightly more secure.

Default is true
JSON key: cookie.obfuscate 

Cookie path

Specifies cookie path on session cookies - in general should be set to as a specific value as possible, but for single-sign on between multiple applications, this is in practice always set to the root "/".

Default is /
JSON key: cookie.path 

No Cache-Control for

If URI path matches this pattern, no "Cache-Control: no-cache header" will be added.

Default: *.pdf|*.crl
JSON key: cookie.no.cachecontrol.header.for

No cookie for

If URI path matches this pattern, no session cookie will be added. This can be used to create sessions for certain URLs, but not add a session cookie for it. Notice that a better method of allowing some requests to pass through without a session, is to create a location which does not require a session, and handle those URIs there - in that case, no session will be created.

Default: *.crl
JSON key: cookie.not.for.uri

SameSite

If set to none, lax or scrict, the cookie attribute SameSite=None, SameSite=Strict or SameSite=Lax is added to the session cookies. This enables CSRF/XSRF attack protection - see https://tools.ietf.org/html/draft-west-first-party-cookies-07 for details.

Default: blank (as in not selected)
JSON key: cookie.samesite

Session Resolvers

Session resolvers look at the request to determine session ID based upon e.g. a session cookie, bearer token or other types of input.

You can select from these session resolvers by default:

• io.ceptor.session.SessionResolverBearerToken
  Allows use of an OAuth2 bearer token in the HTTP request header Authorization.
• io.ceptor.session.SessionResolverApiKey
  Allows using an API Key contained in an HTTP header, e.g. ceptor-apikey instead of using a session ID to identify the session.
• io.ceptor.session.SessionResolverCookie
  Supports use of a session cookie.
• io.ceptor.session.SessionResolverDomainRedirect
  Supports using Domain Redirect URLs (URLs ending with ".domainRedirect") which allows sharing sessions between two or more domains, e.g. www.mydomain1.com and www.myotherdomain.com
• io.ceptor.session.SessionResolverSSLClientCert
  Allows using an SSL client certificate as a "ticket", with no other session ID - if no session currently exists for the incoming client certificate, one will be created and the user will be authenticated assuming the authentication plugin allows access. 
• io.ceptor.session.SessionResolverSSLClientCertAPIManagement
  Allows using an SSL client certificate to authenticate - instead of using the regular Ceptor SSL Client certificate authentication plugin the API Management specific plugin is used, which lookup's certificates in API Partner Application definitions.
• io.ceptor.session.SessionResolverScript
  Allows implementing a session resolver using Javascript - makes it easy to add custom functionality to the gateway. 

See also Plugins - Session Resolvers 

Default: none
JSON key: resolvers 

Defense Against Session Fixation Attack

Session fixation is a form of attack where an attacker uses a public computer, captures the session ID, and then leaves the computer for another to authenticate at - when the user authenticates later, if the session id is not changed then the attacker has that session ID available, and he can then take over the authenticated users session.

The gateway can defend against this, by creating another cookie, a so-called session-defense cookie, which is changed at the moment of authentication - for all authenticated request, the value of this cookie is then compared against the expected value, and if they differ the request is considered to be invalid.

It can work in two modes, in the complete, it adds the cookie automatically, by looking at the request when it comes in, and on the way out again - if authenticated anytime in the meantime, e.g. by a login application on a proxied destination server, then the gateway will detect it and automatically add the session defense cookie. It creates a unique ID, stores that in the regular session, and then for all future authenticated requests, it compares the received value against the expected one.

Session Fixation Defense Cookie

Name of session fixation defense cookie to use for encrypted HTTPS sessions.

Default: sslsessionid_sf
JSON Key:  sessionfixation.cookiename

Defend against session fixation attack

If set, for authenticated sessions which have set pp_sessionfixation in the session, we will check if there is a session fixation cookie with the same value in the request.

Default: true
JSON Key: sessionfixation.defense 

Add session fixation defense cookie automatically

If set, a new value is generated and stored in the session, and the cookie will be added automatically when the user is authenticated. Note that unless defense against session fixation is turned on, this cookie has no effect.

Default: true
JSON Key: sessionfixation.addcookie 

If SessionResolverApiKey is added as a session resolver

In case a SessionResolverApiKey is added, this setting is used:

HTTP Header name for API key

Can be used to specify the name of the HTTP header to read the API key from.

Default: ceptor-apikey
JSON Key: headername within an apikey JSON object.

Scripts, if SessionResolverScript is added as a session resolver

Note that these scipts are only executed if the SessionResolverScript plugin is added to the list of active session resolvers. See Plugins for examples.

Session resolver script

Script executed to resolve a session.

Default: none
JSON Key: resolve.script 

Session creation script

Optional script executed to create a session.

Default: none
JSON Key: create.script 

Session removal script

Optional script executed to remove a session ID - e.g. delete a session cookie.

Default: none
JSON Key: remove.script