Ceptor has the concept of a session - in this session, we store known data about a particular user/client/browser/device.

A session always has a session ID which references it - this ID can be in the "new" or the "old" format - the old format is a fixed length format with space for limited data, and the new format is variable length with space for containing more data.
A session can also have a token or ticket pointing to it - this could be a JWT token, an SSL client certificate, an eticket or any other kind of ticker or token previously issued to a user.

A Unique ID is unique per request, and contains both a Session ID part, and a Request ID part - the Request ID is not part of the key for the session itself, but a unique string appended to the session ID creating the "Unique ID" which is forwarded on each request to the proxied Destinations. The Request part of the ID carries data such as the current IP address and TCP port number of the request, along with environment and channel ID.

Obtaining Sessions

When the Ceptor Gateway obtains a session, it invokes a Session Resolver - a Session Resolver is responsible for looking at the request, and identifying a session from the request. A session can be identified using a number of different methods and attributes, such as a plain session cookie, but it can also be based upon an API Key, an HTTP header value, a bearer token or any other form of token or ticket or ID which identifies the client/callers session in some form.

The session ID / ticket / token is mapped to a session by calling Ceptor Agent (embedded in the gateway) which makes a call to the Ceptor Session Controller in order to obtain a reference to a session.

The session itself (while initially containing nothing) is over time populated with information about the caller, such as userid, groups and attributes such as name, address or even haircolor, shoesize or whatever other attributes you want to store within the session. A session survives across requests and is potentially shared across many requests and gateways, applications and modules. Look at it as a kind of shared piece of memory containing attributes that in some form identifies or relates to the caller.

All sessions are stored on the Ceptor Session Controller and accessed via the API in the Ceptor Agent - the Agent is also responsible for caching content, and participates in a kind distributed shared cache.
Any changes to a session are always done solely by the Ceptor Session Controller - but changes are requested by many other modules via the Ceptor Agent API.

Creating a session from a token/ticket/attribute can involve authenticating the client - e.g. if a session is created from an API Key or an SSL Client Certificate, the creation of the session involves validating and authenticating the client.

Ceptor provices out-of-the-box support for the following Session Resolvers:

• SSL Client certificate
  An SSL client certificate is used as a "Token" - meaning only a single session is created for a given SSL client certificate received by the gateway - this session is then shared between multiple calls using the same certificate.
• Bearer Token
  A session is created from a Bearer Token - meaning an HTTP request header in the format "Authorization:  Bearer: xxxxxx" where xxxxxx is the token - the valid contents of this token is up to a given authentication plugin running - the authentication plugin called in the Session Controller is of the type "AuthTypes.AUTHTYPE_OAUTH2". A typical example is to use an authentication plugin that knows how to process JWT Tokens.
• API Key
  A session is created from an API key - an HTTP header, e.g. "Ceptor-Api-Key: xxxxxx" where xxxxxx is the API key. For API Keys, the authentication plugin called within the session controller is AuthTypes.AUTHTYPE_APIKEY.
• Domain Redirect
  Domain Redirect is a way of sharing browser sessions between domains - when you are authenticated on www.mydomain1.com you can create a special URL that sends a request to www.myotherdomain.com and forwards the session cookie information to that second domain - in this case, the same session cookie will be set for both domains.
• Session Cookie
  This is the most used format - it works similar to an HTTP session where the ID is stored in a cookie - if no valid session or cookie is found, a new one will be created for the user.
• Script
  This allows you to customize the behavior and e.g. base the session ID on a query parameter, custom HTTP header or something entirely different.

 It is possible to create your own ways of resolving a session using a different method, e.g. using a unique device ID sent by a client, using another format than a cookie to contain the session ID etc. Ceptor has a plugin architecture which allows you to create custom plugins to handle this. Refer to the documentation here: Plugins - SessionResolver For information on how to do this.

Session ID formats

"Old" ID format

 *  8 bytes Client Machine ID (IP)
 *  2 bytes cluster ID
 *  2 bytes segment ID
 * 28 bytes Session ID (random bytes + timestamp + counter)


The above is considered the session ID part of the ID, below is the request specific part of it
 *  2 bytes Transaction chn type
 *  8 bytes Transaction ID
 *  2 bytes Environment ID
 *  8 bytes Current IP address

"New" ID format

* 5 bytes "magic" identifier - either "PPID_" or "CEPID_"
* x bytes Session ID

The above is considered the session ID part of the ID, below is the request specific part of it
* 1 bytes seperator character - always "_"
* y bytes Request ID
The x/y bytes of Session/Request ID is in the format
* 2 bytes length
* 1 byte type (Currenty for sesssion ID: IP, RANDOM, CLUSTERID, SEGMENTID and for request ID: CHANNELID, ENVIRONMENTID, SOURCEIP, SOURCEPORT, TRANSACTIONID, OAUTHTOKEN)
* z bytes (defined by the first 2 bytes indicating the length) content

As you can see, the new format is dynamic in length and can be extended with other types of information, where the old format is fixed and is unable to carry more information.

The type of format used is configured in the Ceptor Session Controller - we recommend using the new format unless you have good reason not to.

Data as Part of ID

The IDs can carry limited data, here is a short description of the purpose of each data item;

• Cluster ID
  You can have multiple cluster of session controllers, and an agent can connect to multiple different clusters at a time - the cluster ID is the unique ID of the cluster who "owns" the session. Based upon the cluster ID, an agent knows which cluster to contact in order to read or change the contents of the session.
• Segment ID
  You can divide your Dispatchers / Gateways into different segments - e.g. one segment for internal users, another for internal users and a third for partners. You cannot share sessions between segments, this enables you to set up an environment where even though sessions are kept on the same clusters of session controllers, environments are separated from each other. Additionally, you can restrict certain authentication plugins to only be callable by certain segments or environments so you can ensure that even in case of application errors, types of authentication meant for internal users cannot be used for external users. 
• Environment ID
  Like you have different segments, you can have different environments for your Dispatchers / Gateways - but where sessions cannot be shared between segments, they can be shared between environments. This allows you to share SSO between external and internal users, but still (via environment limits on authentication plugins) ensure that internal authentication types are only called by users accessing an internal cluster of Dispatchers/Gateways.
• Transaction ID
  This is a unique ID generated for each transaction/request - if the entire request ID is transmitted as part of the call-chain between applications and used for logging everywhere, it allows identification of log entries for individual requests across different servers and applications.
• Channel ID/Type
  The channel type contains information about the original request - whether it arrived using HTTP, HTTPS or a different transport method.
• Source IP
  If part of the session ID, Source IP of the original session - can optionally be used to limit requests to the IP address that originally created them, protecting against hijacking sessions. If part of the request ID, this is the current IP address used for this specific request - this is useful in situations where the client change IP address during a session, or the cases where the session is based upon a token, e.g. JWT token.
• Source TCP Port
  Contains the TCP Port number of the request - can be used by forensics to determine which user really originated the request in case of NAT gateways or proxies being used where multiple individual users share the same IP address. 
• OAuthToken
  Token or ticket used to create the session - can be eticket, JWT token, SSL certificate or whatever access token was used in place of a session cookie.