6.1 Access Controller

  provides different Tools to, for example, view logs, statistics, and pico instance information, and to import and export configurations.

To be able to operate, you need to be defined as a user in the system. Your access to various applications is defined by the access group that you are assigned with. The Execute permission means that members of an access group can use a certain application. To applications that include configurable parameters you apply the Write permission.

Note!

  • By default, members of the predefined group Administrator have full permissions for the Access Controller. You can enable these permissions for other groups as well.
  • When no members belong in the Administrator group, all users with full permissions for the Access Controller will have Administrative access.
  • It is not possible to disable or delete the last active user with full permissions for the Access Controller. This is to prevent system lockout.
  • Members that are not part of the Administrator group will not be able to remove or modify the Administrator group and any of its group members.
  • Only one user may use the Access Controller with write permissions at any given time.
  • It is not possible to delete the last group with members that have full permissions for the Access Controller. This is to prevent system lockout.
  • By setting the Platform property mz.security.user.restricted.login to true, access is restricted to one login for each interface type:

    • Desktop

    • Web Interface

    • Command Line Tool mzsh

  • It is possible to use SCIM via the REST HTTP interface to POST, GET, DELETE, PUT and PATCH user and group configurations.
  • By default, installation is done with Platform property mz.userserver.filebased set to true, where Access Controller data is stored in files under the $MZ_HOME directory, so it is important that the read/write permissions for $MZ_HOME are given only to authorized unix users or unix user groups.

To open the Access Controller, click the Tools button in the upper left part of the Desktop window, and then select Access Controller from the menu.

Users Tab

In , the default user, mzadmin, will always have full permissions for any activity.

It is recommended that the password for mzadmin is changed and kept in a safe place. Instead personal accounts should be created and used for handling the system in order to track changes.

To Add a User:

  1. Open the Users tab.
  2. Select the File menu and then Add.

      
    Access Controller - Users tab

  3. Fill in the details according to the description below. 
SettingDescription

Enable User

Check to enable the user's predefined access rights

Username

Enter the name of the user. Valid characters are: A-Z, a-z, 0-9, '-' and '_'.

Note!

A username must be unique. This also applies if you use an external authentication method, e g LDAP.

Full Name

Enter a descriptive name of the user.

Email

Enter the user's e-mail address. This address will be automatically applied to applications from which e-mails may be sent.

Password

Enter a password for the user account.

Verify Password

Re-enter the password.

SuccessorA successor must be defined in the case you want to remove a user that has ownership of configuration objects.
Validity Period

A defined period of time when a particular user has access rights to .

When the validity period expires, the user will be unable to login or access the system until the validity period is renewed by an administrator.

Note!

If a user has the Enable User option disabled and the validity period is still valid, the user will not have access rights.

Note!

When defining the dates for the validity period, you will not be able to choose dates that are earlier than the current day. This applies to editing existing users and creating new users.

Group

Enter a comma delimited list of all the access groups that the user is a member of.

Member

If enabled, the user is registered as a member of the specific group.

Default

If enabled, this group is set as default group for the user. By default, this group will have read, write and execute permissions for new configurations created by the user.


For details of how to change your password see The File Menu in 1.3 Desktop User Interface.

Access Groups Tab

Administrator is a predefined access group. By default, this group has full access to all the activities and functions in the system and it cannot be deleted. You can only change the Access Controller permissions for the Administrator group.

To add a new group to the system, select the Access Groups tab and then select Add from the File menu or from the toolbar.

 

Access Controller - Access Groups tab

SettingDescription

Name

Enter the name of the group. Valid characters are: A-Z, a-z, 0-9, '-' and '_'

Description

Descriptive information about the group.

Allow Access Through SCIM

Allows the group to be accessed using SCIM. 

Note!

Available only when you have SCIM as part of the license.

Application

This column is a list of the all applications in the system.

Execute

Check to enable the members of the access group to start an instance of the relevant application. Clear to prohibit the access group members from using it.

Write

Check to enable the members of the access group to edit and save a configuration within the relevant application. Clear to prohibit the user from doing so.

Note!

