System (infrastructure) configuration

[]

Portal system configuration mainly defines how to reach the surrounding infrastructure, such as Headless CMS and SMTP server, and also contains some security settings. Make sure that you keep this configuration up-to-date.

Portal system configuration is set by the property portal in the JSON data (either config.json and/or the CONFIG variable). It interacts with the dynamic and design configuration for the portal as well as with the modules configuration when a portal is started or initialized. If the system configuration is missing or incomplete, initialization of a new portal will fail.

Below are the nested properties of this property, explained in detail.

Basic and DNS domain configuration

For production, this should be entered as portal-hcms property. See this article for other alternatives. Below is the list of the nested properties.

Property	Required	Value type	Default	Description
`id`	optional	string	The value specified in the `portalDomain` property.	Portal ID
`portalDomain`	required	string	-	DNS name of the domain; if multiple domains are accepted, enter the preferred one here.
`acceptAllDomains`	required	boolean	`false`	The default setting is secure. Please read this to learn more.

Security domain configuration

This is about domains in censhare terminology, not DNS domains. This setting is used by such entities as users and accepted terms.

Property	Nested property	Required	Value type	Default	Description
`securityDomain`		optional	string or JSON object	`root.`	If not specified, `root.` is assumed. A string value is taken from the `main` property if the rest is not specified.
`securityDomain`	`main`	optional	string	-	Main security domain; this is not used directly, only when `people` or `system` domain does not exist.
`securityDomain`	`people`	optional	string	Value from `main` concatenated with `people.`	Domain for people (user accounts).
`securityDomain`	`system`	optional	string	Value from `main` concatenated with `system.`	Domain for the "accepted terms" assets: assets created whenever a user accepts Terms Of Service.

Default roles for new users

This property is very useful to allow new users immediate access to new custom modules.

Property	Required	Value type	Default	Description
`defaultRoles`	optional	string[]	When present, it overrides current configuration of the authentication module.

Connection to HeadlessCMS

Property	Nested property	Nested property	Required	Value type	Default	Description
`hcms`			required	JSON object	-	See nested properties.
`hcms`	`jwt`		required	JSON object	-	See nested property.
`hcms`	`jwt`	`hmacSecret`	required	string	-	HMAC secret configured in the HCMS configuration.
`hcms`	`urlPathPrefix`		-	string	-	Unused. A complete URL is set in the `url` property (see below). The property is kept for the backward compatibility, to resolve some placeholders.
`hcms`	`url`		required	string	-	Headless CMS base URL. Note that the part with the HCMS version number is mandatory! (e.g., `hcms/v1.0` )
`hcms`	`acceptedHostnames`		optional	string	`{@link #url}`	Regular expression with accepted hostnames for HCMS requests. Not recommended and only meant for the multi-domain setup, side effect are security holes.

SMTP server configuration

This configuration is required for sending emails and can be alternatively filled in on runtime, in the portal GUI, under Settings -> Authentication -> Mail.

Property	Nested property	Required	Value type	Description
`mailConfig`		optional	JSON object
`mailConfig`	`server`	optional	string	SMTP server
`mailConfig`	`port`	optional	string	SMTP port
`mailConfig`	`username`	optional	string	SMTP server username
`mailConfig`	`password`	optional	string	SMTP server pwaaword
`mailConfig`	`sender`	optional	string	Email that will appear as sender.

Initial workflow and workflow state

In censhare system, an asset (typically, a media file in the portal) can have a workflow, like an approval workflow. This property will specify which workflow should be assigned to new assets (e.g., newly uploaded files) and also set the initial workflow step.

There is one property for both. Values are concatenated using .. Also, their ids should be used; the actual descriptions can be checked in the censhare system. The mapping is stored in its master data. Example value: 900001.10..

Property	Required	Value type	Default	Description
`initialWorkflowState`	optional	string	-	Initial workflow and workflow state, combined.

OpenID integration configuration

Read more about the OpenID - authentication server - integration here.

openid is a property of the JSON object type (not a list!) where you should enter all your OpenID providers; each provider should have their own property, but their nested properties should be the same. The values can be obtained from the provider. Please also refer to the official theird-party documentation on the meaning of certain fields and requirements to their values. We only add some notes for the most popular OpenID providers.

