Table of contents:

Introduction

The tenant configuration provides means to configure and customize certain settings of SOUP subscription (tenant). This page gives an overview over the available options.

Updating the tenant configuration is done via the Management API /api/mgmt/tenant-config collection and requires SYSTEM_ADMIN role (cf. SOUP Authorization).

Configuration options

Recipe template and validation

Recipe template

Key: soup.recipe.template

Handlebars template file that is used to generate the install representation of the recipe (also, recipe file).

Meta data validation

Key: soup.validation.metadata

Meta data validation rules for recipe, module update definition, and system distribution set meta data. Metadata could be used by the recipe-template, mandatory values for a valid recipe generation should be enforced here, with a validation rule.

// GET /api/mgmt/tenant-config/soup.validation.metadata
{
  "key": "soup.validation.metadata",
  "value": {
    "recipeRules": [
      {
        "metaDataKey": "exampleKey",
        "mandatory": true,
        "valueValidationRegex": "^(value1|value2|value3)$"
      }
    ],
    "systemDistributionSetRules": [
      {
        "metaDataKey": "exampleKey",
        "mandatory": false,
        "valueValidationRegex": "^[a-zA-Z0-9 .-]+$"
      }
    ],
    "moduleUpdateDefinitionWithDistributionSetRules": [
      {
        "metaDataKey": "exampleKey",
        "mandatory": true,
        "valueValidationRegex": "^(value1|value2|value3)$"
      }
    ],
    "moduleUpdateDefinitionWithoutDistributionSetRules": [
      {
        "metaDataKey": "exampleKey",
        "mandatory": true,
        "valueValidationRegex": "^[a-zA-Z0-9 .-]+$"
      }
    ]
  }
}

Artifact size validation threshold

Key: soup.validation.artifact.size.threshold.bytes

Configure the thresholds in bytes for the total file size validator of the recipe.

// GET /api/mgmt/tenant/soup.validation.artifact.size.threshold.bytes
{
  "key": "soup.validation.artifact.size.threshold.bytes",
  "value": "1048576"
}

Artifact size validation exclude

Key: soup.validation.artifact.size.excluded.softwaremodule.types

Exclude artifacts within software modules of a certain type from the Total file size validator calculation.

// GET /api/mgmt/tenant/soup.validation.artifact.size.excluded.softwaremodule.types
{
  "key": "soup.validation.artifact.size.excluded.softwaremodule.types",
  "value": ["release_notes", "collaterals"]
}

System report processing

Module identification

Key: soup.module.identification

Ruleset to specify the role, id fields, and updatability of each module in the system report.

// GET /api/mgmt/tenant-config/soup.module.identification
{
  "key": "soup.module.identification",
  "value": {
    "default": {
      "typeField": "type",
      "primaryIdField": "id",
      "nameField": "name",
      "role": "(DEFAULT|PRIMARY|REMOVABLE|TRACKED|IGNORED)",
      "updatable": true
    },
    "overwrites": [
      {
        "condition": {
          "myType": [
            "nextGen"
          ],
          "HwVersion": [
            "2.0",
            "3.0"
          ]
        },
        "overwrite": {
          "typeField": "myType",
          "primaryIdField": "myId",
          "nameField": "productName",
          "role": "REMOVABLE",
          "updatable": true
        }
      }
    ]
  }
}

Module property key override

Key: soup.module.identification.keymap

Map to provide overrides for identifiers in the recipe file. Works as input for the method createModuleIdentificationFromMatchAndMatchCountQuery that can be invoked within the recipe template.

// GET /api/mgmt/tenant/soup.module.identification.keymap
{
  "key": "soup.module.identification.keymap",
  "value": {
    "myOldKey": "myNewKey"
  }
}

Version property names

Key: soup.systemreport.version.property.names

System report property names, where the values contain version information. These properties are normalized respectively and natural sort ordering is applied when it comes to comparing version numbers. Version properties (hardware as well as software versions) must be configured here, otherwise the greater/lower comparison might generate unexpected results!

// GET /api/mgmt/tenant/soup.systemreport.version.property.names
{
  "key": "soup.report.validation.trusted.cert.fingerprints",
  "value": ["Version","HwVersion"]
}

Trusted fingerprints for signed reports

Key: soup.report.validation.trusted.cert.fingerprints

Fingerprint used to authenticate signed system- and update-reports in the backend (cf. Set up system- and update-report signing).

// GET /api/mgmt/tenant/soup.report.validation.trusted.cert.fingerprints
{
  "key": "soup.report.validation.trusted.cert.fingerprints",
  "value": ["51:92:CD:F2:39:B7:F5:01:5A:85:2F:1E:13:F4:B8:C3:99:76:C8:62:89:DF:7A:1E:C9:47:5F:21:6A:0E:8E:4B"]
}

Sign & Encrypt integration

Sign & Encrypt tenant

Key: signencrypt.tenant

Tenant name of the Sign & Encrypt tenant that is used to automatically trigger recipe signing tasks when promoting a recipe.

// GET /api/mgmt/tenant/signencrypt.tenant
{
  "key": "signencrypt.tenant",
  "value": "demo"
}

Sign & Encrypt device config Id

Key: signencrypt.deviceconfig.id

Sign & Encrypt device config id that is used for signing the recipe.

// GET /api/mgmt/tenant/signencrypt.deviceconfig.id
{
  "key": "signencrypt.deviceconfig.id",
  "value": "bda8566b-17f7-4893-a7a8-e6d08f86df08"
}

Role configuration

Role verification

Key: soup.role.verification.enabled

Enforce authorization via role-based-access-control based on the roles specified in SOUP Authorization.

// GET /api/mgmt/tenant/soup.role.verification.enabled
{
  "key": "soup.role.verification.enabled",
  "value": false
}

Role mapping

Key: soup.role.{basic, approve, system-admin, tag-admin, test-installer, update-coordinator}

Mapping of roles provided in the JWT to SOUP specific roles (cf. SOUP Authorization).

// GET /api/mgmt/tenant/soup.role.basic
{
  "key": "soup.role.basic",
  "value": "IdM-my-example-soup-basic-role-name"
}