The main Desktop menu is divided into Configuration, Inspection, and Tools. Configuration enables you to create configurations. Inspection enables you to view data that is produced by workflows. Tools enables you to view data that is generated by the system. When you define an Access Group in the Access Controller, you can only check Write for Inspection- and Tools applications, so that users are able to manipulate data that is either generated by a workflow, or by the system. Configuration Write access is set per configuration from the Set Permissions view. For further information see Properties in 6.2 Configuration Browser.

Application Category

A drop down menu that allows the user to filter on application type. Options are All, Configuration, Inspection, Tools, or Web interface.

Select All

Enables Write (if applicable) and Execute for all permissions in the chosen category.

Deselect All

Disables Write and Execute for all permissions in the chosen category.

For information about how to modify configuration permissions, see 6.2 Configuration Browser.
 

Advanced Tab 

You use the Advanced tab to specify the number of consecutive erroneous login attempts permitted by a user, enable logging in the System Log when a user fails to login to , and configure user authentication by selecting the relevant authentication method.

Access Controller - Advanced tab

Number of Consecutive Erroneous Login Attempts

In order to configure the maximum number consecutive failed login attempts, open the Advanced tab, and set a value in Number Of Consecutive Erroneous Login Attempts. The default is 3. 
When the maximum number of failed login attempts is reached, the user must restart the Desktop. If enhanced user security is enabled, the user account is also locked. For more information, see the section below, Enhanced User Security.

Enable Logging for User Login

In order to configure the system to log failed attempts in the System Log, open the Advanced tab, and select the check box Enable Logging For User Login. Successful logins and locked accounts are always logged regardless of this setting.

Reauthenticate Users after Inactivity

In order to configure the system to reauthenticate users after a period of inactivity  in the Desktop or mzsh shell (interactive mode), open the Advanced tab,  and select the check box Reauthenticate Users After Inactivity. Then  set the maximum inactive time in Time of Inactivity Before Reauthentication (Minutes).

In the Desktop, the duration of time that the user does not perform any actions is counted as inactive time, regardless of ongoing processes. 
However, users are not logged out due to inactivity, but must authenticate again in order to continue the session.

In the mzsh shell, the duration of time that the user does not press any key is counted as inactive time, provided that there is no ongoing command execution. Users are logged out as a result of inactivity and are prompted to enter the password again.

Enhanced User Security

The security user control can be enhanced by changing the Platform property mz.security.user.control.enabled in the platform.conf. By default this property is set to false. If set to true a number of rules regarding the passwords apply as soon as the platform is restarted.

Note!

When you are using LDAP authentication, the information in this section is only applicable for the user mzadmin.

Enhanced User Security Password Rules

If enhanced user security is enabled, the default password rules are:

The password must:

  • Be at least eight characters long

  • Include at least one special character and one that is either a number or capital letter

The password must not:

  • Contain more than two identical characters in an uninterrupted sequence. Such as "aaa".  

    Note!

    Repetitive characters that are not consecutively sequenced are still valid. Such as "adadad".

  • Include the username.

  • Be in alphabetical sequence, such as Abcd.
  • Be in numerical sequence, such as 1234.
  • Be in any US keyboard pattern, such as Qwerty.
  • Contain any whitespace.
  • Be identical to any of the recent twelve (minimum) passwords used for the user ID

The default maximum password age is 30 days for administrators, i e users that are members of the Administrator group, and 90 days for other users.

You can modify the password rules with the following Platform properties:

Note!

All properties listed below is only applicable when the value of mz.security.user.control.enabled is set to true.


PropertyDescription
mz.security.max.password.age.enabled

Default value: false

Enables or disables the password expiration check.  This property is only applicable when mz.security.user.control.enabled is also set to true.

If both properties above are set to true, user is required to change password every N days set in mz.security.max.password.age.admin and mz.security.max.password.age.user.

mz.security.max.password.age.admin

Default value: 30

This property specifies the maximum password age for administrator users in days.

Please refer mz.security.max.password.age.enabled column.

mz.security.max.password.age.user

Default value: 90

This property specifies the maximum password age for users in days.

Please refer mz.security.max.password.age.enabled column.

