Configuration

Karma ships with a simple textbased property configuration.

This document describes:

• the options and the coresponding functionality whos controlled in property files
• which values the options could have
• what are the defaults

configuration files

Normally you will find the configuration files in the ~/config directory on the server. These files maybe YAML, JSON or JavaScript.

Following you will find the loading order of these files (a later file extends/overwrites a previous file):

 - `<hostName>.yaml`: foo.yaml
 - `<hostName>-<NODE_APP_INSTANCE>.yaml`: foo-beta.yaml
 - `<NODE_ENV>.yaml`: development.yaml or production.yaml
 - `<NODE_ENV>-<NODE_APP_INSTANCE>.yaml`: development-beta.yaml
 - `<hostName>-<NODE_ENV>-<NODE_APP_INSTANCE>`: foo-production-beta.yaml
 - local.yaml
 - `local-<NODE_APP_INSTANCE>.yaml`: local-beta.yaml
 - `local-<NODE_ENV>.yaml`: local-production.yaml
 - `local-<NODE_ENV>-<NODE_APP_INSTANCE>.yaml`: local-production-foo.yaml

main parts

log:

options to adjust the loglevel of the programm parts. For normal purpose we use the loglevel 'warn' and 'debug' for troubleshooting. You can control the amount of messages based on componentents.

log:
  level: info
  components:
    # bootstrap: trace
    # initialize: trace
    # finalize: trace
    # initialize: trace
    # http: trace
    # ldap: trace
    # rbpm: trace

loglevel could be: trace, debug, info, warn, error

Network Parts

http:

This configuration is used for the frontened part of the application.

http.server:

In that pattern you can change the IP-Adress and the Port. We recommend the using of a http webserver (Apache or NGinx) as a proxy server for the application becouse of better performance.

Example:

http:
  server:
    port: 9999
    host: 127.0.0.1

http.assets:

In the asset directory you can store the custimized images, logos or templates. The configuration is relative relative to CONFIG_DIR.

http:
  assets: ./assets

http.auth:

The http auth part also controlling the authentification and autorization for the application. The parameter realm, tokenExpirationTimeand tokenSecret are used for the internal (Karma) token handling. Please be aware if you configure a loadbalanced system, use the same tokenSecret for all cluster members.

http:
  auth:
    realm: Karma
    tokenExpirationTime: 10h
    # openssl rand -base64 48
    tokenSecret: jEW+o75aFvJ6ZrpfocQVVtqiTx12f5SHMHNpSCrGCm1izYinYAXLuuehvRMPH1AG

Karma supports mainly three different types of authorization options.

• without any parameter -> local LDAP auth with an karma-own form.
• use Micro Focus OSP (One SSO Provider, packaged in Micro Focus IDM) as identity provider with the parameter http.auth.osp.* and http.auth.sso.* -> How to configure
• using header informations from an front proxy configuration (a.e. NAM) -> http.auth.requestHeader parameter

http:
  auth:
    osp:
      baseUrl: https://karma-ui.kenoxa.com
      clientId: k5-local
      clientSecret: clientSecret
    sso:
      logoutUrl: https://userapp.kenoxa.com/osp/a/idm/auth/app/logout
      landingUrl: https://userapp.kenoxa.com/landing/
      
      # SSO injection using HTTP Header
      requestHeader:
        # the header name
        name: REMOTE_USER
        # LDAP filter to query matching user
        # '%s' is replaced with value of header
        # used together with users.filter to create resulting filter
        # -> (&<%= users.filter %>(<%= users.id %>=%s))
        # filter: (&(<%= users.id %>=%s)(groupMembership=cn=karma,ou=groups,o=data))
        filter: '(<%= users.id %>=%s)'
        base: '<%= users.base %>'
        scope: '<%= users.scope %>'

The toobusy parameter controls if and when Karma refused to server any more requests. Basically this says if Karma needs more than this time to accept a new request it rejects this request by sending a 503 status code.

http:
  toobusy: 248ms

ldap:

Here you can configure the binding options for the main LDAP Server. If you configure a secure connection (ldaps) don't forget to check the ca parameter to configure the root-ca.

Optional you can encrypt some config values (ldap.bindDN, ldap.bindCredentials, rbpm.credentials.username and rbpm.credentials.password). See encryption section for more informations.

