mirror of https://gitee.com/bigwinds/arangodb
146 lines
5.1 KiB
Plaintext
146 lines
5.1 KiB
Plaintext
!CHAPTER Foxx Sessions
|
|
|
|
Foxx provides some convenience methods to make working with sessions easier.
|
|
|
|
!SUBSECTION Activate sessions
|
|
|
|
Enables session features for the controller.
|
|
|
|
`controller.activateSessions(options)`
|
|
|
|
Once sessions have been activated, a *session* property will be added to the *request* object passed to route handlers defined on the controller, which will be a saved instance of the session model provided by the session storage.
|
|
|
|
If the option *autoCreateSession* has not explicitly been set to *false*, a new session will be created for users that do not yet have an active session.
|
|
|
|
If *type* is set to *"cookie"*, the session cookie will be updated after every route.
|
|
|
|
*Parameter*
|
|
|
|
* *options* (optional): an object with any of the following properties:
|
|
* *sessionStorageApp* (optional): mount point of the session storage app to use. Default: *"/_system/sessions"*.
|
|
* *type* (optional): sessions type, currently only *"cookie"* and *"header"* are supported. Default: *"cookie"*.
|
|
* *cookie* (optional): an object with the following properties:
|
|
* *name*: name of the session cookie if using cookie sessions. Default: *"sid"*.
|
|
* *secret* (optional): secret string to sign session cookies with if using cookie sessions.
|
|
* *algorithm* (optional): algorithm to sign session cookies with if using cookie sessions. Default: *"sha256"*.
|
|
* *header* (optional): name of the session header if using header sessions. Default: *"X-Session-Id"*.
|
|
* *jwt* (optional): whether the session ID should be wrapped in a JSON Web Token. Default: *false*.
|
|
* *autoCreateSession* (optional): whether a session should always be created if none exists. Default: *true*.
|
|
|
|
If *cookie* is set to a string, its value will be used as the *cookie.name* instead.
|
|
|
|
Optionally *jwt* can be an object with any of the following values:
|
|
|
|
* *secret* (optional): secret string to sign session JSON Web Tokens with.
|
|
* *algorithm* (optional): algorithm to sign session JSON Web Tokens with. Default: *"HS256"* if a *secret* is provided, *"none"* otherwise.
|
|
* *verify* (optional): whether incoming session JSON Web Tokens should be verified. Default: *true*.
|
|
|
|
If *jwt* is set to a string, its value will be used as the *jwt.secret* instead.
|
|
|
|
Note that if the *jwt.algorithm* is explicitly set to any algorithm other than *"none"*, not providing a *jwt.secret* will raise an exception.
|
|
|
|
*Examples*
|
|
|
|
Example configuration for using signed cookies:
|
|
|
|
```js
|
|
var controller = new FoxxController(applicationContext);
|
|
controller.activateSessions({
|
|
sessionStorageApp: '/_system/sessions',
|
|
cookieName: 'sid',
|
|
cookieSecret: 'secret',
|
|
type: 'cookie'
|
|
});
|
|
```
|
|
|
|
Example configuration for using a header:
|
|
|
|
```js
|
|
var controller = new FoxxController(applicationContext);
|
|
controller.activateSessions({
|
|
sessionStorageApp: '/_system/sessions',
|
|
headerName: 'X-Session-Token',
|
|
type: 'header'
|
|
});
|
|
```
|
|
|
|
Example configuration for using a JWT header:
|
|
|
|
```js
|
|
var controller = new FoxxController(applicationContext);
|
|
controller.activateSessions({
|
|
sessionStorageApp: '/_system/sessions',
|
|
headerName: 'X-Web-Token',
|
|
jwt: 'keyboardcat',
|
|
type: 'header'
|
|
});
|
|
```
|
|
|
|
Example configuration for using a JWT header with signature algorithm "none" (and no secret):
|
|
|
|
```js
|
|
var controller = new FoxxController(applicationContext);
|
|
controller.activateSessions({
|
|
sessionStorageApp: '/_system/sessions',
|
|
headerName: 'X-Web-Token',
|
|
jwt: true,
|
|
type: 'header'
|
|
});
|
|
```
|
|
|
|
Example configuration for using a JWT header with signature verification disabled:
|
|
|
|
```js
|
|
var controller = new FoxxController(applicationContext);
|
|
controller.activateSessions({
|
|
sessionStorageApp: '/_system/sessions',
|
|
headerName: 'X-Web-Token',
|
|
jwt: {
|
|
verify: false
|
|
},
|
|
type: 'header'
|
|
});
|
|
```
|
|
|
|
Example configuration for using signed JWT cookies:
|
|
|
|
```js
|
|
var controller = new FoxxController(applicationContext);
|
|
controller.activateSessions({
|
|
sessionStorageApp: '/_system/sessions',
|
|
cookieName: 'token',
|
|
cookieSecret: 'secret',
|
|
jwt: 'keyboardcat',
|
|
type: 'cookie'
|
|
});
|
|
```
|
|
|
|
Example configuration for using unsigned cookies:
|
|
|
|
```js
|
|
var controller = new FoxxController(applicationContext);
|
|
controller.activateSessions({
|
|
sessionStorageApp: '/_system/sessions',
|
|
cookieName: 'sid',
|
|
type: 'cookie'
|
|
});
|
|
```
|
|
|
|
!SUBSECTION Define a session destruction route
|
|
|
|
Defines a route that will destroy the session.
|
|
|
|
`controller.destroySession(path, options)`
|
|
|
|
Defines a route handler on the controller that destroys the session.
|
|
|
|
When using cookie sessions, this function will clear the session cookie (if *autoCreateSession* was disabled) or create a new session cookie, before calling the *after* function.
|
|
|
|
*Parameter*
|
|
|
|
* *path*: route path as passed to *controller.get*, *controller.post*, etc.
|
|
* *options* (optional): an object with any of the following properties:
|
|
* *method* (optional): HTTP method to handle. Default: *"post"*.
|
|
* *before* (optional): function to execute before the session is destroyed. Receives the same arguments as a regular route handler.
|
|
* *after* (optional): function to execute after the session is destroyed. Receives the same arguments as a regular route handler. Default: a function that sends a *{"message": "logged out"}* JSON response.
|