mz.security.max.password.history

Default value: 12

This property specifies how many passwords back that are required to be unique before reusing an old password.

mz.security.user.control.enabled

Default value: false

This property enables or disables enhanced user security. If set to true, a number of rules regarding the passwords apply as soon as the platform is restarted. For information about enhanced user security, see   6.1 Access Controller in the Desktop User's Guide.

Note!

At installation this property will be set to the same value as the installation property install.security.

mz.security.user.control.password.length.count

Default value: 8

This property specifies the minimum total number of characters in a password.

Note!

This is only applicable when the value of mz.security.user.control.enabled is true.

mz.security.user.control.password.numcaps.count

Default value: 1

The minimum number of upper case characters  or number of numerical characters, in a password.

mz.security.user.control.password.numcaps.message

Default value: The password needs at least one capital letter or a number in it.

The message to be displayed for the user when they have not met the condition for the minimum number of upper case or numerical characters in the password.

mz.security.user.control.password.numcaps.pattern

Default value: [A-Z0-9]

The pattern of the permitted values in regular expression. The password will be matched to the pattern to determine if the condition is met.

mz.security.user.control.password.length.count

Default value: 8

The minimum total number of characters in a password.

mz.security.user.control.password.length.message

Default value: The password needs to be at least 8 characters.

The message to be displayed for the user when they have not met the condition for the minimum length of the password.

mz.security.user.control.password.lowercase.count

Default value: ""

The minimum total number of lowercase characters in a password.
mz.security.user.control.password.uppercase.count

Default value: ""

The minimum total number of uppercase characters in a password.

mz.security.user.control.password.number.count

Default value: ""

The minimum total number of numeric characters in a password.

mz.security.user.control.password.special.count

Default value: 1

The minimum number of special characters, in a password.

mz.security.user.control.password.special.message

Default value: The password needs to contain at least 1 special character(s).

The message to be displayed for the user when they have not met the condition for the minimum number of special characters in the password.

mz.security.user.control.password.special.pattern

Default value: [\\W_]

The pattern of the permitted values in regular expression. The password will be matched to the pattern to determine if the condition is met.

mz.security.user.control.password.repetition.message

Default value: The password contains too many consecutive identical characters.

The message to be displayed for the user when they have not met the condition for the password having the least amount of multiple repeated characters in a sequence.

mz.security.user.control.password.username.message

Default value: The username may not be a part of the password.

The message to be displayed for the user when they have the username contained withing the password.

mz.security.user.control.password.history.message

Default value: The password may not be a recently used password.

The message to be displayed for the user when they are reusing a password that they have used before.

mz.security.user.control.password.extra.count

Default value: ""

The minimum number of characters for the extra user policy.

mz.security.user.control.password.extra.message

Default value: ""

The message to be displayed for the user when they did not meet the requirements of the extra user policy.

mz.security.user.control.password.extra.pattern

Default value: ""

The pattern of the permitted values. The password will be matched to the pattern to determine if the condition is met.

mz.security.user.control.password.extra.type

Default value: ""

The type that determines what the extra pattern will be. The value of this property can be set to regexp or none. Setting it to regexp ensures that the pattern has to conform to regular expressions.


Note!

The user account will be locked after a configurable number of failed login attempts. If this happens, the password settings for the user account must be updated in the Users tab, unless automatic unlocking is selected. For more information about how to update password settings for a user account and how to configure automatic unlocking, see the section above, Users Tab, and the section below, Enhanced User Security Configuration.

Enhanced User Security Configuration

 The settings that are described in this section are available when enhanced user security is enabled.

Access Controller - Advanced tab

SettingDescription

Enable Automatic Unlocking Of Users

Select this check box to automatically unlock accounts that have been disabled due failed login attempts. Accounts that have been manually disabled from the Users tab are not affected by this setting.

Time Before Automatic Unlocking (Minutes)

Enter the time that should pass before a locked account is automatically unlocked by the system. The minimum value is 1 minute.

LDAP Authentication

User authentication is by default performed in . As an alternative, you can connect to an external LDAP directory for delegated authentication. This facilitates automation of administrative tasks such as creation of users and assigning access groups.

