Skip to content

Configuration.md

Latest commit

 

History

History
235 lines (181 loc) · 8.62 KB

Configuration.md

File metadata and controls

235 lines (181 loc) · 8.62 KB

Configuration

JSCAS uses nixconfig, nixconfig-toml, and nixconfig-yaml for loading configuration. This nixconfig name is jscas. Thus, a jscas.js, jscas.json, jscas.toml, jscas.yaml, or jscas.yml file within any of the following directories will be loaded:

  • /etc
  • /etc/jscas
  • ~
  • ~/.jscas
  • ~/.config/jscas

It is also possible to set the environment variable nixconfig_config_home to specify any other directory. This directory will be searched last, and the configuration within it will take precedence.

Default Configuration

The default configuration is viewable by reading /lib/config.js. The default configuration attempts to have "sane" values. There are some values that must be adjusted for any install to function properly, but a great deal of effort is made to keep this to a minimum.

In particular, the server, and protocol itself, relies on cookies to function. As a result, the most important configuration parameters deal with:

  1. The cookie settings for the application to keep track of session data.
  2. The cookie settings for the ticket granting ticket.

Parameters

Each heading in this section is a property on a root configuration object.

logger

The logger configuration property configures the included Pino instance. To learn about the available options, read Pino's documentation.

server

An object with the properties:

  • address (Default: '127.0.0.1'): the local IP address to bind to.
  • port (Default: 9000): the local port to use for listening.

caching

JSCAS uses an internal cache for things such as session storage. It is important that this configuration be updated to supply a proper backing store. The default uses an in-memory store that should not be relied upon in production.

This parameter accepts an object with the following properties:

  • privacy (Default: 'no-cache'): any value that is valid for the Cache-control header.
  • cacheSegment (Default: 'jscas'): the namespace to store cache values under.
  • cache (Default: an in-memory cache): This is an abstract-cache configuration object. An alternate driver should be specified to prevent the usage of the in-memory storage.

helmet

An configuration object to pass to fastify-helmet. The default value is {}.

dataSources

JSCAS makes various data sources available to registered plugins. The plugins to be used will dictate this configuration parameter. The bundled demonstration plugins do not require any data sources to be defined.

This parameter accepts an object with the following properties:

cookie

This parameter defines the settings that will be used when server sets ticket granting ticket cookies. It is important this parameter be configured properly.

This parameter accepts an object with the following properties:

  • domain (Default: '.cas.example.com'): this should be set to the specific domain for the CAS server.
  • path (Default: '/'): this should be set to the base path for the CAS server.
  • expires (Default: 1800000): time, in milliseconds, that the cookie should be valid. This time should be less than or equal to the cache lifetime.
  • secure (Default: true): specifies if the cookie should only be sent over HTTPS connections.
  • sameSite (Default: true): dictates if the cookie is allowed to be sent with cross site requests. See https://www.owasp.org/index.php/SameSite.
  • httpOnly (Default: true): dictates if the cookie can be read by scripts within a web page.

session

This parameter defines the settings governing the session used by the server to track users's authorization, and by plugins for various purposes.

The parameter accepts an object with the following properties:

  • secretKey (Default: insecure): it is imperitive this setting be adjusted. It must be a string of at least 32 characters. This setting is used to sign the session cookie.
  • sessionMaxAge (Default: 1800000): time, in milliseconds, that the session will be valid. This should be less than or equal to the cookie lifetime (typically equal).
  • cookie: the same possible settings as in cookie. It is recommended that the values be the same as the cookie configuration.

tickets

This parameter defines settings for the various tickets that comprise the CAS protocol.

This parameter accepts an object with the following properties:

  • serviceTicket: an object with the property ttl that defines the maximum lifetime, in milliseconds, that a service ticket is valid. The default lifetime is 10 seconds. This should be a very short time since a service ticket is only valid for one service verification.
  • ticketGrantingTicket: an object with the properties cookieName and ttl The cookieName defaults to 'jscas-tgt'. The ttl defaults to 1800000; this is the time, in milliseconds, that the ticket granting ticket will be valid. This should match the maximum age of the session.

v3overv2

This parameter toggles the ability to serve CAS protocol version 3 attributes to services via the CAS protocol version 2 endpoints. This parameter is a boolean that defaults to false.

saml11Banner9Hack

This parameter toggles inclusion of a UDC_IDENTIFIER attribute in /samlValidate responses. This is to enable compliance with the SIS product Banner 9. The value of the attribute will be set to the same value as the regular CAS user property, i.e. the "username".

This parameter is a boolean that defaults to false.

Note: the value of UDC_IDENTFIER gets mapped to a value in Banner's general.gobumap table.

plugins

This parameter defines the set of plugins that the server will use for various functionalities. A basic set of plugins is required for the server to function properly. Each value should be the name of a module that provides a corresponding plugin. If the name begins with ~/, then the plugin is loaded from the server's lib/plugins/ directory; this is only useful for the bundled demonstration plugins.

Any plugin name containing > indicates a nested plugin. Such plugins are a module that exports a hash of plugins. For example, if a plugin named foo returns the object:

{
  bar: function () {},
  baz: function () {}
}

Then the name foo>bar will load the bar plugin exported by the foo module.

This parameter accepts an object with the following properties:

  • attributesResolver (Default: ~/jsAttributesResolver): name of the module that provides an attributes resolver plugin. This plugin is required to properly support CAS protocol version 3.0, but is otherwise optional.
  • theme (Default: ~/basicTheme): name of the module that provides the user interface. This is a required plugin.
  • serviceRegistry (Default: ~/jsServiceRegistry): name of the module that provides the service registry. This is a required plugin.
  • ticketRegistry (Default: ~/jsTicketRegistry): name of the module that provides the ticket registry. This is a required plugin.
  • auth (Default: ['~/jsIdP']): this is an array of plugins that provide authenticators. At least one authenticator is required.
  • misc (Default: []): this is an array of plugins that provide miscellaneous additional functionality. No plugins are required in this category.

pluginsConf

This parameter defines the configuration for each of the supplied plugins.

This parameter accepts an object with properties that are equal to the names of the respective plugin they are for. As an example, if there is a miscellaneous plugin with the name "foo" registered, this parameter may look like:

{
  foo: {
    option1: 'value',
    option2: 'value'
  }
}