Adds 'm365 entra group add' command. Closes pnp#5476

mkm17 · Feb 11, 2024 · 7b7aace · 7b7aace
1 parent 7076f2e
commit 7b7aace
Show file tree

Hide file tree

Showing 8 changed files with 1,085 additions and 0 deletions.
diff --git a/docs/docs/cmd/entra/group/group-add.mdx b/docs/docs/cmd/entra/group/group-add.mdx
@@ -0,0 +1,231 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# entra group add
+
+Creates a Microsoft Entra group
+
+## Usage
+
+```sh
+m365 entra group add [options]
+```
+
+## Alias
+
+```sh
+m365 aad group add [options]
+```
+
+## Options
+
+```md definition-list
+`-n, --displayName <displayName>`
+: The name for the group. The maximum length is 256 characters.
+
+`-d, --description [description]`
+: The description for the group.
+
+`-t, --type <type>`
+: The group type. Valid values: `microsoft365` or `security`.
+
+`-m, --mailNickname [mailNickname]`
+: The mail alias for the group (part before the @). Maximum length is 64 characters.
+
+`--ownerIds [ownerIds]`
+: Comma-separated list of IDs of Microsoft Entra ID users that will be group owners. Specify either `ownerIds` or `ownerUserNames`, but not both.
+
+`--ownerUserNames [ownerUserNames]`
+: Comma-separated list of UPNs of Microsoft Entra ID users that will be group owners. Specify either `ownerIds` or `ownerUserNames`, but not both.
+
+`--memberIds [memberIds]`
+: Comma-separated list of IDs of Microsoft Entra ID users that will be group members. Specify either `memberIds` or `memberUserNames`, but not both.
+
+`--memberUserNames [memberUserNames]`
+: Comma-separated list of UPNs of Microsoft Entra ID users that will be group members. Specify either `memberIds` or `memberUserNames`, but not both.
+
+`--visibility [visibility]`
+: Specifies the group join policy and group content visibility for Microsoft 365 groups. Possible values are: `Private`, `Public`, or `HiddenMembership`. Defaults to `Public`. Specify only when creating a group of type `microsoft365`.
+```
+
+<Global />
+
+## Remarks
+
+:::info
+
+The `visibility` option affects the behavior of the group.
+
+With the `Public` visibility:
+- Anyone can join the group without needing owner permission. 
+- Anyone can view the attributes of the group. 
+- Anyone can see the members of the group.
+
+With the `Private` visibilty:
+- Owner permission is needed to join the group.
+- Anyone can view the attributes of the group.
+- Anyone can see the members of the group.
+
+With the `HiddenMembership` visibility:
+- Owner permission is needed to join the group.
+- Guest users cannot view the attributes of the group.
+- Non-members cannot see the members of the group. This setting doesn't affect visibility of group owners.
+- Administrators (global, company, user, and helpdesk) can view the membership of the group.
+- The group appears in the global address book (GAL).
+
+:::
+
+:::note
+
+The `HiddenMembership` visibility can be set only for Microsoft 365 groups when the groups are created. It can't be updated later.
+
+:::
+
+This command allows using unknown options. For a comprehensive list of group properties, please refer to the [Graph documentation page](https://learn.microsoft.com/graph/api/resources/group?view=graph-rest-1.0#properties).
+
+If the specified option is not found, you will receive a `Resource 'xyz' does not exist or one of its queried reference-property objects are not present.` error.
+
+## Examples
+
+Create a security group without any owners or members
+
+```sh
+m365 entra group add --displayName Developers --type security
+```
+
+Create a private Microsoft 365 group with owners and members and a custom mail address
+
+```sh
+m365 entra group add --displayName Developers --type microsoft365 --mailNickname devs --ownerUserNames [email protected] --memberUserNames "[email protected],[email protected]" --visibility Private
+```
+
+Create a public Microsoft 365 group without any owners or members
+
+```sh
+m365 entra group add --displayName Developers --type microsoft365 --description "This group is for all developers in the company." --visibility Public
+```
+
+
+## Response
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```json
+  {
+    "id": "ae0e8388-cd70-427f-9503-c57498ee3337",
+    "deletedDateTime": null,
+    "classification": null,
+    "createdDateTime": "2024-01-10T11:33:18Z",
+    "creationOptions": [],
+    "description": "This group is for all developers in the company.",
+    "displayName": "Developers",
+    "expirationDateTime": null,
+    "groupTypes": [
+      "Unified"
+    ],
+    "isAssignableToRole": null,
+    "mail": "[email protected]",
+    "mailEnabled": true,
+    "mailNickname": "devs",
+    "membershipRule": null,
+    "membershipRuleProcessingState": null,
+    "onPremisesDomainName": null,
+    "onPremisesLastSyncDateTime": null,
+    "onPremisesNetBiosName": null,
+    "onPremisesSamAccountName": null,
+    "onPremisesSecurityIdentifier": null,
+    "onPremisesSyncEnabled": null,
+    "preferredDataLocation": null,
+    "preferredLanguage": null,
+    "proxyAddresses": [
+      "SMTP:[email protected]"
+    ],
+    "renewedDateTime": "2024-01-10T11:33:18Z",
+    "resourceBehaviorOptions": [],
+    "resourceProvisioningOptions": [],
+    "securityEnabled": true,
+    "securityIdentifier": "S-1-12-1-2920186760-1115671920-1959068565-926150296",
+    "theme": null,
+    "visibility": "Public",
+    "onPremisesProvisioningErrors": [],
+    "serviceProvisioningErrors": []
+  }
+  ```
+
+  </TabItem>
+  <TabItem value="Text">
+
+  ```text
+  classification               : null
+  createdDateTime              : 2024-01-10T11:36:31Z
+  creationOptions              : []
+  deletedDateTime              : null
+  description                  : This group is for all developers in the company.
+  displayName                  : Developers
+  expirationDateTime           : null
+  groupTypes                   : ["Unified"]
+  id                           : f7bce6b2-c017-4a00-ba0c-fbbe458364aa
+  isAssignableToRole           : null
+  mail                         : [email protected]
+  mailEnabled                  : true
+  mailNickname                 : devs
+  membershipRule               : null
+  membershipRuleProcessingState: null
+  onPremisesDomainName         : null
+  onPremisesLastSyncDateTime   : null
+  onPremisesNetBiosName        : null
+  onPremisesProvisioningErrors : []
+  onPremisesSamAccountName     : null
+  onPremisesSecurityIdentifier : null
+  onPremisesSyncEnabled        : null
+  preferredDataLocation        : null
+  preferredLanguage            : null
+  proxyAddresses               : ["SMTP:[email protected]"]
+  renewedDateTime              : 2024-01-10T11:36:31Z
+  resourceBehaviorOptions      : []
+  resourceProvisioningOptions  : []
+  securityEnabled              : true
+  securityIdentifier           : S-1-12-1-4156352178-1241563159-3204123834-2858713925
+  serviceProvisioningErrors    : []
+  theme                        : null
+  visibility                   : Public
+  ```
+
+  </TabItem>
+  <TabItem value="CSV">
+
+  ```csv
+  id,deletedDateTime,classification,createdDateTime,description,displayName,expirationDateTime,isAssignableToRole,mail,mailEnabled,mailNickname,membershipRule,membershipRuleProcessingState,onPremisesDomainName,onPremisesLastSyncDateTime,onPremisesNetBiosName,onPremisesSamAccountName,onPremisesSecurityIdentifier,onPremisesSyncEnabled,preferredDataLocation,preferredLanguage,renewedDateTime,securityEnabled,securityIdentifier,theme,visibility
+  4c63e8cd-eb2b-4b0d-9251-d709cc75cf5e,,,2024-01-10T11:37:02Z,This group is for all developers in the company.,Developers,,,[email protected],1,devs,,,,,,,,,,,2024-01-10T11:37:02Z,1,S-1-12-1-1281616077-1259203371-165106066-1590654412,,Public
+  ```
+
+  </TabItem>
+  <TabItem value="Markdown">
+
+  ```md
+  # entra group add --displayName "Developers" --type "microsoft365" --description "This group is for all developers in the company." --visibility "Public" --mailNickname "devs"
+
+  Date: 1/10/2024
+
+  ## Developers (b3fd8e8f-eced-45c7-a366-178bc5c1db37)
+
+  Property | Value
+  ---------|-------
+  id | b3fd8e8f-eced-45c7-a366-178bc5c1db37
+  createdDateTime | 2024-01-10T11:37:39Z
+  description | This group is for all developers in the company.
+  displayName | Developers
+  mail | [email protected]
+  mailEnabled | true
+  mailNickname | devs
+  renewedDateTime | 2024-01-10T11:37:39Z
+  securityEnabled | true
+  securityIdentifier | S-1-12-1-3019738767-1170730221-2333566627-937148869
+  visibility | Public
+  ```
+
+  </TabItem>
+</Tabs>
+
diff --git a/docs/src/config/sidebars.ts b/docs/src/config/sidebars.ts
@@ -281,6 +281,11 @@ const sidebars: SidebarsConfig = {
         },
         {
           group: [
+            {
+              type: 'doc',
+              label: 'group add',
+              id: 'cmd/entra/group/group-add'
+            },
             {
               type: 'doc',
               label: 'group get',

diff --git a/src/m365/entra/aadCommands.ts b/src/m365/entra/aadCommands.ts
@@ -21,6 +21,7 @@ export default {
   APPROLEASSIGNMENT_ADD: `${prefix} approleassignment add`,
   APPROLEASSIGNMENT_LIST: `${prefix} approleassignment list`,
   APPROLEASSIGNMENT_REMOVE: `${prefix} approleassignment remove`,
+  GROUP_ADD: `${prefix} group add`,
   GROUP_GET: `${prefix} group get`,
   GROUP_LIST: `${prefix} group list`,
   GROUP_REMOVE: `${prefix} group remove`,

diff --git a/src/m365/entra/commands.ts b/src/m365/entra/commands.ts
@@ -22,6 +22,7 @@ export default {
   APPROLEASSIGNMENT_ADD: `${prefix} approleassignment add`,
   APPROLEASSIGNMENT_LIST: `${prefix} approleassignment list`,
   APPROLEASSIGNMENT_REMOVE: `${prefix} approleassignment remove`,
+  GROUP_ADD: `${prefix} group add`,
   GROUP_GET: `${prefix} group get`,
   GROUP_LIST: `${prefix} group list`,
   GROUP_REMOVE: `${prefix} group remove`,