ldap:
  url: ldaps://ldap.kenoxa.com
  # use tlsOptions only for test purposes
  # tlsOptions: {rejectUnauthorized: false}
  bindDN: ENC(pcQUIcvRKTrdjClyDcogsTR6U_29DHFlsBDObe234567654323Z0UY9upEk5w)
  bindCredentials: ENC(6copvOvkK5UAAymvzkbReUJkO23456765432ZfuOe)

ldap.capabilities.proxyAuthorization

since v2.8.24

Use Proxied Authorization Control (RFC 4370) for ACL evaluation when available (since eDirectoy 9.0); this can be disabled and reverted to the old behavior (simple check on the ACL attribute for each entry) using:

ldap:
  capabilities:
    proxiedAuthorization: false

For this feature to work, the Karma LDAP Proxy account must have supervisor rights on the impersonated user. See here for more details and configuration.

additional ldap config

ldap:
  singleValueAttributes:
      - internetEMailAddress preferredLanguage salutation surname
  search:
    noCount: true
  capabilities:
    # preventEdirectorySimpleQueryBug: true
    # proxiedAuthorization: false
    search:
      ## eDir 8.x (small dataset)
      ## eDir 9.x (small/medium dataset)
      # paging: 'virtualListView'
      # serverSideSorting: true
      ## eDir 9.x (large dataset)
      paging: 'pagedResults'
      serverSideSorting: false
      ## eDir 8.8 (medium/large dataset)
      # paging: false
      # serverSideSorting: false
      # estimatedSize: false

rbpm

rbpm:
  url: https://userapp.kenoxa.com/IDMProv
  href: https://userapp.kenoxa.com/IDMProv
  allowedRestActions:
    - requestRolesAssignment
  driverRoot: 'cn=UserApplication,cn=driverset1,o=system'
  credentials:
    username: uaadmin
    password: novell
  defaultProvisioningRequestsCategory: dashboard
  provisioningRequestCategories:
    - accounts
    - attestation
    - nrf
    - service
    - entitlements

Enabling bulk approval for tasks

The bulk approval feature allows you to approve or deny multiple tasks in a single step. The standard role approval is bulk approvable by default. For custom workflows, you need to enable the feature by adding a hidden boolean form field bulkApprovable to your approval form configuration ...

... and set it to true in the Pre Data Item mapping

UI Object configuration

users:

users:
  base: <%= partitions.identity.users.base %>
  filter: '(structuralObjectClass=inetOrgPerson)'
  login:
    filter: '(objectClass=Person)'
  primaryPartitionAttribute: pager
  childObjectDNsAttribute: directReports

users.searchAttributes:

since v2.8.6

Search attributes can now be defined in the configuration file. If omitted defaults apply.

• The $id is the ldap attribute to be searched.
• The label may be a plain text value or an translation key (see below: Custom i18n).

users:
  searchAttributes:
    - {$id: '$id', label: 'k5SiteSearch.attributes.id'}
    - {$id: '$name', label: 'k5SiteSearch.attributes.login'}
    - {$id: '$description', label: 'k5SiteSearch.attributes.description'}
    - {$id: 'givenName', label: 'k5SiteSearch.attributes.givenName'}
    - {$id: 'sn', label: 'k5SiteSearch.attributes.surName'}
    - {$id: 'mail', label: 'k5SiteSearch.attributes.mail'}
    - {$id: 'some-custom-field', label: 'Some Custom Field'}

Defaults:

users:
  searchAttributes:
    - {$id: '$id', label: 'k5SiteSearch.attributes.id'}
    - {$id: '$name', label: 'k5SiteSearch.attributes.login'}
    - {$id: '$description', label: 'k5SiteSearch.attributes.description'}
    - {$id: 'givenName', label: 'k5SiteSearch.attributes.givenName'}
    - {$id: 'sn', label: 'k5SiteSearch.attributes.surName'}
    - {$id: 'mail', label: 'k5SiteSearch.attributes.mail'}

accounts:
  searchAttributes:
    - {$id: '$id', label: 'k5SiteSearch.attributes.id'}
    - {$id: '$name', label: 'k5SiteSearch.attributes.login'}
    - {$id: '$description', label: 'k5SiteSearch.attributes.description'}
    - {$id: 'givenName', label: 'k5SiteSearch.attributes.givenName'}
    - {$id: 'sn', label: 'k5SiteSearch.attributes.surName'}
    - {$id: 'mail', label: 'k5SiteSearch.attributes.mail'}

