User Permission and Attribute Synchronization¶
Some IT shops prefer to manage user permissions, group membership, and user attributes in Active Directory instead of in the CloudBolt UI. This page explains how to set up and customize that synchronization.
How It Works¶
Whenever an “external user” (one who is authenticating with credentials in an external source), logs into CloudBolt, CloudBolt runs all enabled actions for the “External User Sync” trigger point. These actions can run arbitrary code to fetch that user’s permissions and attributes in an external system (like AD) and then add/remove the user to the appropriate groups and roles in CloudBolt. This happens synchronously, meaning that the user will not be logged in and be able to use the UI until these CB actions complete.
Using the “User Permission Sync From LDAP” Action¶
CloudBolt comes with a sync action enabled by default that can automatically grant CloudBolt permissions to a user based on their LDAP permissions. For each LDAP utility you create in CloudBolt, you will need to map its OUs and groups to their equivalent CloudBolt Groups and Roles.
To set up the user permission sync, you’ll need to create some mappings:
- Go to Admin → Security → LDAP Authentication Settings → your LDAP utility.
- Click the New LDAP Mapping button on the Mappings tab. The first dialog lets you select the LDAP OU and group that the user must match in order to receive CloudBolt roles. You’ll need the full LDAP distinguished name, which can be found in the object’s properties in AD. If this mapping will grant any global roles, you will also set those here.
- Next, click the Add Group Roles link on your newly created mapping. This dialog lets you select a CloudBolt group and the roles that should be granted in that group. This link will not show for Super Admin mappings.
- Repeat step 3 as necessary if you want this mapping to grant roles in multiple groups.
- To test your mappings, click the Sync Mappings button. You’ll be able to select a user and do a dry run of the sync action to see which roles the user would receive.
Roles granted by mappings are additive: if a user is be impacted by more than one mapping, they will receive all the roles in each mapping.
If using Active Directory, note that the user’s primary group is not used when applying mappings.
Synchronizing User Attributes from LDAP¶
In addition to synchronizing permissions and group membership from LDAP, CloudBolt can also synchronize user attributes. To set this up:
1. Go to Admin → LDAP Authentication Settings → your LDAP utility → Attribute Mappings tab. 2. Click the New LDAP Mapping button. This will allow you to map the name of an attribute in LDAP with a parameter in CloudBolt. 3. To test your mappings, click the Sync Mappings button. You’ll be able to select a user and do a dry run of the sync action to see which parameter values would be added to the user profile.
Parameters that have the “show on objects” attribute set to true will be displayed on the user’s details page.
Once parameters have been set on users, they can be used in actions. CloudBolt ships with an example plug-in that utilizes parameters. This plug-in can be seen at Admin → Orchestration Actions → Provision Server → Sample Per-User Server Limits.
To use this to control the maximum number of servers each user can own in CloudBolt by setting an attribute in LDAP:
- Enable the aforementioned action
- Create a custom field of type Integer called max_servers with show on objects set to True.
- Create attributes in LDAP on the users you want to have a server limit on that is different than the default defined in
- Create a mapping to map the LDAP attribute you created to the max_servers parameter in CloudBolt
- Sync Mappings and then go to the user’s details page to make sure the parameter is properly set.
- Test setting the limit to 0 in LDAP, then log in as that user and try to provision a server.
- The Sample Per-User Server Limits action will cause the provisioning job to fail before it takes any action.
This action is one specific example of how attributes synchronized from LDAP to parameters on servers in CloudBolt can be used, but this feature can be used to solve any case where data needs copied from LDAP to user profiles in CloudBolt and then used programmatically.
Creating Custom Actions¶
To manage the external user sync actions, navigate in the UI to Admin → Orchestration Actions → Other → External Users Sync. You can use the default CloudBolt action as a sample when developing your own action. If you modify it, we recommend first duplicating it, and then modifying the new one you created.
You can also look in the CloudBolt Forge for additional examples.
You could test your newly enabled external user sync action by logging out and logging in, but that takes some time, and, if your plugin has significant problems, it could prevent login.
A faster, safer way to test is to navigate to Admin → Users, click on an external user you can test with, and click the Sync External User button. We recommended using a user account that is not the one you are logged in as, because a problematic sync could remove your admin permissions and prevent you from testing further.
You can also sync all users at once using the Mappings tab on the LDAP utility page. This will only sync users who have already logged into CloudBolt at some point in the past. Note that the dialog may take a long time to process if you are syncing a large number of users.