If the external authentication server returns an error or cannot be accessed, will perform the authentication internally as a fallback method.

 The Authentication Methods drop-down list is only available if LDAP Authentication is installed.

Note!

Configuration performed from the Users Tab has no impact on external authentication servers. 

LDAP Authentication Preparations

This section does not apply if authentication is to be performed by .

NOTE: For Active directory specific settings check Active Directory Important Information

Directory Structure

The LDAP directory that is used for authentication must conform to the following requirements:

  1. The cn attribute of group entries must match an access group defined .
     

    Note!

    performs case sensitive comparisons of the cn attributes and access groups. 

  2.  For each user in a group entry, the memberUid attribute must be set.
  3.  All group entries must belong to the object class posixGroup.
  4.  All user entries must belong to the objectclass posixAccount. 

  5. The username must be unique. It cannot duplicate a username that already exists.

Note!

If a user requires administration rights, they must be added to the Administrator access group, which is a default access group in , and you must create a group named Administrator in the LDAP directory.

Secure Access 

The following steps are required before configuration of authentication with LDAPS or LDAP over TLS:

  1.  Obtain the server certificate for the authentication server from your LDAP administrator.
     
  2.  Start a command shell and copy the server certificate to the platform host.
     
  3.  If using JRE on a platform side, change the directory to $JAVA_HOME/lib/security on the platform host. Otherwise, change the path to $JAVA_HOME/jre/lib/security. 
     
  4.  Install the server certificate using the Java keytool command:

    keytool -import -file <certificate> -keystore cacerts 

Active Directory Important Information

Directory Structure

The LDAP directory that is used for authentication must conform to the following requirements:

  1. All user entries must belong to the objectclass user .

  2. User's groups have to be provided via memberOf attribute.

  3. User's login has to be provided via samaccountname attribute.

  4. The username must be unique. It cannot duplicate a username that already exists.

Note!

If a user requires administration rights, they must be added to the Administrator access group, which is a default access group and you must create a group named Administrator in the LDAP directory.

LDAP Configuration

Access Controller - Advanced tab with LDAP Authentication


SettingDescription
Authentication Methods

The Authentication Methods setting is only available if LDAP Authentication is installed.

Select the authentication method to be used. The following settings are available:

  • Default
  • LDAP

The default setting authentication performed by .

The selected authentication method becomes effective when the configuration is saved.

Note!

Authentication for the user mzadmin is always performed by regardless of the selected authentication method. 

URL

Enter the URL for the external authentication server. The default ports, 389 for LDAP and 686 for LDAPS, are used unless other ports are specified in the URL.

When using LDAP, you may connect via LDAPS by entering ldaps:// in the URL.

Example of LDAP URL

ldap://ldap.example.com:389

Example of LDAPS URL

ldaps://ldap.example.com:636

Test Connection

Click this button to test the connection to the authentication server. LDAP attributes and other settings than the URL are not used when testing the connection.

User Base DN

Enter the LDAP attributes for user lookups in the external authentication server. The substring %s in this value will be replaced with the username entered at login to produce an identifier that is passed to the LDAP server.

Example of User Base DN

uid=%s,ou=users,dc=digitalroute,dc=com

Group Base DN

Enter the LDAP attributes for group lookups in the external authentication server.

Example of Group Base DN

ou=groups,dc=digitalroute,dc=com

The name of the groups must be identical to the names configured in Access Groups.

TLS

Select this check box to enable Transport Layer Security.

Note!

The following must be considered when using TLS:

  • LDAPS and TLS is not a valid combination.

  • The URL must contain a fully qualified DNS name or the authentication will fail.

  • The default LDAP port, 389, should be used.

AD NamingSelect this check box if you want to use Active directory specific naming.
Enable

Select this check box if you want to enable group search bind credentials. You must also populate the Bind DN and Password fields. If you want to run an anonymous lookup, leave this check box empty.

Bind DN

If you want to use a specific Bind DN to search for the group, enter the Bind DN.

Password

If you want to use a specific Bind DN to search for the group, enter the password for the Bind DN.

Configuration using Cross-domain Identity Management (SCIM)