Property	Nested property	Nested property	Required	Value type	Default	Description
`openid`			optional	JSON object	-	See nested properties.
`openid`	`[providerId: string]`		required	JSON object	-	Create an id for your provider.
`openid`	`[providerId: string]`	`name`	optional	string	`providerId`	Name of the provider.
`openid`	`[providerId: string]`	`logo`	optional	string	Value of `name`	Link to the provider logo. Must be a valid HTTPS link, as it is directly rendered into `<img src=""/>` element on the login page.
`openid`	`[providerId: string]`	`issuer_url`	required	string	-	Base URL of the provider.
`openid`	`[providerId: string]`	`client_id`	required	string	-	Client ID.
`openid`	`[providerId: string]`	`client_secret`	required	string	-	Client secret.
`openid`	`[providerId: string]`	`scope`	required	string	`openid email profile`	Scope, e.g., a shared protocol and role mappings. The default value should suffice for most providers.
`openid`	`[providerId: string]`	`logout_id_token_hint`	optional	boolean	-	By default, HCMS Client does not remember this token and thus does not add it.
`openid`	`[providerId: string]`	`accountPairBy`	optional	string	-	Automatically pair existing account assets by specified value. Only `email` is actually supported for now. When not set, existing accounts are used only when they have the proper `openid.sub` which is the most secure option. When set to `email`, and the user tries to log in for the first time, and their email matches with the provider database, an `openid.sub` will be set for them.
`openid`	`[providerId: string]`	`autoCreate`	optional	boolean	`false`	The property specifies if a new account representation should be created for the user if no account asset in the censhare system or entity in HCMS has been found for them, neither by `openid.sub` nor by the value set in the `accountPairBy`. I.e., it adds the value for `openid.sub` as a property to the account asset which in it's turn stored as a feature on the user asset. On default behaviour, the user login just fails.
`hideStandardLogin`			optional	boolean	-	Specifies if the standard login page should be shown or hidden before the user is redirected to an OpenID provider. The login page is always skipped if only one OpenID provider is configured. This flag can be dynamically suppressed by the user by going to the special URL `/#/login?showStandardLogin=1` which forces the login form to be shown.
`openid_landing`			optional	JSON object	-	Landing pages where the user ends up after the OpenID login or logout. Intended only to be used for local development and debugging, please avoid in production.
`openid_landing`	`after_logout`		optional	string	-	Landing page after the logout.
`openid_landing`	`after_login`		optional	string	-	Landing page after the successful login.
`openid_landing`	`base`		optional	string	-	The URL base. When used, the other paths can be relative.

Keycloak-specific configuration

Please keep in mind that for the issuer_url property, you need to enter a URL that ends with realms/ and the name of the realm, e.g, for the censhare realm: realms/censhare.

OKTA-specific configuration

In the scope, you can use offline_access to force refresh the token.
logout_id_token_hint is required for this provider.

Schema directory during build

This property is very critical as it makes sure that the application can be built. Please read this article to learn more about the roles schemas play and what this property specifies.

Property	Nested property	Required	Value type	Default	Description
`schemas`	`dir`	mandatory	string	-	-

Example

Content of CONFIG variable:

JSON

{
  "sessionSecret": "ZQa8ELqNNjROXRXdk8P1iNjnwOdeG4iLsU6ioNKSvfnFQBG1z1OsictU+oQPLVWZpW2naqDc/D95FVczHCLK32O1HIDWEK33LCNCAS23wecck",
  "portal-hcms": {
     "portalId": "babo-hcms-dev",
  },
  "portal": {
    "id": "babo-hcms-dev",
    "portalDomain": "babo-hcms-dev.demo.censhare.com",
    "securityDomain": "root.hcms.",
    "hcms": {
      "jwt": {
        "hmacSecret": "zHQFnysgkIxxxxxx-censored"
      },
      "url": "https://babo-hcms-dev.demo.censhare.com/hcms/v1.0",
      "urlPathPrefix": ""
    },
    "mailConfig": {
      "password": "censored",
      "port": 587,
      "sender": "cs-mediaportal@web.de",
      "server": "smtp.web.de",
      "username": "cs-mediaportal@web.de"
    }
  }
}