Version information
This version is compatible with:
- Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x
- Puppet >= 5.5.0 < 9.0.0
Start using this module
Add this module to your Puppetfile:
mod 'eitco-dcom', '0.3.3'
Learn more about managing modules with a PuppetfileDocumentation
dcom
Table of Contents
Description
This module manages the user / group assignments in the DCOM configuration for Windows apps. Changing those DCOM settings usually means to do it by hand, complex self-written scripts...or by using this module!
It can help you out with the following things: manage the user identity of the app it should be launched as, manage the user access permissions, manage the local / remote launch & activation permissions.
In order to do that the dcom module uses an extended version of a tool called "DComPerm" whose soure code can be found in the Windows SDK. The extended version can be found here: https://github.com/albertony/dcompermex
Setup
In order to use it you need to include the main class first, which will then ensure that the DComPerm.exe will be copied into the TEMP-folder of the system.
include dcom
Then - depending on what you need - just call the defined resources from your module like that:
dcom::identity{ 'Setting up identities':
app_identities => $app_identities,
}
# or
dcom::activation_launch_permissions{ 'Setting up activation & launch permissions':
app_activation_launch_permissions => $app_activation_launch_permissions,
}
# or
dcom::access_permissions{ 'Setting up access permissions':
app_access_permissions => $app_access_permissions,
}
Usage
The configuration depends on hiera. To set up the applications the way you want them, you need to know the App-ID of the application. Each program has it´s own App-ID which will be always the same in every installation. You can either find it out by going through the DCOM-config manually (dcomcnfg.exe) or with the help of PowerShell. Here are some examples.
Get-WMIObject Win32_DCOMApplicationSetting -Filter 'Caption like "%Microsoft Word%"'
Get-WMIObject Win32_DCOMApplicationSetting -Filter 'Description like "%Microsoft Excel%"'
Get-WMIObject will then create a WQL query out of it and return the result. The %-sign is a wildcard (like *).
Every defined resource is expecting the parameter to be of the datatype Hash. The resources are designed to manage one or more applications or users / groups. The keys inside the hash are predefined and mandatory.
:warning: Major change in version 0.3.0:
When a Windows machine is created freshly it only contains a DCOM config list of the default pre-installed Windows-Apps.
If you install further apps (and you want to manage them) it is required to update the list manually by opening the Component-Snap-In (dcomcnfg) and klicking once at the DCOM config tree.
Otherwise this module won´t be able to successfully change the settings although it will tell you it did.
To overcome this overhead the module will now check wether the app (identified by the AppID) already exists in this list or not and create an entry in case it doesn´t.
It will use the name of the key inside of the hash to name the DCOM app in that config list so choose the name wisely!
I recommend to name the key the way it would have been named by default (e.g. 'Microsoft Word 97 - 2003 Document' instead of 'Word').
It has no other impact on the functionality but the naming.
Last but not least it does not affect you at all if the AppID already exist in the DCOM config list.
The entry can be found here: HKEY_CLASSES_ROOT\AppID\{APPID_of_the_software}
Identity
There are three categories of identities in DCOM for regular apps: launching user, interactive user & custom user. In the following example we configure the Word application to be launched in the context of the user "domain_user".
your_module::app_identities:
'Microsoft Word 97 - 2003 Document':
appID: '{00020906-0000-0000-C000-000000000046}'
identity_type: 'custom user'
user: 'CONTOSO\domain_user'
password: 'password'
The user & password keys are only needed for the "custom user" identity type.
Now let´s add a few more apps with a different identity configuration.
your_module::app_identities:
'Microsoft Word 97 - 2003 Document':
appID: '{00020906-0000-0000-C000-000000000046}'
identity_type: 'custom user'
user: 'CONTOSO\domain_user'
password: 'password'
'Outlook Message Attachment':
appID: '{00020D09-0000-0000-C000-000000000046}'
identity_type: 'custom user'
user: 'local_user'
password: 'password'
'Microsoft Excel Application':
appID: '{00020812-0000-0000-C000-000000000046}'
identity_type: 'launching user'
'Microsoft PowerPoint Slide':
appID: '{048EB43E-2059-422F-95E0-557DA96038AF}'
identity_type: 'interactive user'
Done!
Access permissions
The access permissions are configured in a similar way, just with a few more keys. On top of that you can also set the configuration for one or more users. Let´s see an example:
your_module::app_access_permissions:
'Microsoft Word 97 - 2003 Document':
appID: '{00020906-0000-0000-C000-000000000046}'
ensure: 'present'
users:
- 'CONTOSO\user1'
acl: 'permit'
level: 'l,r'
'Microsoft Excel Application':
appID: '{00020812-0000-0000-C000-000000000046}'
ensure: 'present'
users:
- 'CONTOSO\user1'
- 'CONTOSO\user2'
acl: 'deny'
level: 'r'
'Microsoft PowerPoint Slide':
appID: '{048EB43E-2059-422F-95E0-557DA96038AF}'
ensure: 'present'
users:
- 'CONTOSO\user2'
- 'local_user3'
acl: 'permit'
level: 'l'
What if it is not a user but a local group that you want to add? Or maybe even a domain group?
your_module::app_access_permissions:
'Microsoft Word 97 - 2003 Document':
appID: '{00020906-0000-0000-C000-000000000046}'
ensure: 'present'
users:
- 'Administrators' # local group
- 'CONTOSO\Admin-Group' # domain group
acl: 'permit'
level: 'l,r'
Launch and activation permissions
The launch & activation permissions are configured the same way as the access permissions.
your_module::app_activation_launch_permissions:
'Microsoft Word 97 - 2003 Document':
appID: '{00020906-0000-0000-C000-000000000046}'
ensure: 'present'
users:
- 'CONTOSO\user1'
acl: 'permit'
level: 'la'
'Microsoft Excel Application':
appID: '{00020812-0000-0000-C000-000000000046}'
ensure: 'present'
users:
- 'CONTOSO\user2'
- 'local_user3'
acl: 'deny'
level: 'l,r'
'Microsoft PowerPoint Slide':
appID: '{048EB43E-2059-422F-95E0-557DA96038AF}'
ensure: 'present'
users:
- 'local_user3'
acl: 'permit'
level: 'ra'
Now let´s assume you want to have two users configured for the same app but with different permissions. Unfortunately I haven´t found a better way yet...but here is a workaround how it could be done (but be aware of it´s impact):
your_module::app_activation_launch_permissions:
'Microsoft Word 97 - 2003 Document - user1':
appID: '{00020906-0000-0000-C000-000000000046}'
ensure: 'present'
users:
- 'CONTOSO\user1'
acl: 'permit'
level: 'la'
'Microsoft Word 97 - 2003 Document - user2':
appID: '{00020906-0000-0000-C000-000000000046}'
ensure: 'present'
users:
- 'CONTOSO\user2'
acl: 'permit'
level: 'l,r'
If an application is configured with
ensure: 'absent'
then all the users configured in the users key will be removed from the DCOM configuration for that application!
Reference
Parameters
Hash app_identities:
'key':
Pattern['^{[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*}$'] appID
String[Enum['custom user','interactive user','launching user']] identity_type
Optional[String] user
Optional[String] password
Hash app_access_permissions:
'key':
Pattern['^{[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*}$'] appID
String[Enum['present','absent']] ensure
Array[String] users
String[Enum['permit','deny']] acl
String[Enum['l','r','l,r']] level
Hash app_activation_launch_permissions:
'key':
Pattern['^{[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*-[A-Z0-9].*}$'] appID
String[Enum['present','absent']] ensure
Array[String] users
String[Enum['permit','deny']] acl
String[Enum['l','r','l,r','la','ll','ra','rr']] level
Default: undef
Classes
# main class
Class['dcom']
# ensures that the DComPerm.exe is present within the TEMP-path
Class['dcom::prerequisites']
Defined resources
# manages the launch identity of an app
dcom::identity
# manages the access permissions for an app
dcom::access_permissions
# manages the activation and launch permissions for an app
dcom::activation_launch_permissions
Limitations
- Predefined (default) user / groups can´t be changed
- a user / group can be added through this module, the removal however won´t happen automatically when removing them from the nested hash
- workaround #1: create new hash element with the user / group marked as 'ensure: absent'
- workaround #2: remove the user / group from DCOM-config by hand
- This module is limited by the features that the DComPerm-tool offers
- DComPerm requires at least Vista / Server 2008
Final thoughts
Although the feature set is mostly complete (based on what can be done with DComPerm) there might be still some room for improvement. If you have some feedback or something isn´t working correctly - feel free to create an issue in the GitHub-repository.
Changelog
All notable changes to this project will be documented in this file.
Release 0.3.3
- Updating library dependencies & Puppet 8 preparation
Release 0.3.2
- Added a way for the module to determine wether the app is listed in the DCOM config already or not and adding it to the list in case it isn´t
- Added error handling: if DComPermEx couldn´t realize the settings an error will be raised (the exception of DComPermEx is only visible when running in debug-mode though)
- Updated the README documentation
- Included License of DComPermEx-Tool (since i forgot it in the previous release - credit where credit is due!)
- Change: instead of using a temporary path DComPermEx.exe will be copied under 'C:\Program Files\DComPermEx' from now on
Release 0.2.2
- Minor changes in README documentation
Release 0.2.0
- The initial release
Dependencies
- puppetlabs-stdlib (>= 6.1.0)
- puppetlabs-powershell (>= 2.3.0)
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS Copyright (c) 2023 European IT Consultancy EITCO GmbH Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.