Skip to main content
Skip table of contents

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

Default

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"
    }
  }
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.