roles:
  searchAttributes:
    - {$id: '$id', label: 'k5SiteSearch.attributes.id'}
    - {$id: 'nrfLocalizedNames', label: 'k5SiteSearch.attributes.name'}
    - {$id: 'nrfLocalizedDescrs', label: 'k5SiteSearch.attributes.description'}

users.cardattributes

since v2.8.14

user & account card attributes are configurable

The attributes shown in the cards of search results for user and account are configurable.

users:
  # the defaults are mail, telephoneNumber, roomNumber and container
  cardAttributes: mail telephoneNumber roomNumber

users.childObjectDNsAttribute

since 2.8.20

The relation between a user and its accounts can be configured and shown in the UI. Once configured a new panel is added to the user screen showing tha associated accounts and there roles. (coresponding property: accounts.parentObjectDNsAttribute)

To enable this feature adjust your configuration:

users:
  # defines which multi-value attribute at the user contains the account DNs
  childObjectDNsAttribute: directReports

users.hideResourcesPanel

since 2.9.1

The resources panels can be disabled - it is not only hidden but the attributes are not requested from the ldap server

users:
  hideResourcesPanel: true

users.rolesFilterDefaultHidden

since 2.11.0

On the roles panel the roles can additionally be filtered by assignment type, level and category.

users: # works identically for accounts
  # defines which options are not selected by default
  # if not set all options are enabled by default
  rolesFilterDefaultHidden:
    # each value can be an array, comma or space separated string
    assigments: container # possible values: 'assigned', 'group', 'container'
    levels: # possible values: 10, 20, 30
    categories: system # any category defined in the UA

users.historyAttributes

since 2.11.0

The history tab and its content is configurable for users and accounts

users:
  # mapping from kind to ldap attribute
  historyAttributes:
    # the default configuration
    userID: 'k5UserIDHistory'
    role: 'k5RoleHistory'
    saphr: 'k5SaphrHistory'
    resource: 'nrfResourceHistory'
    lifecycle: 'k5UserLifecycle'

accounts:
  historyAttributes:
    # only hide resources, all others use the default config shown above
    resource: false

  # it is possible to hide the tab completly
  historyAttributes: false

users.businessCategories

since 2.11.0

The organizational units below users and accounts can now be used to narrow down a search. Organizational units are grouped into primary and secondary. For each of these you can define which businessCategory (an ldap attribute on organizational unit) belongs to primary or secondary.

Note:

• Each primary OU should be hierarchically before any secondary OU.
• To use this feature effectivly a value index on businessCategory should exist.

Features

• filtered searches based on organizational units
• breadcrumbs have links to organizational unit search
• the ldap base for accounts maybe configured for each partition

users:
  businessCategories:
    primary: department
    # value can be an array, comma or space separated string
    secondary: section costCenter

accounts:
  businessCategories:
    # just use same as users
    primary: <%= users.businessCategories.primary %>
    secondary: <%= users.businessCategories.secondary %>

Styling

Each businessCategory should have a own icon to distinguish them. In the custom css file define each businessCategory using a font-awesome icon.

/* using https://fontawesome.com/v4.7.0/icon/building for businessCategory: section */
.fa-section:before { content: "\f1ad"; }

users.actions

To start a workflow on the viewed user object in karm, you can use actions. The worklfow consumes the selected user by fromstate.recipient. To use this feature, you have to use Karma forms - otherwise Karma can't render the approval form.

users:
  actions:
    -
      # icon: ...
      # style: default
      workflow: cn=does-not-exist,cn=RequestDefs,cn=AppConfig,cn=UserApplication,cn=Driver Set,o=system
      # can be a karma role (user, admin, guest) or the DN of a user, group, role or conatiner
      # The role or DN specified here will be allowed to trigger the action by default
      # However, you can override the setting by changing the rule 'can trigger action' beneath `request` in your `rules.js`
      authz: user
      formState:
        recipient: <%= users.formState.initiator %>

additional config

users:
  patchAttributes:
    - telephoneNumber facsimileTelephoneNumber roomNumber street l postalCode
  roles:
    admin: '(groupMembership=cn=idm-admin,ou=groups,o=data)'
    user : true
    guest: true

obsolete config

since 2.10.0

The configuration options: detailAttributes and sapAttributes are now obsolete. Please use the new panel configuration instead.

