provides different Tools to view logs, statistics, and Pico instance information, and to import and export configurations.

To be able to operate the system, 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 to. Execute permissions to prescribe how members of an access group can use a certain application. For applications that include configurable parameters, you need to delegate 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 if needed.
When no members belong to the Administrator group, all users with full permissions for the Access Controller 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 are not able to remove or modify the Administrator group or any of its group members.
Only one user can 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.

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

Users Tab

The default user, mzadmin, always has full permissions to all activities.

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

To add a user:

Open the Users tab.
Click New.

Access Controller - Users tab
Fill in the details according to the description below.

Setting	Description
Enable User	When selected, this option enables the user.
Username	Enter the name of the user. Accepted characters are A-Z, a-z, 0-9, '-', and '_'. Note! The entered usernames must be uniquely named. This also applies if you use an external authentication method, e.g. LDAP.
Full Name	Enter the full name of the user.
Email	Enter the user's associated e-mail address. This address is automatically applied to applications from which e-mails are sent.
Password	Enter the associated password for the given user account.
Verify Password	Re-enter the password to confirm it.
Successor	A successor must be defined in case you want to remove a user that has ownership of configuration objects.
Validity Period	A defined period of time to which a particular user has access rights to the system. When the validity period expires, the user will be unable to log in or access 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 are not able to choose dates that are earlier than the current date. This applies to editing existing users and creating new users.
Allow Access Through SCIM	Allows the group to be accessed using SCIM. Note! Available only when you have SCIM as part of the license.
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 the default group for the user. By default, this group has read, write, and execute permissions for new configurations created by the user.

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

Access Groups Tab

The 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 click New.

Access Controller - Access Groups tab

Setting	Description
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 all applications in the system.
Execute	Select 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	Select 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 the Configuration, Inspection, and Tools sections. The Configuration section enables you to create configurations. The Inspection section enables you to view data that is produced by workflows. The Tools section enables you to view data that is generated by the system. When you define an Access Group in the Access Controller, you can only select 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 Configuration Browser.
Application Category	A drop-down menu that allows the user to filter on application type. Options are All, Configuration, Inspection, Tools, or the 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 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 log in, 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 of consecutive failed login attempts, open the Advanced tab, and set a value in Number Of Consecutive Erroneous Login Attempts. The default is 3.

This feature is only enabled when Enhanced User Security is activated. When the maximum number of failed login attempts is reached, the user account is 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 checkbox Enable Logging For User Login. Successful logins and locked accounts are always logged regardless of this setting.

Reauthenticate Users after Inactivity

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 checkbox Reauthenticate Users After Inactivity. Then set the maximum inactive time in Time of Inactivity Before Reauthentication (Minutes).

On 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 to 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 a capital letter

The password cannot:

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 sequences, such as Abcd.
Be in numerical sequences, 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 administrator group users, and 90 days for all other users.

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

Note!

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

Property	Description
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, the user is required to change the 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 passwords apply as soon as the platform is restarted. For information about enhanced user security, see Access Controller in the Desktop User's Guide. Note! At installation, this property is 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 a 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 is 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 the regular expression. The password is 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 is displayed to 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 is 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 the regular expression. The password is 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 is 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 is displayed to the user when they have the username contained within the password.
mz.security.user.control.password.history.message	Default value: `The password may not be a recently used password.` The message is displayed to the user when they reuse a password that they have used before.
mz.security.user.control.password.extra.count	Default value: `""` The minimum number of characters of the extra user policy.
mz.security.user.control.password.extra.message	Default value: `""` The message is displayed to the user when they do 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 is matched to the pattern to determine if the condition is met.
mz.security.user.control.password.extra.type	Default value: `""` The type determines what the extra pattern is. 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 is 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

Setting	Description
Enable Automatic Unlocking Of Users	Select this checkbox to automatically unlock accounts that have been disabled due to 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 the system. As an alternative, you can connect to an external LDAP directory for delegated authentication. This facilitates the automation of administrative tasks such as the creation of users and assigning access groups.

If the external authentication server returns an error or cannot be accessed, the authentication is performed 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:

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

Note!

The system performs case-sensitive comparisons of the cn attributes and access groups.
For each user in a group entry, the memberUid the attribute must be set.
All group entries must belong to the object class posixGroup.
All user entries must belong to the object class posixAccount.
The username must be unique. It cannot duplicate a username that already exists in the system.

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.

Secure Access

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

Obtain the server certificate for the authentication server from your LDAP administrator.
Start a command shell and copy the server certificate to the platform host.
Change the directory to $JAVA_HOME/jre/lib/security where $JAVA_HOME points to your JDK directory.
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:

All user entries must belong to the objectclass user.
User groups have to be provided via memberOf attribute.
The user's login has to be provided via samaccountname attribute.
The username must be unique. It cannot duplicate a username that already exists in the system.

Note!

LDAP Configuration

Access Controller - Advanced tab with LDAP Authentication

Setting	Description
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 is 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 checkbox 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 Naming	Select this checkbox to use Active directory specific naming.
Enable	Select this checkbox 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 checkbox 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 covers 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 into the system or when upgrading, the users are disabled after the import operation or the upgrade. To enable the users, you can use PATCH or PUT, a user with attribute active : true. You can also enable the user by selecting 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 is 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 to 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 the 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

There is 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 configurations 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: 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 must always be greater or equal to from field.

User related APIs

This section covers 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: */*

Browser not supported