It is possible to use SCIM via the REST HTTP interface to POST, GET, DELETE, PUT and PATCH user and group configurations. This section will cover the schemas used to create, update and remove users and groups, as well as the limitations when using SCIM for .

For more information regarding the specifications for SCIM, please see RFC:  https://tools.ietf.org/html/rfc7643 

For information regarding the API endpoints, please see RFC: https://tools.ietf.org/html/rfc7644#section-3.2

Note!

When importing the user configurations or when upgrading, the users will be disabled after the import operation or the upgrade. In order to enable the users, you can use PATCH or PUT, a user with attribute active : true. You can also enable the user by ticking the checkbox for the users you want to enable from the User tab in Access Controller on the desktop.

When creating a new user from SCIM, the user will be enabled by default.

These are the limitations for using SCIM instead of the desktop.

  • A user can only be created once using the HTTP method POST
  • The password attribute is not mandatory when you create a user with POST , however the user will not be able to login without a password.
  • All user details can be modified except the username.
  • The users assigned group can only be updated using the HTTP method PUT
  • When using PUT to assign a user's group, no default group will be selected.
  • You can only POST an access group with same name one time, the group name can not be changed.
  • It is not possible to set or change the applications connected to the access group using the HTTP methods available via SCIM, this is only possible using the desktop.

Custom Schema

has an additional schema for the "User" resource. The Schema URI for it is:

urn:sap:cloud:scim:schemas:extension:custom:2.0:mzuser


The following attributes are defined:

  • successor: The successor user takes over all configs when the current user is removed.
    • value: The identifier of the successor user.

      Example

      71a36bb7-816f-460d-b580-3bd9352b0953
    • display: A human-readable name, primarily used for display purposes. It is read-only.

  • validityPeriod: The validity period of a user. Format is: yyyy-mm-ddThh:mm:ss
    • from: The "DateTime" the user should be valid from.

      Example

      2021-03-18T23:00:00Z


    • to: The "DateTime" the user should be valid to.

      Example

      2021-03-23T22:59:59Z


      Note

      The to field should always be greater or equal to from field.

User related APIs

This section will cover all the REST HTTP APIs that are used for user related operations.

Retrieving Users

You can use this to retrieve all users:

URL: http://<host>:9000/scim/api/v1/Users
Method: GET
Header: 
Accept: application/scim+json
Content-Type: application/scim+json

You can use this to retrieve a specific user:

URL: http://<host>:9000/scim/api/v1/Users/14c257bd-e486-4ec6-b73e-47bb1e9b491b
Method: GET
Header: 
Accept: application/scim+json
Content-Type: application/scim+json

Creating Users

You can use this to create a user:

Info!

The schemas and userName fields as shown below are mandatory. They must be filled in. The rest of the fields are optional

URL: http://<host>:9000/scim/api/v1/Users
Method: POST
Header: 
Accept: application/scim+json
Content-Type: application/scim+json
Request Body: 
{
	"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
	"userName":"bjensen",
	"displayName": "mz80u3",
	"password": "mz80u3",
	"active": "true",
	"emails": [
	{ 
		"value": "b@b.com",
		"display": "bbb",
		"primary": true
	}

	],
	"externalId":"bjensen",
	"name":
	{
		"formatted":"Ms. Barbara J Jensen III",
		"familyName":"Jensen",
		"givenName":"Barbara"
	},
	"groups": [
	{
		"value": "ed309a27-3f34-45d3-ade5-b2f8f798deb5"
	},
	{
		"value": "86138dad-9742-44a2-a9cb-70347fb884a8"
	}
	],
	"urn:sap:cloud:scim:schemas:extension:custom:2.0:mzuser": {
        "successor": {
            "value": "71a36bb7-816f-460d-b580-3bd9352b0953"
        },
        "validityPeriod": {
                    "from": "2021-03-19T23:00:00Z",
                    "to": "2021-03-23T22:59:59Z"
                }
    }
}

Updating Users

You can use this to update all the values for a user:

Info!

The schemas and userName fields as shown below are mandatory. They must be filled in. The rest of the fields are optional

