510 lines
17 KiB
Markdown
510 lines
17 KiB
Markdown
|
Extended Session Management
|
||
|
|
===========================
|
||
|
|
|
||
|
|
<!-- toc -->
|
||
|
|
|
||
|
|
- [Abstract](#abstract)
|
||
|
|
- [Session Lifecycle](#session-lifecycle)
|
||
|
|
- [Security](#security)
|
||
|
|
- [Data Privacy](#data-privacy)
|
||
|
|
- [API Reference](#api-reference)
|
||
|
|
- [Example](#example)
|
||
|
|
- [Performance](#performance)
|
||
|
|
- [Custom Storage Driver](#custom-storage-driver)
|
||
|
|
- [Credentials Structure](#credentials-structure)
|
||
|
|
|
||
|
|
<!-- tocstop -->
|
||
|
|
|
||
|
|
## Abstract
|
||
|
|
|
||
|
|
The application router uses a memory store as a session repository to provide
|
||
|
|
the best runtime performance. However, it is not persisted and it is not shared
|
||
|
|
across multiple instances of the application router.
|
||
|
|
|
||
|
|
*__Note:__ The Limitations above do not prevent the application router from
|
||
|
|
being scaled out, since session stickiness is in place by default.*
|
||
|
|
|
||
|
|
While it is good enough for most of the cases, it may be required to
|
||
|
|
provide a highly-available solution, which may be achieved by storing
|
||
|
|
the state (session) of the application router outside - in durable shared
|
||
|
|
storage.
|
||
|
|
To allow implementing these qualities, the application router exposes the
|
||
|
|
*extended session management* API described below.
|
||
|
|
|
||
|
|
## Session Lifecycle
|
||
|
|
|
||
|
|
The application router stores user agent sessions as JavaScript objects
|
||
|
|
serialized to strings. It also stores the session timeout associated with
|
||
|
|
each session, which indicates the amount of time left until session
|
||
|
|
invalidation.
|
||
|
|
|
||
|
|
### Initial Data
|
||
|
|
|
||
|
|
During the start of the application router, the internal session store is initiated.
|
||
|
|
It contains an empty list of sessions and their timeouts. The internal session
|
||
|
|
store is not available right after the application router instance is
|
||
|
|
created, but is available in the callback of `approuter.start` and all
|
||
|
|
the time afterwards until the application router is stopped.
|
||
|
|
|
||
|
|
In case an external session storage is used, the application router extension
|
||
|
|
should perform the following actions to synchronize the internal session
|
||
|
|
store with the external one:
|
||
|
|
|
||
|
|
- Load existing sessions from external storage
|
||
|
|
- Start the application router
|
||
|
|
- Populate the application router's internal session store
|
||
|
|
|
||
|
|
### Read
|
||
|
|
|
||
|
|
A session identifier may be obtained from the request object `req.sessionID`.
|
||
|
|
|
||
|
|
On each request, the application router executes registered middlewares
|
||
|
|
in a certain order and the session is not available to all of them.
|
||
|
|
|
||
|
|
- First it passes the request to `approuter.first` middleware.
|
||
|
|
At this point, there is no session associated with
|
||
|
|
the incoming request.
|
||
|
|
- Afterwards, the application router checks if the user is authenticated, reads
|
||
|
|
the relevant session from the internal session store and puts it into the request
|
||
|
|
context.
|
||
|
|
- Next, the application router passes a request to
|
||
|
|
`approuter.broforeRequestHandler`. At this point, the session object is
|
||
|
|
available and associated with the incoming request.
|
||
|
|
- `approuter.beforeErrorHandler` also has access to session.
|
||
|
|
|
||
|
|
### Login
|
||
|
|
|
||
|
|
When a user agent requests a resource, served via a route that requires
|
||
|
|
authentication, the application router will request the user agent to
|
||
|
|
pass authentication first (usually via redirect to XSUAA). At this point,
|
||
|
|
the application router does not create any session. Only after
|
||
|
|
the authentication process is finished, the application router creates a session,
|
||
|
|
stores it in the internal session storage and emits a `login` event.
|
||
|
|
|
||
|
|
### Update Session
|
||
|
|
|
||
|
|
Any changes made to the session are not stored in the internal session store
|
||
|
|
immediately, but are accumulated to make a bulk update after the end of the response.
|
||
|
|
While the request is passed through the chain of middlewares, the session object
|
||
|
|
may be modified. Also, when the backend access token is close to expire,
|
||
|
|
the application router may trigger the refresh backend token flow. In both cases,
|
||
|
|
the actual update of the internal session store is done later on, outside of
|
||
|
|
the request context.
|
||
|
|
|
||
|
|
### Timeout
|
||
|
|
|
||
|
|
There is a time-based job in the application router that basis outside
|
||
|
|
the request context and destroys sessions with an elapsed timeout.
|
||
|
|
|
||
|
|
Each time the application router reads a session from the session store,
|
||
|
|
the timeout of this session is reset to the initial value that may be retrieved
|
||
|
|
using the [`getDefaultSessionTimeout()`](#sessionstoregetdefaultsessiontimeout)
|
||
|
|
API.
|
||
|
|
|
||
|
|
### Logout
|
||
|
|
|
||
|
|
When a user agent requests a URL defined as the `logoutEndpoint` in the
|
||
|
|
`xs-app.json` file, a central logout process takes place. As part of this
|
||
|
|
process, the application router emits a `logout` event. More detailed
|
||
|
|
information about the central logout may be found in
|
||
|
|
[README.md](../README.md)
|
||
|
|
|
||
|
|
## Security
|
||
|
|
|
||
|
|
The application router uses session secret to sign session cookies and
|
||
|
|
prevent tampering. The session secret, by default, is generated using
|
||
|
|
a random sequence of bytes at the startup of the application router. It is
|
||
|
|
different for each instance and changed on each restart of the same
|
||
|
|
instance.
|
||
|
|
|
||
|
|
Using the default session secret generation mechanism for highly available
|
||
|
|
application routers may cause issues in the following scenarios:
|
||
|
|
|
||
|
|
- The user agent is authenticated and the session is stored in a session store.
|
||
|
|
The application router is restarted (due to internal error or triggered
|
||
|
|
by platform) and a new session secret is generated. The authenticated user
|
||
|
|
agent makes a request, which contains the session cookies. However, the cookies are
|
||
|
|
signed using another secret and the application router ignores them.
|
||
|
|
- The user agent is authenticated and the session is stored in the session store.
|
||
|
|
The application router instance is unavailable. The authenticated user agent
|
||
|
|
makes a request to the application router and the request contains the session
|
||
|
|
cookies. The load balancer forwards the request to another instance of
|
||
|
|
the application router. However, cookies are signed using another secret and
|
||
|
|
the application router ignores them.
|
||
|
|
|
||
|
|
In both scenarios, the session in the store is no longer accessible, the cookies
|
||
|
|
sent by the user agent are redundant, and the user agent will be requested to
|
||
|
|
pass authentication once again.
|
||
|
|
|
||
|
|
To avoid the issues described above, the extension that implements the extended session
|
||
|
|
management mechanism, should make sure to implement the `getSessionSecret` hook.
|
||
|
|
|
||
|
|
```js
|
||
|
|
var ar = AppRouter();
|
||
|
|
|
||
|
|
ar.start({
|
||
|
|
getSessionSecret: function () {
|
||
|
|
return 'CUSTOM_PERSISTED_SESSION_SECRET';
|
||
|
|
},
|
||
|
|
...
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
It is recommended to have at least 128 characters in the string that replaces
|
||
|
|
`CUSTOM_PERSISTED_SESSION_SECRET`.
|
||
|
|
|
||
|
|
## Data Privacy
|
||
|
|
|
||
|
|
The user agent session potentially contains personal data. By implementing
|
||
|
|
the custom session management behaviour, you take the responsibility to be
|
||
|
|
compliant with all personal data protection laws and regulations
|
||
|
|
(e.g. [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation))
|
||
|
|
that may be applied in the regions, where the application will be used.
|
||
|
|
|
||
|
|
## API Reference
|
||
|
|
|
||
|
|
### Methods
|
||
|
|
|
||
|
|
#### approuter.start(options)
|
||
|
|
|
||
|
|
* `options`
|
||
|
|
* `getSessionSecret` - returns the session secret to be used
|
||
|
|
by the application router for the signing of the session cookies.
|
||
|
|
|
||
|
|
#### approuter.getSessionStore()
|
||
|
|
|
||
|
|
returns `SessionStore` instance.
|
||
|
|
|
||
|
|
#### sessionStore.getDefaultSessionTimeout()
|
||
|
|
|
||
|
|
returns the default session timeout in minutes.
|
||
|
|
|
||
|
|
#### sessionStore.getSessionTimeout(sessionId, callback)
|
||
|
|
|
||
|
|
* `sessionId` - an unsigned session identifier
|
||
|
|
* `callback` - `function(error, session)` a function that is called
|
||
|
|
when the session object is retrieved from the internal session
|
||
|
|
storage of the application router.
|
||
|
|
* `error` - an error object in case of an error, otherwise `null`
|
||
|
|
* `timeout` - time, in minutes, until the session times out
|
||
|
|
|
||
|
|
#### sessionStore.get(sessionId, callback)
|
||
|
|
|
||
|
|
* `sessionId` - an unsigned session identifier
|
||
|
|
* `callback` - `function(error, session)` a function that is called
|
||
|
|
when the session object is retrieved from the internal session
|
||
|
|
storage of the application router.
|
||
|
|
* `error` - an error object in case of an error, otherwise `null`
|
||
|
|
* `session` - the session object
|
||
|
|
* `id` - session identifier, immutable
|
||
|
|
|
||
|
|
#### sessionStore.set(sessionId, sessionString, timeout, callback)
|
||
|
|
|
||
|
|
* `sessionId` - an unsigned session identifier
|
||
|
|
* `sessionString` - a session object serialized to string
|
||
|
|
* `timeout` - a timestamp in milliseconds, after which the session should be
|
||
|
|
automatically invalidated
|
||
|
|
* `callback` - a function that is called after the session is saved in the
|
||
|
|
internal session storage of the application router
|
||
|
|
|
||
|
|
#### sessionStore.update(sessionId, callback, resetTimeout)
|
||
|
|
|
||
|
|
* `sessionId` - an unsigned session identifier
|
||
|
|
* `callback` - `function(currentSession)` function, which returns
|
||
|
|
session object. Callback function may modify and return current
|
||
|
|
session object or create and return brand new session object
|
||
|
|
* `currentSession` - current session object
|
||
|
|
* `resetTimeout` - a boolean that indicates whether to reset the session timeout
|
||
|
|
|
||
|
|
|
||
|
|
#### sessionStore.destroy(sessionId, callback)
|
||
|
|
|
||
|
|
* `sessionId` - an unsigned session identifier
|
||
|
|
* `callback` - a function that is called after the session is destroyed in
|
||
|
|
the internal session storage of the application router
|
||
|
|
|
||
|
|
### Events
|
||
|
|
|
||
|
|
Extension may subscribe to application router events using the standard
|
||
|
|
[`EventEmitter`](https://nodejs.org/api/events.html) API.
|
||
|
|
|
||
|
|
```js
|
||
|
|
var ar = AppRouter();
|
||
|
|
|
||
|
|
ar.on('someEvent', function handler() {
|
||
|
|
// Handle event
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `login`
|
||
|
|
|
||
|
|
Emitted when user agent is authenticated.
|
||
|
|
|
||
|
|
Parameters:
|
||
|
|
* `session` - session object
|
||
|
|
* `id` - session identifier, immutable
|
||
|
|
|
||
|
|
#### `logout`
|
||
|
|
|
||
|
|
Emitted when a user agent session is going to be terminated in
|
||
|
|
the internal session store of the application router. Emitted either when
|
||
|
|
the user agent session is timed-out or when `logoutEndpoint` was requested.
|
||
|
|
|
||
|
|
*__Note:__ Central logout is an asynchronous process. The order in which
|
||
|
|
the backend and the application router sessions are invalidated, is not
|
||
|
|
guaranteed.*
|
||
|
|
|
||
|
|
Parameters:
|
||
|
|
* `session` - session object
|
||
|
|
* `id` - session identifier, immutable
|
||
|
|
|
||
|
|
## Example
|
||
|
|
There may be many various options, how the application router extension
|
||
|
|
decides to store sessions exposed via the session management API. The example
|
||
|
|
below assumes a `SessionDataAccessObject` to be implemented by the extension
|
||
|
|
developer and to have the following API:
|
||
|
|
|
||
|
|
### Methods:
|
||
|
|
|
||
|
|
* `sessionDataAccessObject.create` - `function(session, timeout)`
|
||
|
|
* `sessionDataAccessObject.update` - `function(sessionId, timeout)`
|
||
|
|
* `sessionDataAccessObject.delete` - `function(sessionId)`
|
||
|
|
* `sessionDataAccessObject.load` - `function()`
|
||
|
|
|
||
|
|
### Events:
|
||
|
|
|
||
|
|
#### `create`
|
||
|
|
|
||
|
|
Parameters:
|
||
|
|
|
||
|
|
* `sessionId` - session identifier
|
||
|
|
* `session` - session object serialized to string
|
||
|
|
* `timeout` - timestamp, when session should expire
|
||
|
|
* `callback` - function to be called after session is stored in
|
||
|
|
internal session storage
|
||
|
|
|
||
|
|
#### `update`
|
||
|
|
|
||
|
|
Parameters:
|
||
|
|
|
||
|
|
* `sessionId` - session identifier
|
||
|
|
* `session` - session object serialized to string
|
||
|
|
* `timeout` - timestamp, when session should be expired
|
||
|
|
* `callback` - function to be called after session is stored in
|
||
|
|
internal session storage
|
||
|
|
|
||
|
|
#### `delete`
|
||
|
|
|
||
|
|
Parameters:
|
||
|
|
|
||
|
|
* `sessionId` - session identifier
|
||
|
|
|
||
|
|
#### `load`
|
||
|
|
|
||
|
|
Parameters:
|
||
|
|
|
||
|
|
* `sessions[]` - array of objects
|
||
|
|
* `id` - session identifier
|
||
|
|
* `session` - session object serialized to string
|
||
|
|
* `timeout` - timestamp, when session should expire
|
||
|
|
|
||
|
|
```js
|
||
|
|
var ar = new require('@sap/approuter')();
|
||
|
|
var dao = new SessionDataAccessObject();
|
||
|
|
|
||
|
|
dao.on('load', function (data) {
|
||
|
|
|
||
|
|
ar.start({
|
||
|
|
getSessionSecret: function getSessionSecret() {
|
||
|
|
return process.env.SESSION_SECRET;
|
||
|
|
}
|
||
|
|
}, function() {
|
||
|
|
var store = ar.getSessionStore();
|
||
|
|
var defaultTimeout = store.getDefaultSessionTimeout();
|
||
|
|
|
||
|
|
// AppRouter -> Persistence
|
||
|
|
ar.on('login', function(session) {
|
||
|
|
dao.create(session, defaultTimeout);
|
||
|
|
});
|
||
|
|
ar.on('update', function(sessionId, timeout) {
|
||
|
|
dao.update(sessionId, timeout);
|
||
|
|
});
|
||
|
|
ar.on('logout', function(sessionId) {
|
||
|
|
dao.delete(sessionId);
|
||
|
|
});
|
||
|
|
|
||
|
|
// Load Initial Data
|
||
|
|
data.forEach(function(item) {
|
||
|
|
store.set(item.id, item.session, item.timeout);
|
||
|
|
});
|
||
|
|
|
||
|
|
// Persistence -> AppRouter
|
||
|
|
dao.on('create', store.set);
|
||
|
|
dao.on('update', store.set);
|
||
|
|
dao.on('delete', store.destroy);
|
||
|
|
});
|
||
|
|
|
||
|
|
});
|
||
|
|
|
||
|
|
dao.load();
|
||
|
|
```
|
||
|
|
|
||
|
|
## Performance
|
||
|
|
|
||
|
|
*__Note:__ The `update` event of the application router may be potentially
|
||
|
|
triggered thousands of times a second. It is recommended to throttle or
|
||
|
|
debounce calls to the external storage to reduce network and CPU
|
||
|
|
consumption.*
|
||
|
|
|
||
|
|
Here is an example of a throttled `dao.update()`, where the latest change
|
||
|
|
will be persisted in the external storage no more than once in `500ms` for
|
||
|
|
the same session.
|
||
|
|
|
||
|
|
```js
|
||
|
|
// Throttled update
|
||
|
|
update(sessionId, timeout) {
|
||
|
|
var dao = this;
|
||
|
|
var sessionStore = this._sessionStore;
|
||
|
|
if(typeof timeout === 'undefined') {
|
||
|
|
if (!this.updateTimers[sessionId]) {
|
||
|
|
this.updateTimers[sessionId] = setTimeout(function() {
|
||
|
|
dao.updateTimers[sessionId] = null;
|
||
|
|
}, 500);
|
||
|
|
sessionStore.get(sessionId, function(err, session) {
|
||
|
|
dao._saveSession(sessionId, session)
|
||
|
|
});
|
||
|
|
}
|
||
|
|
} else {
|
||
|
|
if (!this.timeoutTimers[sessionId]) {
|
||
|
|
this.timeoutTimers[sessionId] = setTimeout(function() {
|
||
|
|
dao.timeoutTimers[sessionId] = null;
|
||
|
|
}, 500);
|
||
|
|
sessionStore.getSessionTimeout(sessionId, function(err, timeout) {
|
||
|
|
dao._saveTimeout(sessionId, timeout)
|
||
|
|
});
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
And here is an example of a debounced `dao.update()`, where the latest
|
||
|
|
change will be persisted in the external storage only if there were no other
|
||
|
|
changes during the last `500ms` for the same session.
|
||
|
|
|
||
|
|
```js
|
||
|
|
// Debounced update
|
||
|
|
update(sessionId, timeout) {
|
||
|
|
var dao = this;
|
||
|
|
var sessionStore = this._sessionStore;
|
||
|
|
if(typeof timeout === 'undefined') {
|
||
|
|
if (this.updateTimers[sessionId]) {
|
||
|
|
clearTimeout(this.updateTimers[sessionId]);
|
||
|
|
}
|
||
|
|
this.updateTimers[sessionId] = setTimeout(function() {
|
||
|
|
sessionStore.get(sessionId, function(err, session) {
|
||
|
|
dao._saveSession(sessionId, session)
|
||
|
|
});
|
||
|
|
}, 500);
|
||
|
|
} else {
|
||
|
|
if (this.timeoutTimers[sessionId]) {
|
||
|
|
clearTimeout(this.timeoutTimers[sessionId]);
|
||
|
|
}
|
||
|
|
this.timeoutTimers[sessionId] = setTimeout(function() {
|
||
|
|
sessionStore.getSessionTimeout(sessionId, function(err, timeout) {
|
||
|
|
dao._saveTimeout(sessionId, timeout)
|
||
|
|
});
|
||
|
|
}, 500);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
To understand the difference between throttling and debouncing, let's
|
||
|
|
consider an example, where requests for the same session come every
|
||
|
|
`100ms` for `1sec`. In case of `500ms` debouncing, changes will be
|
||
|
|
persisted one time. In case of `500ms` throttling, changes will be
|
||
|
|
persisted two times. Without any optimisation, changes will be
|
||
|
|
persisted ten times.
|
||
|
|
|
||
|
|
## Custom Storage Driver
|
||
|
|
|
||
|
|
It is possible to use your own driver. In order to do that, user shall inject its own implementation of a store.
|
||
|
|
|
||
|
|
The class shall implement the following interface:
|
||
|
|
```typescript
|
||
|
|
|
||
|
|
interface UserCustomStore {
|
||
|
|
|
||
|
|
// delete all sessions
|
||
|
|
clear(): Promise<void>;
|
||
|
|
|
||
|
|
// remove <sessionId> session
|
||
|
|
destroy(sessionId : string): Promise<void>;
|
||
|
|
|
||
|
|
// retrieve <sessionId> session
|
||
|
|
get(sessionId : string): Promise<object | null>;
|
||
|
|
|
||
|
|
// number of sessions
|
||
|
|
length(): Promise<number>;
|
||
|
|
|
||
|
|
// get <sessionId> expiration
|
||
|
|
ttl(sessionId : string): Promise<number>;
|
||
|
|
|
||
|
|
// set <sessionId> data to <session> with <timeout> expiration
|
||
|
|
set(sessionId: string, session: object, timeout: number): Promise<void>;
|
||
|
|
|
||
|
|
// check if session <sessionId> exists
|
||
|
|
exists(sessionId: string): boolean;
|
||
|
|
|
||
|
|
// update existing session <sessionId> expiration to <timeout>
|
||
|
|
resetTimer(sessionId: string, timeout: number);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
In addition, the file should include a method to get an instance of the store, for example:
|
||
|
|
```typescript
|
||
|
|
let store;
|
||
|
|
module.exports.getStore = () => {
|
||
|
|
if (!store) {
|
||
|
|
store = new UserCustomStore();
|
||
|
|
}
|
||
|
|
return store;
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
see [Redis store](../lib/utils/redis-store.js) for example
|
||
|
|
|
||
|
|
In order for app router to use it, user shall set ```externalStoreFilePath``` property in the ```EXT_SESSION_MGT``` env variable with the path to the storage.
|
||
|
|
The application router will use this path to require your storage.
|
||
|
|
|
||
|
|
The application router uses the defaultRetryTimeout and the backOffMultiplier properties in the EXT_SESSION_MGT environment variable to determine the Redis pattern for automatic retries of failed operations.
|
||
|
|
|
||
|
|
For example:
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"instanceName": "approuter-redis",
|
||
|
|
"storageType": "redis",
|
||
|
|
"sessionSecret": "someuniquesessionsecret",
|
||
|
|
"externalStoreFilePath": "./src/storage/my-special-storage",
|
||
|
|
"defaultRetryTimeout": 10000,
|
||
|
|
"backOffMultiplier": 10
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Credentials Structure when using Redis
|
||
|
|
|
||
|
|
Redis store can be used on both CF and Kyma, however the external session managment expects to receive the credentials in a certain structure,
|
||
|
|
similar to the structure of the CF redis service instance.
|
||
|
|
If you're using Kyma, create a [K8s secret](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-config-file/#create-the-config-file) that includes the credentials in the following structure:
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"cluster_mode": "(Mandatory) boolean",
|
||
|
|
"tls": "(Mandatory) boolean",
|
||
|
|
"ca_base64": "(Optional) string",
|
||
|
|
"sentinel_nodes": "(Optional) Array of objects of hostname and port, e.g '[{hostname: 127.0.0.1, port: 26543}]'",
|
||
|
|
"uri": "(Mandatory if using sentinel_nodes) string",
|
||
|
|
"password": "(Mandatory) string",
|
||
|
|
"hostname": "(Mandatory) string",
|
||
|
|
"port": "string"
|
||
|
|
}
|
||
|
|
```
|