# Management of Permissions > Symcon documentation · English · generated on 2026-11-09 > Index: https://www.symcon.de/en/llms.txt ## Contents Pages in this file: - Users - IPS_AddPermissionToUser – adds a permission to a user - IPS_AddRoleToUser – assigns a role to a user - IPS_CreateUser – creates a new user - IPS_DeleteUser – deletes a user - IPS_GetUser – returns information about a user - IPS_GetUserList – returns the names of all users - IPS_RemovePermissionFromUser – removes a permission from a user - IPS_RemoveRoleFromUser – removes a role from a user - IPS_SetUserActive – activates/deactivates a user - IPS_SetUserBindDN – sets the BindDN of an LDAP user - IPS_SetUserEMail – sets the e-mail address of a user - IPS_SetUserFirstName – sets the first name of a user - IPS_SetUserLastName – sets the last name of a user - IPS_SetUserPassword – sets the password of a user - IPS_UserExists – checks whether a specific user exists - IPS_UserHasPermission – checks whether a user may perform an operation on an object - IPS_UserHasRole – checks whether a specific role is assigned to a user - IPS_UserIsAdministrator – checks whether a user is an administrator - IPS_GetLoggedInUser – returns the name of the user in whose context the current execution runs - IPS_HasPermission – checks whether the currently logged in user may perform an operation on an object - IPS_IsAdministrator – checks whether the currently logged in user is an administrator - IPS_IsUnknown – checks whether the current execution runs without a logged in user - Roles - IPS_AddPermissionToRole – adds a permission to a role - IPS_CreateRole – creates a new role - IPS_DeleteRole – deletes a role - IPS_GetRole – returns information about a role - IPS_GetRoleList – returns the names of all roles - IPS_RemovePermissionFromRole – removes a permission from a role - IPS_RoleExists – checks whether a role exists - IPS_RoleHasPermission – checks whether a role has a permission for an object Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/ ## Users Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ ## IPS_AddPermissionToUser Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-addpermissiontouser/ `bool IPS_AddPermissionToUser(string $User, int $ObjectID, string $Operation, bool $Recursive)` adds a permission to a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$ObjectID` (int): ID of the object the permission applies to - `$Operation` (string): Name of the registered operation, e.g. VISUALIZATION - `$Recursive` (bool): __TRUE__ if the permission also applies to all objects below __ObjectID__, otherwise __FALSE__ **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function grants the user __User__ the permission to perform the __Operation__ on the object __ObjectID__. Alternatively, permissions can be granted via roles (see [IPS_AddPermissionToRole](management-permissions.md)). Access to a visualization can also be configured directly in its instance configuration under [Security](../components/tile-visualization.md). A recursive permission applies to the object itself and to all objects below it in the object tree (children, grandchildren, etc.). A recursive permission on the root object (ID 0) therefore applies to all objects. A non-recursive permission applies to exactly this object only. Links are not followed; only the position of the checked object in the object tree matters. Operations are registered by modules. Currently the visualization registers the operation __VISUALIZATION__ (access to a visualization with all its objects) as soon as a visualization instance (e.g. [Tile Visualization](../modules/tile-visualization.md) or [WebFront Visualization](../modules/webfront-visualization.md)) exists. It is checked against the ID of the visualization instance. The operation name is case-sensitive. If the operation is not registered, the function fails with "Cannot verify unsupported operation". > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". Further checks in this order: If the operation is not registered, the function fails with "Cannot verify unsupported operation". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". If the object does not exist, it fails with "Object #… does not exist". If the user already has a permission with identical __ObjectID__, __Operation__ and __Recursive__, it fails with "User already has this permission". A permission that only differs in __Recursive__ counts as a separate entry. See also: [IPS_RemovePermissionFromUser](management-permissions.md), [IPS_UserHasPermission](management-permissions.md) **Example** ```php $VisuID = 12345; // ID of a tile visualization IPS_AddPermissionToUser('anna', $VisuID, 'VISUALIZATION', false); ``` ## IPS_AddRoleToUser Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-addroletouser/ `bool IPS_AddRoleToUser(string $User, string $Role)` assigns a role to a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$Role` (string): Name of the role to be assigned (case-sensitive) **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function assigns the role __Role__ to the user __User__. The user thereby receives all permissions of the role. If the @admin role is assigned, the user becomes an administrator. Roles are created with [IPS_CreateRole](management-permissions.md). > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the role does not exist, the function fails with "Role with name '…' does not exist"; if the user does not exist, with "User with name '…' does not exist". If the role is already assigned, it fails with "User with name '…' already has Role '…' attached". As the @admin user implicitly has all roles, the function also fails with this message for it. See also: [IPS_RemoveRoleFromUser](management-permissions.md), [IPS_UserHasRole](management-permissions.md) **Example** ```php IPS_CreateRole('visu'); IPS_AddRoleToUser('anna', 'visu'); ``` ## IPS_CreateUser Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-createuser/ `bool IPS_CreateUser(string $User, int $UserType)` creates a new user **Parameters** - `$User` (string): Name of the new user (case-sensitive) - `$UserType` (int): Type of the user, see the table in the description
0 `USER_TYPE_LOCAL`: local account
1 `USER_TYPE_LDAP`: LDAP **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function creates a new user with the name __User__ and the type __UserType__. | User type | Constant | Description | | --------- | ----------------- | --------------------------------------------------------------------------------------------------------------- | | 0 | `USER_TYPE_LOCAL` | Local account, login with the password set via [IPS_SetUserPassword](management-permissions.md) | | 1 | `USER_TYPE_LDAP` | LDAP, login via the LDAP server with the BindDN set via [IPS_SetUserBindDN](management-permissions.md) | Users are usually managed in the [Permission Control](../modules/permission-control.md). A new user is __inactive__ and has no password, no first and last name, no roles and no permissions. For the user to be able to log in, the user must be activated with [IPS_SetUserActive](management-permissions.md) and, for a local account, get a password with [IPS_SetUserPassword](management-permissions.md) or, for an LDAP account, a BindDN with [IPS_SetUserBindDN](management-permissions.md). > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". The new user counts against the user limit of the license (10 users by default, the @admin user is not counted). If the limit would be exceeded, the function fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". Further errors: * An empty name fails with "User cannot be empty". * The name "token" is reserved for logging in with temporary tokens and fails with "User 'token' is reserved and cannot be used". * A name that equals the licensee (e-mail address of the license) fails with "User cannot be equivalent to the licensee". * A user type other than 0 or 1 fails with "Unsupported User Type!". * If a user with this name already exists, the function fails with "User with name '…' already exists". See also: [IPS_DeleteUser](management-permissions.md), [IPS_GetUser](management-permissions.md), [IPS_AddRoleToUser](management-permissions.md) **Example** ```php IPS_CreateUser('anna', USER_TYPE_LOCAL); IPS_SetUserPassword('anna', 'secret'); IPS_SetUserFirstName('anna', 'Anna'); IPS_SetUserLastName('anna', 'Muster'); IPS_SetUserActive('anna', true); ``` ## IPS_DeleteUser Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-deleteuser/ `bool IPS_DeleteUser(string $User)` deletes a user **Parameters** - `$User` (string): Name of the user (case-sensitive) **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function deletes the user __User__ including the user's role assignments and permissions. The roles themselves are kept. > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". The user limit of the license is not checked here, so users can be deleted even if there are more users than the license allows. The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". See also: [IPS_CreateUser](management-permissions.md), [IPS_UserExists](management-permissions.md) **Example** ```php if (IPS_UserExists('anna')) { IPS_DeleteUser('anna'); } ``` ## IPS_GetUser Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-getuser/ `array IPS_GetUser(string $User)` returns information about a user **Parameters** - `$User` (string): Name of the user (case-sensitive) **Returns** (array) The following information is available as __key => value__ pairs: | Index | Type | Description | | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | __UserName__ | string | Name of the user | | __UserType__ | integer | Type of the user
0 `USER_TYPE_LOCAL`: Local account
1 `USER_TYPE_LDAP`: LDAP | | __FirstName__ | string | First name | | __LastName__ | string | Last name | | __EMail__ | string | E-mail address | | __BindDN__ | string | BindDN for logging in at the LDAP server (only relevant for LDAP users) | | __IsActive__ | boolean | __TRUE__ if the user is active and can log in | | __Roles__ | array | Names of the directly assigned roles | | __Permissions__ | array | Directly assigned permissions, see Permissions | ### Permissions | Index | Type | Description | | ------------- | ------- | ----------------------------------------------------------------------- | | __ObjectID__ | integer | ID of the object the permission applies to | | __Operation__ | string | Name of the operation, e.g. VISUALIZATION | | __Recursive__ | boolean | __TRUE__ if the permission also applies to all objects below the object | The function returns an array with information about the user __User__. The password is not returned; it is only stored as a hash. __Roles__ and __Permissions__ only contain the entries assigned directly to the user; permissions resulting from roles can be read with [IPS_GetRole](management-permissions.md) or checked with [IPS_UserHasPermission](management-permissions.md). For the @admin user the function returns the first name "Default" and the last name "Administrator" without roles and permissions, as this user has all permissions anyway. If the user does not exist, the function fails with "User with name '…' does not exist". The function requires neither the RBAC feature in the license nor administrator permissions. See also: [IPS_GetUserList](management-permissions.md), [IPS_UserExists](management-permissions.md) **Example** ```php print_r(IPS_GetUser('anna')); /* e.g. returns: Array ( [BindDN] => [EMail] => anna@example.com [FirstName] => Anna [IsActive] => 1 [LastName] => Muster [Permissions] => Array ( [0] => Array ( [ObjectID] => 12345 [Operation] => VISUALIZATION [Recursive] => ) ) [Roles] => Array ( [0] => visu ) [UserName] => anna [UserType] => 0 ) */ ``` ## IPS_GetUserList Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-getuserlist/ `array IPS_GetUserList()` returns the names of all users **Returns** (array): An array with the names of all users, including the @admin user The function returns the names of all existing users. The @admin user is always included. The order of the entries is not guaranteed. The function requires neither the RBAC feature in the license nor administrator permissions. Detailed information about a user is returned by [IPS_GetUser](management-permissions.md). **Example** ```php print_r(IPS_GetUserList()); /* e.g. returns: Array ( [0] => @admin [1] => anna ) */ ``` ## IPS_RemovePermissionFromUser Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-removepermissionfromuser/ `bool IPS_RemovePermissionFromUser(string $User, int $ObjectID, string $Operation, bool $Recursive)` removes a permission from a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$ObjectID` (int): ID of the object the permission applies to - `$Operation` (string): Name of the registered operation, e.g. VISUALIZATION - `$Recursive` (bool): Must match the value the permission was added with **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function removes the permission for the __Operation__ on the object __ObjectID__ from the user __User__. The combination of __ObjectID__, __Operation__ and __Recursive__ must exactly match a permission assigned directly to the user (see __Permissions__ in [IPS_GetUser](management-permissions.md)). Permissions the user receives via roles are not affected. > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". Further checks in this order: If the operation is not registered, the function fails with "Cannot verify unsupported operation". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". If the object does not exist, it fails with "Object #… does not exist". If the user does not have the permission, it fails with "User does not have this permission". See also: [IPS_AddPermissionToUser](management-permissions.md), [IPS_RemovePermissionFromRole](management-permissions.md) **Example** ```php $VisuID = 12345; // ID of a tile visualization IPS_RemovePermissionFromUser('anna', $VisuID, 'VISUALIZATION', false); ``` ## IPS_RemoveRoleFromUser Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-removerolefromuser/ `bool IPS_RemoveRoleFromUser(string $User, string $Role)` removes a role from a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$Role` (string): Name of the role to be removed (case-sensitive) **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function removes the role __Role__ from the user __User__. The permissions of the role no longer apply to the user afterwards; the role itself is kept. > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the user does not exist, the function fails with "User with name '…' does not exist". If the role is not assigned to the user, it fails with "User with name '…' does not have Role '…' attached". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". See also: [IPS_AddRoleToUser](management-permissions.md), [IPS_DeleteRole](management-permissions.md) **Example** ```php if (IPS_UserHasRole('anna', 'visu')) { IPS_RemoveRoleFromUser('anna', 'visu'); } ``` ## IPS_SetUserActive Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-setuseractive/ `bool IPS_SetUserActive(string $User, bool $Active)` activates/deactivates a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$Active` (bool): Specifies whether the user is to be activated (__TRUE__) / deactivated (__FALSE__) **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function activates or deactivates the user __User__. Only active users can log in. This way a user can be blocked temporarily without deleting the user. Newly created users are initially inactive (see [IPS_CreateUser](management-permissions.md)). Roles and permissions of the user are kept when deactivating. > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". **Example** ```php IPS_SetUserActive('anna', true); // Activates the user ``` ## IPS_SetUserBindDN Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-setuserbinddn/ `bool IPS_SetUserBindDN(string $User, string $BindDN)` sets the BindDN of an LDAP user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$BindDN` (string): Distinguished name the user logs in with at the LDAP server **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function sets the BindDN (distinguished name) of the user __User__. When an LDAP user (user type 1, `USER_TYPE_LDAP`) logs in, a bind with this BindDN and the entered password is performed against the LDAP server configured in the [Permission Control](../modules/permission-control.md). The LDAP synchronization of the [Permission Control](../modules/permission-control.md) sets the BindDN automatically. The value can be set for every user type, but it is only evaluated for LDAP users. > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". **Example** ```php IPS_CreateUser('max', USER_TYPE_LDAP); IPS_SetUserBindDN('max', 'uid=max,cn=users,dc=symcon'); IPS_SetUserActive('max', true); ``` ## IPS_SetUserEMail Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-setuseremail/ `bool IPS_SetUserEMail(string $User, string $EMail)` sets the e-mail address of a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$EMail` (string): New e-mail address of the user **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function sets the e-mail address of the user __User__. The value is not validated. The current value can be read with [IPS_GetUser](management-permissions.md). > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". **Example** ```php IPS_SetUserEMail('anna', 'anna@example.com'); ``` ## IPS_SetUserFirstName Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-setuserfirstname/ `bool IPS_SetUserFirstName(string $User, string $FirstName)` sets the first name of a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$FirstName` (string): New first name of the user **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function sets the first name of the user __User__. First and last name are displayed e.g. in the visualization. The current value can be read with [IPS_GetUser](management-permissions.md). > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". **Example** ```php IPS_SetUserFirstName('anna', 'Anna'); ``` ## IPS_SetUserLastName Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-setuserlastname/ `bool IPS_SetUserLastName(string $User, string $LastName)` sets the last name of a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$LastName` (string): New last name of the user **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function sets the last name of the user __User__. First and last name are displayed e.g. in the visualization. The current value can be read with [IPS_GetUser](management-permissions.md). > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". **Example** ```php IPS_SetUserLastName('anna', 'Muster'); ``` ## IPS_SetUserPassword Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-setuserpassword/ `bool IPS_SetUserPassword(string $User, string $Password)` sets the password of a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$Password` (string): New password of the user **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function sets the password of the user __User__. The password is not stored in plain text but only as a salted hash (PBKDF2-HMAC-SHA256) and therefore cannot be read back. The password is only used for local accounts (user type 0, `USER_TYPE_LOCAL`). As long as no password has been set for a local account, logging in is not possible. LDAP users (user type 1, `USER_TYPE_LDAP`) log in via the LDAP server with their BindDN instead (see [IPS_SetUserBindDN](management-permissions.md)); the password set here is not evaluated for them. > **Note:** This function is only available for licenses that include the RBAC feature ([Permission Control](../modules/permission-control.md)). Otherwise it fails with "This function is only available for licenses with the RBAC feature enabled!". If there are more users than the license allows (10 users by default, the @admin user is not counted), it fails with "Your license is currently limited to 10 users. Please consider upgrading the license to more users!" (the number is the limit of the license). The currently logged in user (see [IPS_GetLoggedInUser](management-permissions.md)) must be an administrator, i.e. the @admin user or a user with the @admin role. Otherwise the function fails with "Administrator permissions are required for this action!". If the user does not exist, the function fails with "User with name '…' does not exist". The @admin user cannot be modified; trying to do so fails with "User @admin cannot be modified!". **Example** ```php IPS_SetUserPassword('anna', 'secret'); ``` ## IPS_UserExists Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-userexists/ `bool IPS_UserExists(string $User)` checks whether a specific user exists **Parameters** - `$User` (string): Name of the user to be checked (case-sensitive) **Returns** (bool): If the user exists, __TRUE__ is returned, otherwise __FALSE__. The function checks whether a user with the name __User__ exists. The check is case-sensitive. The @admin user always exists, whereas the special user @unknown is not an actual user, so the function returns __FALSE__ for it. The function requires neither the RBAC feature in the license nor administrator permissions. **Example** ```php if (IPS_UserExists('anna')) { echo 'User exists!'; } ``` ## IPS_UserHasPermission Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-userhaspermission/ `bool IPS_UserHasPermission(string $User, int $ObjectID, string $Operation)` checks whether a user may perform an operation on an object **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$ObjectID` (int): ID of the object to be checked - `$Operation` (string): Name of the registered operation, e.g. VISUALIZATION **Returns** (bool): If the user has the permission, __TRUE__ is returned, otherwise __FALSE__. The function checks whether the user __User__ may perform the __Operation__ on the object __ObjectID__. The permissions of the user and the permissions of all the user's roles are taken into account. Whether the user is active does not matter for this check. The check is performed in this order: If the operation is not registered, the function fails with "Cannot verify unsupported operation"; if the object does not exist, with "Object #… does not exist". The @admin user always has all permissions, the @unknown user never has any. For all other users: If the user does not exist, the function fails with "User with name '…' does not exist". If the user has the @admin role, __TRUE__ is returned. Otherwise __TRUE__ is returned if a permission of the user or of one of the user's roles grants the operation on the object. A recursive permission applies to the object itself and to all objects below it in the object tree (children, grandchildren, etc.). A recursive permission on the root object (ID 0) therefore applies to all objects. A non-recursive permission applies to exactly this object only. Links are not followed; only the position of the checked object in the object tree matters. Operations are registered by modules. Currently the visualization registers the operation __VISUALIZATION__ (access to a visualization with all its objects) as soon as a visualization instance (e.g. [Tile Visualization](../modules/tile-visualization.md) or [WebFront Visualization](../modules/webfront-visualization.md)) exists. It is checked against the ID of the visualization instance. The operation name is case-sensitive. If the operation is not registered, the function fails with "Cannot verify unsupported operation". The function requires neither the RBAC feature in the license nor administrator permissions. For the currently logged in user, [IPS_HasPermission](management-permissions.md) can be used. **Example** ```php $VisuID = 12345; // ID of a tile visualization IPS_AddPermissionToUser('anna', 0, 'VISUALIZATION', true); // recursive from the root object var_dump(IPS_UserHasPermission('anna', $VisuID, 'VISUALIZATION')); /* returns: bool(true) */ ``` ## IPS_UserHasRole Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-userhasrole/ `bool IPS_UserHasRole(string $User, string $Role)` checks whether a specific role is assigned to a user **Parameters** - `$User` (string): Name of the user (case-sensitive) - `$Role` (string): Name of the role to be checked (case-sensitive) **Returns** (bool): If the role is assigned to the user, __TRUE__ is returned, otherwise __FALSE__. The function checks whether the role __Role__ is assigned to the user __User__. The role itself does not need to exist. For the @admin user the function returns __TRUE__ for every role, for the special user @unknown always __FALSE__. If the user does not exist, the function fails with "User with name '…' does not exist". The function requires neither the RBAC feature in the license nor administrator permissions. See also: [IPS_AddRoleToUser](management-permissions.md), [IPS_UserIsAdministrator](management-permissions.md) **Example** ```php if (IPS_UserHasRole('anna', 'visu')) { echo 'Anna has the role visu'; } ``` ## IPS_UserIsAdministrator Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/users/ips-userisadministrator/ `bool IPS_UserIsAdministrator(string $User)` checks whether a user is an administrator **Parameters** - `$User` (string): Name of the user (case-sensitive) **Returns** (bool): If the user is an administrator, __TRUE__ is returned, otherwise __FALSE__. The function checks whether the user __User__ is an administrator. Administrators are the @admin user and every user that has been assigned the @admin role (see [IPS_AddRoleToUser](management-permissions.md)). For the special user @unknown the function returns __FALSE__. If the user does not exist, the function fails with "User with name '…' does not exist". The function requires neither the RBAC feature in the license nor administrator permissions. For the currently logged in user, [IPS_IsAdministrator](management-permissions.md) can be used. **Example** ```php var_dump(IPS_UserIsAdministrator('anna')); /* e.g. returns: bool(false) */ ``` ## IPS_GetLoggedInUser Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/ips-getloggedinuser/ `string IPS_GetLoggedInUser()` returns the name of the user in whose context the current execution runs **Returns** (string): Name of the currently logged in user, e.g. "@admin" or "@unknown" The function returns the name of the user in whose context the current execution (e.g. a script) runs. A script inherits the user of the context that started it. If a script is started e.g. by an action in a visualization where a user is logged in, the function returns the name of this user. The following special users exist: | User | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | __@admin__ | Administrator with all permissions. Logging in is done with the license (e-mail address) and the remote access password, e.g. in the console. | | __@unknown__ | No user is logged in. This user has no permissions at all. | The function does not require the RBAC feature in the license. The executing user is also shown in the traces as __ExecutionUser__, see [IPS_GetTraces](../developer/internal-command-reference/helpers.md). See also: [IPS_IsAdministrator](management-permissions.md), [IPS_IsUnknown](management-permissions.md), [IPS_HasPermission](management-permissions.md) **Example** ```php echo IPS_GetLoggedInUser(); /* e.g. returns: @admin */ ``` ## IPS_HasPermission Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/ips-haspermission/ `bool IPS_HasPermission(int $ObjectID, string $Operation)` checks whether the currently logged in user may perform an operation on an object **Parameters** - `$ObjectID` (int): ID of the object to be checked - `$Operation` (string): Name of the registered operation, e.g. VISUALIZATION **Returns** (bool): If the currently logged in user has the permission, __TRUE__ is returned, otherwise __FALSE__. The function checks whether the user in whose context the current execution runs (see [IPS_GetLoggedInUser](management-permissions.md)) may perform the __Operation__ on the object __ObjectID__. The permissions of the user and the permissions of all the user's roles are taken into account. It corresponds to [IPS_UserHasPermission](management-permissions.md) for the current user. The check is performed in this order: If the operation is not registered, the function fails with "Cannot verify unsupported operation"; if the object does not exist, with "Object #… does not exist". The @admin user always has all permissions, the @unknown user never has any. For all other users: If the user does not exist, the function fails with "User with name '…' does not exist". If the user has the @admin role, __TRUE__ is returned. Otherwise __TRUE__ is returned if a permission of the user or of one of the user's roles grants the operation on the object. A recursive permission applies to the object itself and to all objects below it in the object tree (children, grandchildren, etc.). A recursive permission on the root object (ID 0) therefore applies to all objects. A non-recursive permission applies to exactly this object only. Links are not followed; only the position of the checked object in the object tree matters. Operations are registered by modules. Currently the visualization registers the operation __VISUALIZATION__ (access to a visualization with all its objects) as soon as a visualization instance (e.g. [Tile Visualization](../modules/tile-visualization.md) or [WebFront Visualization](../modules/webfront-visualization.md)) exists. It is checked against the ID of the visualization instance. The operation name is case-sensitive. If the operation is not registered, the function fails with "Cannot verify unsupported operation". The function does not require the RBAC feature in the license. **Example** ```php $VisuID = 12345; // ID of a tile visualization if (IPS_HasPermission($VisuID, 'VISUALIZATION')) { echo 'Access granted'; } ``` ## IPS_IsAdministrator Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/ips-isadministrator/ `bool IPS_IsAdministrator()` checks whether the currently logged in user is an administrator **Returns** (bool): If the currently logged in user is an administrator, __TRUE__ is returned, otherwise __FALSE__. The function checks whether the user in whose context the current execution runs (see [IPS_GetLoggedInUser](management-permissions.md)) is an administrator. Administrators are the @admin user and every user that has been assigned the @admin role. For the @unknown user the function always returns __FALSE__. Administrator permissions are required e.g. for all functions that modify users and roles. The function does not require the RBAC feature in the license. To check an arbitrary user, [IPS_UserIsAdministrator](management-permissions.md) can be used. **Example** ```php if (IPS_IsAdministrator()) { echo 'The script runs with administrator permissions'; } ``` ## IPS_IsUnknown Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/ips-isunknown/ `bool IPS_IsUnknown()` checks whether the current execution runs without a logged in user **Returns** (bool): If the current user is @unknown, __TRUE__ is returned, otherwise __FALSE__. The function checks whether the current execution runs without a logged in user, i.e. whether [IPS_GetLoggedInUser](management-permissions.md) returns the special user @unknown. This is the case if no user is logged in in the triggering context or no login succeeded. The @unknown user has no permissions at all and is not an administrator. The function does not require the RBAC feature in the license. **Example** ```php if (IPS_IsUnknown()) { echo 'No user logged in'; } else { echo 'Logged in as ' . IPS_GetLoggedInUser(); } ``` ## Roles Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ ## IPS_AddPermissionToRole Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ips-addpermissiontorole/ `bool IPS_AddPermissionToRole(string $Role, int $ObjectID, string $Operation, bool $Recursive)` adds a permission to a role **Parameters** - `$Role` (string): Name of the role - `$ObjectID` (int): ID of the object the permission applies to - `$Operation` (string): Name of the operation, e.g. VISUALIZATION - `$Recursive` (bool): Specifies whether the permission also applies to all objects below __ObjectID__ (__TRUE__) or only to the object itself (__FALSE__) **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function grants the role __Role__ the permission to perform __Operation__ on the object __ObjectID__. All users the role is assigned to thereby receive this permission. If __Recursive__ is enabled, the permission applies to the object and all objects below it – a recursive permission on the root object (ID 0) therefore applies to all objects. A permission is identified by __ObjectID__, __Operation__ and __Recursive__ together; the same __ObjectID__ and __Operation__ can therefore be added once recursively and once non-recursively. __Operation__ must be an operation registered in the system, otherwise the function fails with "Cannot verify unsupported operation". The operation is case-sensitive. Currently there is the operation `VISUALIZATION` (access to a visualization with all its objects). It is registered as soon as a visualization instance (e.g. [Tile Visualization](../modules/tile-visualization.md)) exists and is checked against the ID of the visualization instance. The checks are performed in this order: operation, role ("Role with name '…' does not exist"), object ("Object #… does not exist"). If the same permission already exists, the function fails with "Role already has this permission". The executing user must be an administrator (see [IPS_IsAdministrator](management-permissions.md)), otherwise the function fails with "Administrator permissions are required for this action!". > **Note:** Role management is only available with a license that includes the RBAC feature. Otherwise the function fails with "This function is only available for licenses with the RBAC feature enabled!". If more users exist than the license allows, the function fails with "Your license is currently limited to … users. Please consider upgrading the license to more users!". **Example** ```php // The role may open the visualization with the ID 12345 IPS_AddPermissionToRole('Residents', 12345, 'VISUALIZATION', false); ``` ## IPS_CreateRole Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ips-createrole/ `bool IPS_CreateRole(string $Role)` creates a new role **Parameters** - `$Role` (string): Name of the role to be created **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function creates a new role with the name __Role__. A new role has no permissions yet. They are added with [IPS_AddPermissionToRole](management-permissions.md). Afterwards the role can be assigned to any number of users with [IPS_AddRoleToUser](management-permissions.md), who thereby receive all permissions of the role. Roles can also be managed in the [Permission Control](../modules/permission-control.md). The name must not be empty ("Role cannot be empty") and must be unique, otherwise the function fails with "Role with name '…' already exists". The name is case-sensitive. The role @admin always exists and grants all permissions. The executing user must be an administrator (see [IPS_IsAdministrator](management-permissions.md)), otherwise the function fails with "Administrator permissions are required for this action!". > **Note:** Role management is only available with a license that includes the RBAC feature. Otherwise the function fails with "This function is only available for licenses with the RBAC feature enabled!". If more users exist than the license allows, the function fails with "Your license is currently limited to … users. Please consider upgrading the license to more users!". **Example** ```php if (!IPS_RoleExists('Residents')) { IPS_CreateRole('Residents'); } // Allow access to the visualization with the ID 12345 IPS_AddPermissionToRole('Residents', 12345, 'VISUALIZATION', false); // Assign the role to a user IPS_AddRoleToUser('anna', 'Residents'); ``` ## IPS_DeleteRole Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ips-deleterole/ `bool IPS_DeleteRole(string $Role)` deletes a role **Parameters** - `$Role` (string): Name of the role to be deleted **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function deletes the role with the name __Role__ together with its permissions. The role is automatically removed from all users it was assigned to – they lose all permissions they only had through this role. If the role does not exist, the function fails with "Role with name '…' does not exist". The role @admin cannot be deleted ("Role @admin cannot be deleted!"). The executing user must be an administrator (see [IPS_IsAdministrator](management-permissions.md)), otherwise the function fails with "Administrator permissions are required for this action!". > **Note:** Role management is only available with a license that includes the RBAC feature. Otherwise the function fails with "This function is only available for licenses with the RBAC feature enabled!". If more users exist than the license allows, the function fails with "Your license is currently limited to … users. Please consider upgrading the license to more users!". **Example** ```php if (IPS_RoleExists('Residents')) { IPS_DeleteRole('Residents'); } ``` ## IPS_GetRole Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ips-getrole/ `array IPS_GetRole(string $Role)` returns information about a role **Parameters** - `$Role` (string): Name of the role **Returns** (array) The following information is available as __key => value__ pairs: | Index | Type | Description | | --------------- | ------ | ---------------------------------------------------------- | | __RoleName__ | string | Name of the role | | __Permissions__ | array | List of the permissions of the role (see permission table) | __Permission table__ | Index | Type | Description | | ------------- | ------- | --------------------------------------------------------- | | __ObjectID__ | integer | ID of the object the permission applies to | | __Operation__ | string | Name of the operation, e.g. VISUALIZATION | | __Recursive__ | boolean | The permission also applies to all objects below ObjectID | The function returns the name and the permissions of the role with the name __Role__. If the role does not exist, the function fails with "Role with name '…' does not exist". The role @admin has no entries in __Permissions__, but still grants all permissions. Whether a role has a specific permission is checked by [IPS_RoleHasPermission](management-permissions.md). The function requires neither administrator permissions nor the RBAC feature in the license. **Example** ```php print_r(IPS_GetRole('Residents')); /* e.g. returns: Array ( [Permissions] => Array ( [0] => Array ( [ObjectID] => 12345 [Operation] => VISUALIZATION [Recursive] => ) ) [RoleName] => Residents ) */ ``` ## IPS_GetRoleList Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ips-getrolelist/ `array IPS_GetRoleList()` returns the names of all roles **Returns** (array): An array with the names of all existing roles. The function returns the names of all roles, including the always existing role @admin. The order of the entries is not guaranteed. Details of a role are returned by [IPS_GetRole](management-permissions.md). The function requires neither administrator permissions nor the RBAC feature in the license. **Example** ```php print_r(IPS_GetRoleList()); /* e.g. returns: Array ( [0] => @admin [1] => Residents ) */ ``` ## IPS_RemovePermissionFromRole Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ips-removepermissionfromrole/ `bool IPS_RemovePermissionFromRole(string $Role, int $ObjectID, string $Operation, bool $Recursive)` removes a permission from a role **Parameters** - `$Role` (string): Name of the role - `$ObjectID` (int): ID of the object the permission applies to - `$Operation` (string): Name of the operation, e.g. VISUALIZATION - `$Recursive` (bool): Specifies whether the permission also applies to all objects below __ObjectID__ (__TRUE__) or only to the object itself (__FALSE__) **Returns** (bool): If the function succeeds, it returns __TRUE__, otherwise __FALSE__. The function removes the permission to perform __Operation__ on the object __ObjectID__ from the role __Role__. __ObjectID__, __Operation__ and __Recursive__ must exactly match the permission added with [IPS_AddPermissionToRole](management-permissions.md) (see [IPS_GetRole](management-permissions.md)), otherwise the function fails with "Role does not have this permission". __Operation__ must be an operation registered in the system, otherwise the function fails with "Cannot verify unsupported operation". The operation is case-sensitive. Currently there is the operation `VISUALIZATION` (access to a visualization with all its objects). It is registered as soon as a visualization instance (e.g. [Tile Visualization](../modules/tile-visualization.md)) exists and is checked against the ID of the visualization instance. The checks are performed in this order: operation, role ("Role with name '…' does not exist"), object ("Object #… does not exist"). The executing user must be an administrator (see [IPS_IsAdministrator](management-permissions.md)), otherwise the function fails with "Administrator permissions are required for this action!". > **Note:** Role management is only available with a license that includes the RBAC feature. Otherwise the function fails with "This function is only available for licenses with the RBAC feature enabled!". If more users exist than the license allows, the function fails with "Your license is currently limited to … users. Please consider upgrading the license to more users!". **Example** ```php // The role may no longer open the visualization with the ID 12345 IPS_RemovePermissionFromRole('Residents', 12345, 'VISUALIZATION', false); ``` ## IPS_RoleExists Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ips-roleexists/ `bool IPS_RoleExists(string $Role)` checks whether a role exists **Parameters** - `$Role` (string): Name of the role to be checked **Returns** (bool): If the role exists, __TRUE__ is returned, otherwise __FALSE__. The function checks whether a role with the name __Role__ exists. The name is case-sensitive. The role @admin always exists. The function requires neither administrator permissions nor the RBAC feature in the license. **Example** ```php if (IPS_RoleExists('Residents')) { echo 'Role already exists!'; } ``` ## IPS_RoleHasPermission Source: https://www.symcon.de/en/service/documentation/command-reference/management-permissions/roles/ips-rolehaspermission/ `bool IPS_RoleHasPermission(string $Role, int $ObjectID, string $Operation)` checks whether a role has a permission for an object **Parameters** - `$Role` (string): Name of the role - `$ObjectID` (int): ID of the object to be checked - `$Operation` (string): Name of the operation, e.g. VISUALIZATION **Returns** (bool): If the role has the permission, __TRUE__ is returned, otherwise __FALSE__. The function checks whether the role __Role__ may perform __Operation__ on the object __ObjectID__. This is the case if the role has a permission with this operation directly for __ObjectID__ or a recursive permission for __ObjectID__ or one of its parent objects (up to the root object with the ID 0). The role @admin always has all permissions. Only the permissions of the role are taken into account. Whether a user is permitted – by their own permissions or one of their roles – is checked by [IPS_UserHasPermission](management-permissions.md). The checks are performed in this order: operation ("Cannot verify unsupported operation"), object ("Object #… does not exist"), role ("Role with name '…' does not exist"). The operation must be registered in the system; currently there is the operation `VISUALIZATION` as soon as a visualization instance exists. The function requires neither administrator permissions nor the RBAC feature in the license. **Example** ```php if (IPS_RoleHasPermission('Residents', 12345, 'VISUALIZATION')) { echo 'The role may open the visualization'; } ```