URL: http://<host>:9000/scim/api/v1/Users/c9706a50-6fd3-44cf-8f8d-7ea00fb05f1c
Method: PUT
Header: 
Accept: application/scim+json
Content-Type: application/scim+json
Request Body: 
{
	"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
	"userName": "bjensen",
	"displayName": "mz80u3",
	"emails": [
	{ 
		"value": "b@b.com",
		"display": "mz80u3",
		"primary": true
	}
	],
	"groups": [
	{
		"value": "119fe1b7-4b8b-4970-8ea6-b62bdaa11f05"
	},
	{
		"value": "53aabe0b-715d-4d96-a220-56c6efc11ae9"
	}
	],
	"urn:sap:cloud:scim:schemas:extension:custom:2.0:mzuser": {
        "successor": {
            "value": "71a36bb7-816f-460d-b580-3bd9352b0953"
        },
        "validityPeriod": {
                    "from": "2021-03-20T23:00:00Z",
                    "to": "2021-03-25T22:59:59Z"
                }
    }
}


You can use this to update specific values for a user:

Info!

The schemas, Operations, op and value fields as shown below are mandatory. They must be filled in. The rest of the fields are optional

URL: http://<host>:9000/scim/api/v1/Users/c9706a50-6fd3-44cf-8f8d-7ea00fb05f1c
Method: PATCH
Header: 
Accept: application/scim+json
Content-Type: application/scim+json
Request Body: 
{
		"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
		"Operations":[
		{
			"op":"add",
			"value":
			{
				"emails":[
				{ 
					"value":"babs@jensen.org",
					"type":"home"
				}
				]
			}
		},
		{
            "op": "add",
            "path": "urn:sap:cloud:scim:schemas:extension:custom:2.0:mzuser:validityPeriod",
            "value": {
                "from": "2021-03-19T23:00:00Z",
                "to": "2021-03-23T22:59:59Z"
            }
        }
		
		]
}

Removing Users

You can use this to remove a user:

URL: http://<host>:9000/scim/api/v1/Users/c9706a50-6fd3-44cf-8f8d-7ea00fb05f1c
Method: DELETE
Header: 
Accept: application/scim+json
Content-Type: application/scim+json

Group related APIs

This section will cover all the REST HTTP APIs that are used for group related operations.

Retrieving Groups

You can use this to retrieve all groups:

URL: http://<host>:9000/scim/api/v1/Groups
Method: GET
Accept: */*
Content-Type: */* 

You can use this to retrieve a specific group:

URL: http://<host>:9000/scim/api/v1/Groups/119fe1b7-4b8b-4970-8ea6-b62bdaa11f05
Method: GET
Accept: */*
Content-Type: */*

Creating groups

You can use this to create a group:

Info!

The schemas and userName fields as shown below are mandatory. They must be filled in. The rest of the fields are optional

URL: http://<host>:9000/scim/api/v1/Groups
Method: POST
Accept: */*
Content-Type: */*
Request body:
{
	"schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],
	"displayName":"group2",
	"members":[
	{
		"value":"a12822ad-a5c0-4f83-9a4e-96733a0d2e1b"
	},
	{
		"value":"8792b456-860a-499d-aa38-5caf4fe487c3"
	}
	]
}

Updating Groups

You can use this to update a group:

Info!

The schemas and userName fields as shown below are mandatory. They must be filled in. The rest of the fields are optional

URL: http://<host>:9000/scim/api/v1/Groups/a85d8e8c-0b6d-4653-b7c6-33c1fd6c1921
Method: PUT
Accept: */*
Content-Type: */*
Request body:
{
	"schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],
	"displayName":"group2",
	"members":[
	{
		"value":"a12822ad-a5c0-4f83-9a4e-96733a0d2e1b"
	},
	{
		"value":"8792b456-860a-499d-aa38-5caf4fe487c3"
	}
	]
}

Deleting Groups

You can use this to delete a group:

URL: http://<host>:9000/scim/api/v1/Groups/a85d8e8c-0b6d-4653-b7c6-33c1fd6c1921
Method: DELETE
Accept: */*
Content-Type: */*