detailAttributes:
    # configuration of showing attributes in detail panel
    manager[]:
      label: Child Objects
      type: entry
    employeeNumber: Mitarbeiternummer
    employeeStatus: Mitarbeiterstatus
    employeeType: Mitarbeitertyp
    passwordRequired: Passwort benötigt
    passwordAllowChange: Passwortänderung möglich
    passwordUniqueRequired: Eindeutiges Passwort nötig

accounts:

accounts:
  base: ' '
  filter: "(&\
    (objectClass=nrfRole)\
  )"
  parentObjectDNsAttribute: manager

accounts.searchAttributes:

since v2.8.6

Search attributes can now be defined in the configuration file. If omitted defaults apply.

• The $id is the ldap attribute to be searched.
• The label may be a plain text value or an translation key (see below: Custom i18n).

acounts:
    searchAttributes:
    - {$id: '$id', label: 'k5SiteSearch.attributes.id'}
    - {$id: '$name', label: 'k5SiteSearch.attributes.login'}
    - {$id: '$description', label: 'k5SiteSearch.attributes.description'}
    - {$id: 'givenName', label: 'k5SiteSearch.attributes.givenName'}
    - {$id: 'sn', label: 'k5SiteSearch.attributes.surName'}
    - {$id: 'mail', label: 'k5SiteSearch.attributes.mail'}

accounts.cardattributes

since v2.8.14

user & account card attributes are configurable

The attributes shown in the cards of search results for user and account are configurable.

acounts:
  # the defaults are mail, telephoneNumber, roomNumber and container
  cardAttributes: mail telephoneNumber roomNumber

accounts.parentObjectDNsAttribute

since 2.8.20

The relation between a user and its accounts can be configured and shown in the UI. Once configured a new panel is added to the user screen showing tha associated accounts and there roles. (coresponding property: users.ChildObjectDNsAttribute)

To enable this feature adjust your configuration:

acounts:
  # defines which attribute (single or multi-value) at the account contains the user DN
  parentObjectDNsAttribute: manager

accounts.hideResourcesPanel

since 2.9.1

The resources panels can be disabled - it is not only hidden but the attributes are not requested from the ldap server

acounts:
  hideResourcesPanel: true

accounts.actions:

-> See on users.action

account.rolesFilterDefaultHidden

-> See on users.rolesFilterDefaultHidden

account.historyAttributes

-> See on users.historyAttributes

account.businessCategories

-> See on users.businessCategories

groups:

groups:
  base: 'ou=groups,o=data'
  scope: one

organizational Units:

organizationalUnits:
  base: ' '
  scope: 'sub'
  filter: "(&\
    (structuralObjectClass=organizationalUnit)\
    (|\
      (ou:dn:=kenoxa)\
      (ou:dn:=NetIQ)\
    )\
    (ou:dn:=users)\
  )"

roles:

roles.searchAttributes:

since v2.8.6

Search attributes can now be defined in the configuration file. If omitted defaults apply.

• The $id is the ldap attribute to be searched.
• The label may be a plain text value or an translation key (see below: Custom i18n).

roles:
   searchAttributes:
    - {$id: '$id', label: 'k5SiteSearch.attributes.id'}
    - {$id: 'nrfLocalizedNames', label: 'k5SiteSearch.attributes.name'}
    - {$id: 'nrfLocalizedDescrs', label: 'k5SiteSearch.attributes.description'}

roles:
  sort: 'nrfLocalizedNames'

basket integration:

orders:
  base: 'cn=k5Orders,ou=karma,ou=res,ou=services,o=data'
  nrfRequestTemplate:
    nrfStatus: '5'

orderItems:
  base: 'cn=GlobalInputRequests,cn=nrfConfig,ou=res,ou=services,o=data'

certificate store:

ca:
  # openssl s_client -showcerts -connect ldap.kenoxa.com:636 </dev/null
  - ldap-ca.pem
  - ldap.pem

main UI features:

ui:
  features:
    accounts: true
    shoppingCart: true
    tools: true
    reports: true

  assets:
    # path within config/assets to an image shown in the header
    logo: logo.png
    # path within config/assets for an additional stylesheet to load
    styles: styles/custom.css

runInContext:

runInContext:
  scripts:
    'cn=k5-check-user,cn=UserApplication,cn=driverset1,o=system': './forms/check//wf.js'

dal:

Further documentation about Forms and dal you can find here.