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 |
---|---|---|---|---|
| optional | string | The value specified in the | Portal ID |
| required | string | - | DNS name of the domain; if multiple domains are accepted, enter the preferred one here. |
| required | boolean |
| 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 |
---|---|---|---|---|---|
| optional | string or JSON object |
| If not specified, | |
|
| optional | string | - | Main security domain; this is not used directly, only when |
|
| optional | string | Value from | Domain for people (user accounts). |
|
| optional | string | Value from | 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 |
---|---|---|---|---|
| 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 |
---|---|---|---|---|---|---|
| required | JSON object | - | See nested properties. | ||
|
| required | JSON object | - | See nested property. | |
|
|
| required | string | - | HMAC secret configured in the HCMS configuration. |
|
| - | string | - | Unused. A complete URL is set in the | |
|
| required | string | - | Headless CMS base URL. Note that the part with the HCMS version number is mandatory! (e.g., | |
|
| optional | string |
| 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 | Default | Description |
---|---|---|---|---|---|
| optional | JSON object | |||
|
| optional | string | SMTP server | |
|
| optional | string | SMTP port | |
|
| optional | string | SMTP server username | |
|
| optional | string | SMTP server pwaaword | |
|
| 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 |
---|---|---|---|---|
| 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 |
---|---|---|---|---|---|---|
| optional | JSON object | - | See nested properties. | ||
|
| required | JSON object | - | Create an id for your provider. | |
|
|
| optional | string |
| Name of the provider. |
|
|
| optional | string | Value of | Link to the provider logo. Must be a valid HTTPS link, as it is directly rendered into |
|
|
| required | string | - | Base URL of the provider. |
|
|
| required | string | - | Client ID. |
|
|
| required | string | - | Client secret. |
|
|
| required | string |
| Scope, e.g., a shared protocol and role mappings. The default value should suffice for most providers. |
|
|
| optional | boolean | - | By default, HCMS Client does not remember this token and thus does not add it. |
|
|
| optional | string | - | Automatically pair existing account assets by specified value. Only |
|
|
| optional | boolean |
| 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 |
| 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 | ||
| 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. | ||
|
| optional | string | - | Landing page after the logout. | |
|
| optional | string | - | Landing page after the successful login. | |
|
| 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 useoffline_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 |
---|---|---|---|---|---|
|
| mandatory | string | - | - |
Example
Content of CONFIG
variable:
{
"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"
}
}
}