Skip to content

Latest commit

 

History

History
113 lines (73 loc) · 6.11 KB

configuration.md

File metadata and controls

113 lines (73 loc) · 6.11 KB

Configuration

REMS contains a number of configuration options that can be used to alter authentication options, theming or to add integration points, just to name a few.

Configuration uses the cprop library. You can specify the location of the configuration file by setting the rems.config system property: java -Drems.config="../somepath/config.edn" -jar rems.jar You can also configure the application using environment variables as described in the cprop documentation.

The full list of available configuration options can be seen in config-defaults.edn.

REMS tries to validate your config file when starting. Errors or warnings will be logged for problems found in the configuration file.

Authentication options

Currently supported authentication methods are SAML2 and OpenId Connect (e.g. Auth0). Login method to be used can be defined with the key :authentication and the following values are recognized:

  • :shibboleth for SAML2
  • :oidc for OpenId Connect
  • :fake for development login

A link to an alternative login endpoint can also be shown if the :alternative-login-url option is set.

SAML2 (:shibboleth)

When using this option, login requests are directed to /Shibboleth.sso/Login.

OpenId Connect (:oidc)

The :oidc authentication method has the following configuration options:

  • :oidc-domain – the openid connect configration is fetched from https://{oidc-domain}/.well-known/openid-configuration
  • :oidc-client-id
  • :oidc-client-secret
  • :oidc-userid-attribute – which id-token attribute to use as the REMS userid. Defaults to "sub".
  • :oidc-additional-authorization-parameters - additional query parameters to add to the OIDC authorization_endpoint url when logging in
  • :oidc-extra-attributes - extra attributes to read. Check config-defaults.edn for the syntax.
  • :public-url - the redirect uri sent to the openid endpoint is {public-url}/oidc-callback

User attributes

By default, REMS reads the following attributes from the OIDC id token:

  • sub - the username
  • name, unique_name or family_name – looked up in this order to decide the display name for the user
  • email - user email

You can configure additional properties to read via the :oidc-extra-attributes configuration key. The additional attributes are only shown to users handling the application, and super-users like the owner and reporter. In praticular, application members cannot see the additional user properties of each other.

Development login (:fake)

This option should not be used in production. Keep also in mind that anyone with access to the dev/test server using development authentication can login with your fake credentials.

Entitlements

REMS can submit a HTTP POST request for every entitlement granted or revoked.

To use this feature, add :entitlements-target {:add "http://url/to/post/to" :remove "http://other/url"} to config.edn.

The payload of the POST request is JSON, and looks like this:

{"application": 137,
 "user": "username",
 "resource": "resource_name_maybe_urn_or_something",
 "email": "[email protected]"}

Localization

To add localization in a new language, make a copy of the English localization file and change the texts. Place it in a directory and configure :translations-directory to point to that directory. The localization file must be named after the language code. Add the language code to :languages to make it available in the application. You can change the default language by configuring :default-language.

For example, to add German localization, create a file my-translations/de.edn and use the following configuration:

{:translations-directory "my-translations"
 :languages [:de :en]
 :default-language :de}

Overriding default localizations

To override certain localization key, create a new folder called extra-translations under theme folder.

Create new localization files to the new directory. You don't need to copy whole localization files, it is enough to add only the localizations you want to override. For example to override English localizations for keys: administration.catalogue-item, administration.catalogue-items, applicant-info.applicant, applicant-info.applicants create the following en.edn file to the new translations folder.

{:t
 {:administration {:catalogue-item "Research item"
                   :catalogue-items "Research items"}
  :applicant-info {:applicant "Student"
                   :applicants "Students"}}}

Themes

Custom themes can be used by creating a file, for example my-custom-theme.edn, and specifying its location in the :theme-path configuration parameter. The theme file can override some or all of the theme attributes (see :theme in config-defaults.edn). Static resources can be placed in a public directory next to the theme configuration file. See example-theme/theme.edn for an example.

To quickly validate that all UI components look right navigate to /guide. See it in action at https://rems-demo.rahtiapp.fi/guide.

Extra pages

Extra pages can be added to the navigation bar using :extra-pages configuration parameter. Each extra page can be either a link to an external url or it can show the content of a markdown file to the user. See :extra-pages in config-defaults.edn for examples of how to define the extra pages.

Logging

REMS uses Logback for logging. By default everything is printed to standard output. If you wish to customize logging, create your own Logback configuration file and specify its location using the logback.configurationFile system property:

java -Dlogback.configurationFile=logback-prod.xml -jar rems.jar