@pnp/cli-microsoft365 6.8.0-beta.f473be5 → 6.9.0-beta.1cd2525

package/docs/docs/cmd/graph/schemaextension/schemaextension-list.mdx

@@ -0,0 +1,127 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# graph schemaextension list
+
+Get a list of schemaExtension objects created in the current tenant, that can be InDevelopment, Available, or Deprecated.
+
+## Usage
+
+```sh
+m365 graph schemaextension list [options]
+```
+
+## Options
+
+```md definition-list
+`-s, --status [status]`
+: The status to filter on. Available values are Available, InDevelopment, Deprecated
+
+`--owner [owner]`
+: The id of the owner to filter on
+
+`-p, --pageSize [pageSize]`
+: Number of objects to return
+
+`-n, --pageNumber [pageNumber]`
+: Page number to return if pageSize is specified (first page is indexed as value of 0)
+```
+
+<Global />
+
+## Remarks
+
+pageNumber is specified as a 0-based index. A value of 2 returns the third page of items. 
+
+## Examples
+
+Get a list of schemaExtension objects created in the current tenant, that can be InDevelopment, Available, or Deprecated.
+
+```sh
+m365 graph schemaextension list 
+```
+
+Get a list of schemaExtension objects created in the current tenant, with owner 617720dc-85fc-45d7-a187-cee75eaf239e
+
+```sh
+m365 graph schemaextension list --owner 617720dc-85fc-45d7-a187-cee75eaf239e
+```
+
+Get a list of schemaExtension objects created in the current tenant, with owner 617720dc-85fc-45d7-a187-cee75eaf239e and return the third page of results of 10
+
+```sh
+m365 graph schemaextension list --owner 617720dc-85fc-45d7-a187-cee75eaf239e --pageNumber 2 --pageSize 10
+```
+
+## Response
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```json
+  [
+    {
+      "id": "adatumisv_exo2",
+      "description": "sample description",
+      "targetTypes": [
+        "Message"
+      ],
+      "status": "Available",
+      "owner": "617720dc-85fc-45d7-a187-cee75eaf239e",
+      "properties": [
+        {
+          "name": "p1",
+          "type": "String"
+        },
+        {
+          "name": "p2",
+          "type": "String"
+        }
+      ]
+    }
+  ]
+  ```
+
+  </TabItem>
+  <TabItem value="Text">
+
+  ```text
+  id              description         targetTypes  status     owner                                 properties                                                                                                                  
+  --------------  ------------------  -----------  ---------  ------------------------------------  --------------------------------------------------------------
+  adatumisv_exo2  sample description  Message      Available  617720dc-85fc-45d7-a187-cee75eaf239e  [{"name":"p1","type":"String"},{"name":"p2","type":"String"}]
+  ```
+
+  </TabItem>
+  <TabItem value="CSV">
+
+  ```csv
+  id,description,status,owner,properties
+  adatumisv_exo2,sample description,Available,617720dc-85fc-45d7-a187-cee75eaf239e,"[{""name"":""p1"",""type"":""String""},{""name"":""p2"",""type"":""String""}]"
+  ```
+
+  </TabItem>
+  <TabItem value="Markdown">
+
+  ```md
+  # graph schemaextension list
+
+  Date: 2023-05-22
+
+  ## adatumisv_exo2
+
+  Property | Value
+  ---------|-------
+  id | adatumisv\_exo2
+  description | sample description
+  status | Available
+  owner | 617720dc-85fc-45d7-a187-cee75eaf239e
+  properties | [{"name":"p1","type":"String"},{"name":"p2","type":"String"}]
+  ```
+
+  </TabItem>
+</Tabs>
+
+## More information
+
+[https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/schemaextension_list](https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/schemaextension_list)

package/docs/docs/cmd/graph/schemaextension/schemaextension-remove.mdx

@@ -0,0 +1,46 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# graph schemaextension remove
+
+Removes specified Microsoft Graph schema extension
+
+## Usage
+
+```sh
+m365 graph schemaextension remove [options]
+```
+
+## Options
+
+```md definition-list
+`-i, --id <id>`
+: The unique identifier for the schema extension definition
+
+`--confirm`
+: Don't prompt for confirming removing the specified schema extension
+```
+
+<Global />
+
+## Remarks
+
+To remove specified schema extension definition, you have to pass the ID of the schema
+extension.
+
+## Examples
+
+Removes specified Microsoft Graph schema extension with ID domain_myExtension. Will prompt for confirmation
+
+```sh
+m365 graph schemaextension remove --id domain_myExtension 
+```
+
+Removes specified Microsoft Graph schema extension with ID domain_myExtension without prompt for confirmation
+
+```sh
+m365 graph schemaextension remove --id domain_myExtension --confirm
+```
+
+## Response
+
+The command won't return a response on success.

package/docs/docs/cmd/graph/schemaextension/schemaextension-set.mdx

@@ -0,0 +1,71 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# graph schemaextension set
+
+Updates a Microsoft Graph schema extension
+
+## Usage
+
+```sh
+m365 graph schemaextension set [options]
+```
+
+## Options
+
+```md definition-list
+`-i, --id <id>`
+: The unique identifier for the schema extension definition
+
+`--owner <owner>`
+: The ID of the Azure AD application that is the owner of the schema extension
+
+`-d, --description [description]`
+: Description of the schema extension
+
+`-s, --status [status]`
+: The lifecycle state of the schema extension. Accepted values are `Available` or `Deprecated`
+
+`-t, --targetTypes [targetTypes]`
+: Comma-separated list of Microsoft Graph resource types the schema extension targets
+
+`-p, --properties [properties]`
+: The collection of property names and types that make up the schema extension definition formatted as a JSON string
+```
+
+<Global />
+
+## Remarks
+
+The lifecycle state of the schema extension. The initial state upon creation is `InDevelopment`.
+Possible states transitions are from `InDevelopment` to `Available` and `Available` to `Deprecated`.
+The target types are the set of Microsoft Graph resource types (that support schema extensions) that this schema extension definition can be applied to. This option is specified as a comma-separated list.
+
+:::caution Escaping JSON in PowerShell
+
+When using the `--properties` option it's possible to enter a JSON string. In PowerShell 5 to 7.2 [specific escaping rules](./../../../user-guide/using-cli.mdx#escaping-double-quotes-in-powershell) apply due to an issue. Remember that you can also use [file tokens](./../../../user-guide/using-cli.mdx#passing-complex-content-into-cli-options) instead.
+
+:::
+
+## Examples
+
+ Update the description of a schema extension
+
+```sh
+m365 graph schemaextension set --id MySchemaExtension --owner 62375ab9-6b52-47ed-826b-58e47e0e304b --description "My schema extension" 
+```
+
+Update the target types and properties of a schema extension
+
+```sh
+m365 graph schemaextension set --id contoso_MySchemaExtension --owner 62375ab9-6b52-47ed-826b-58e47e0e304b --targetTypes "Group,User" --properties '[{"name":"myProp1","type":"Integer"},{"name":"myProp2","type":"String"}]'
+```
+
+Change the status of a schema extension to 'Available'
+
+```sh
+m365 graph schemaextension set --id contoso_MySchemaExtension --owner 62375ab9-6b52-47ed-826b-58e47e0e304b --status Available
+```
+
+## Response
+
+The command won't return a response on success.

package/docs/docs/cmd/graph/subscription/subscription-add.mdx

@@ -0,0 +1,149 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# graph subscription add
+
+Creates a Microsoft Graph subscription
+
+## Usage
+
+```sh
+m365 graph subscription add [options]
+```
+
+## Options
+
+```md definition-list
+`-r, --resource <resource>`
+: The resource that will be monitored for changes
+
+`-c, --changeType <changeType>`
+: The type of change in the subscribed resource that will raise a notification. The supported values are: `created`, `updated`, `deleted`. Multiple values can be combined using a comma-separated list
+
+`-u, --notificationUrl <notificationUrl>`
+: The URL of the endpoint that will receive the notifications. This URL must use the HTTPS protocol
+
+`-e, --expirationDateTime [expirationDateTime]`
+: The date and time when the webhook subscription expires. The time is in UTC, and can be an amount of time from subscription creation that varies for the resource subscribed to. If not specified, the maximum allowed expiration for the specified resource will be used
+
+`-s, --clientState [clientState]`
+: The value of the clientState property sent by the service in each notification. The maximum length is 128 characters
+```
+
+<Global />
+
+## Remarks
+
+On personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. On OneDrive for Business, you can subscribe to only the root folder.
+
+Notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other `driveItem` instances in its hierarchy. You cannot subscribe to `drive` or `driveItem` instances that are not folders, such as individual files.
+
+In Outlook, delegated permission supports subscribing to items in folders in only the signed-in user's mailbox.
+That means, for example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.
+
+To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:
+
+- Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
+- Do not use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.
+
+## Examples
+
+Create a subscription
+
+```sh
+m365 graph subscription add --resource "me/mailFolders('Inbox')/messages" --changeType "updated" --notificationUrl "https://webhook.azurewebsites.net/api/send/myNotifyClient" --expirationDateTime "2016-11-20T18:23:45.935Z" --clientState "secretClientState"
+```
+
+Create a subscription on multiple change types
+
+```sh
+m365 graph subscription add --resource groups --changeType updated,deleted --notificationUrl "https://webhook.azurewebsites.net/api/send/myNotifyClient" --expirationDateTime "2016-11-20T18:23:45.935Z" --clientState "secretClientState"
+```
+
+Create a subscription using the maximum allowed expiration for Group resources
+
+```sh
+m365 graph subscription add --resource groups --changeType "updated" --notificationUrl "https://webhook.azurewebsites.net/api/send/myNotifyClient"
+```
+
+## Response
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```json
+  {
+    "id": "d2df2c16-26ee-4431-ab22-3b133556fb26",
+    "resource": "groups",
+    "applicationId": "31359c7f-bd7e-475c-86db-fdb8c937548e",
+    "changeType": "updated",
+    "clientState": "some secret value",
+    "notificationUrl": "https://webhook.azurewebsites.net/api/changeNotificationHook",
+    "notificationQueryOptions": null,
+    "lifecycleNotificationUrl": null,
+    "expirationDateTime": "2023-05-23T18:23:45.935Z",
+    "creatorId": "0649d0bd-53dc-4e1d-a357-76f1d92d447b",
+    "includeResourceData": null,
+    "latestSupportedTlsVersion": "v1_2",
+    "encryptionCertificate": null,
+    "encryptionCertificateId": null,
+    "notificationUrlAppId": null
+  }
+  ```
+
+  </TabItem>
+  <TabItem value="Text">
+
+  ```text
+  applicationId            : 31359c7f-bd7e-475c-86db-fdb8c937548e
+  changeType               : updated
+  clientState              : some secret value
+  creatorId                : 0649d0bd-53dc-4e1d-a357-76f1d92d447b
+  encryptionCertificate    : null
+  encryptionCertificateId  : null
+  expirationDateTime       : 2023-05-23T18:23:45.935Z
+  id                       : e2484150-c26d-4ad6-af45-84ccf6ac985a
+  includeResourceData      : null
+  latestSupportedTlsVersion: v1_2
+  lifecycleNotificationUrl : null
+  notificationQueryOptions : null
+  notificationUrl          : https://webhook.azurewebsites.net/api/changeNotificationHook
+  notificationUrlAppId     : null
+  resource                 : groups
+  ```
+
+  </TabItem>
+  <TabItem value="CSV">
+
+  ```csv
+  id,resource,applicationId,changeType,clientState,notificationUrl,expirationDateTime,creatorId,latestSupportedTlsVersion
+  34270781-91cf-48ab-a930-072c5eedf808,groups,31359c7f-bd7e-475c-86db-fdb8c937548e,updated,some secret value,https://webhook.azurewebsites.net/api/changeNotificationHook,2023-05-23T18:23:45.935Z,0649d0bd-53dc-4e1d-a357-76f1d92d447b,v1_2
+  ```
+
+  </TabItem>
+  <TabItem value="Markdown">
+
+  ```md
+  # graph subscription add --resource "groups" --changeType "updated" --notificationUrl "https://webhook.azurewebsites.net/api/changeNotificationHook" --expirationDateTime "2023-05-23T18:23:45.935Z" --clientState "some secret value"
+
+  Date: 2023-05-22
+
+  ## 01d62711-6503-4b5b-8500-a5af0ee3967a
+
+  Property | Value
+  ---------|-------
+  id | 01d62711-6503-4b5b-8500-a5af0ee3967a
+  resource | groups
+  applicationId | 31359c7f-bd7e-475c-86db-fdb8c937548e
+  changeType | updated
+  clientState | some secret value
+  notificationUrl | https://webhook.azurewebsites.net/api/changeNotificationHook
+  expirationDateTime | 2023-05-23T18:23:45.935Z
+  creatorId | 0649d0bd-53dc-4e1d-a357-76f1d92d447b
+  latestSupportedTlsVersion | v1\_2
+  ```
+
+  </TabItem>
+</Tabs>
+

package/docs/docs/cmd/login.mdx

@@ -0,0 +1,204 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# login
+
+Log in to Microsoft 365
+
+## Usage
+
+```sh
+m365 login [options]
+```
+
+## Options
+
+```md definition-list
+`-t, --authType [authType]`
+: The type of authentication to use. Allowed values `certificate`, `deviceCode`, `password`, `identity`, `browser`, `secret`. Default `deviceCode`
+
+`-u, --userName [userName]`
+: Name of the user to authenticate. Required when `authType` is set to `password`
+
+`-p, --password [password]`
+: Password for the user or the certificate. Required when `authType` is set to `password`, or when `authType` is set to `certificate` and the provided certificate requires a password to open
+
+`-c, --certificateFile [certificateFile]`
+: Path to the file with certificate private key. When `authType` is set to `certificate`, specify either `certificateFile` or `certificateBase64Encoded`
+
+`--certificateBase64Encoded [certificateBase64Encoded]`
+: Base64-encoded string with certificate private key. When `authType` is set to `certificate`, specify either `certificateFile` or `certificateBase64Encoded`
+
+`--thumbprint [thumbprint]`
+: Certificate thumbprint. If not specified, and `authType` is set to `certificate`, it will be automatically calculated based on the specified certificate
+
+`-s, --secret [secret]`
+: Client Secret of the Azure AD application to use for authentication. Required when `authType` is set to `secret`.
+
+`--appId [appId]`
+: App ID of the Azure AD application to use for authentication. If not specified, use the app specified in the `CLIMICROSOFT365_AADAPPID` environment variable. If the environment variable is not defined, use the multitenant PnP Management Shell app
+
+`--tenant [tenant]`
+: ID of the tenant from which accounts should be able to authenticate. Use `common` or `organization` if the app is multitenant. If not specified, use the tenant specified in the `CLIMICROSOFT365_TENANT` environment variable. If the environment variable is not defined, use `common` as the tenant identifier
+
+`--cloud [cloud]`
+: Cloud to connect to. Allowed values `Public`, `USGov`, `USGovHigh`, `USGovDoD` and `China`. Default `Public`
+```
+
+<Global />
+
+## Remarks
+
+Using the `login` command you can log in to Microsoft 365.
+
+By default, the `login` command uses device code OAuth flow to log in to Microsoft 365. Alternatively, you can authenticate using a user name and password or certificate, which are convenient for CI/CD scenarios, but which come with their own [limitations](../user-guide/connecting-microsoft-365.mdx).
+
+When logging in to Microsoft 365 using the user name and password, next to the access and refresh token, the CLI for Microsoft 365 will store the user credentials so that it can automatically re-authenticate if necessary. Similarly to the tokens, the credentials are removed by re-authenticating using the device code or by calling the [logout](logout.mdx) command.
+
+When logging in to Microsoft 365 using a certificate, the CLI for Microsoft 365 will store the contents of the certificate so that it can automatically re-authenticate if necessary. The contents of the certificate are removed by re-authenticating using the device code or by calling the [logout](logout.mdx) command.  
+
+To log in to Microsoft 365 using a certificate or secret, you will typically [create a custom Azure AD application](../user-guide/using-own-identity.mdx). To use this application with the CLI for Microsoft 365, you will set the `CLIMICROSOFT365_AADAPPID` environment variable to the application's ID and the `CLIMICROSOFT365_TENANT` environment variable to the ID of the Azure AD tenant, where you created the Azure AD application. Also, please make sure to read about [the caveats when using the certificate login option](../user-guide/cli-certificate-caveats.mdx).
+
+Managed identity in Azure Cloud Shell is the identity of the user. It is neither system- nor user-assigned and it can't be configured. To log in to Microsoft 365 using managed identity in Azure Cloud Shell, set `authType` to `identity` and don't specify the `userName` option.
+
+When connecting to clouds other than `Public`, you'll need to use an Azure AD application registered in a directory provisioned in that cloud. If you try to login using the default Azure AD application, login will fail.
+
+## Examples
+
+Log in to Microsoft 365 using the device code
+
+```sh
+m365 login
+```
+
+Log in to Microsoft 365 using the device code in debug mode including detailed debug information in the console output
+
+```sh
+m365 login --debug
+```
+
+Log in to Microsoft 365 using a user name and password
+
+```sh
+m365 login --authType password --userName user@contoso.com --password pass@word1
+```
+
+Log in to Microsoft 365 using a PEM certificate
+
+```sh
+m365 login --authType certificate --certificateFile /Users/user/dev/localhost.pem
+```
+
+Log in to Microsoft 365 using a PEM certificate. Use the specified thumbprint
+
+```sh
+m365 login --authType certificate --certificateFile /Users/user/dev/localhost.pem  --thumbprint 47C4885736C624E90491F32B98855AA8A7562AF1
+```
+
+Log in to Microsoft 365 using a personal information exchange (.pfx) file
+
+```sh
+m365 login --authType certificate --certificateFile /Users/user/dev/localhost.pfx --password 'pass@word1'
+```
+
+Log in to Microsoft 365 using a personal information exchange (.pfx) file protected with an empty password
+
+```sh
+m365 login --authType certificate --certificateFile /Users/user/dev/localhost.pfx --password
+```
+
+Log in to Microsoft 365 using a personal information exchange (.pfx) file not protected with a password
+
+```sh
+m365 login --authType certificate --certificateFile /Users/user/dev/localhost.pfx
+```
+
+Log in to Microsoft 365 using a personal information exchange (.pfx) file. Use the specified thumbprint
+
+```sh
+m365 login --authType certificate --certificateFile /Users/user/dev/localhost.pfx --thumbprint 47C4885736C624E90491F32B98855AA8A7562AF1 --password 'pass@word1'
+```
+
+Log in to Microsoft 365 using a certificate from a base64-encoded string
+
+```sh
+m365 login --authType certificate --certificateBase64Encoded MIII2QIBAzCCCJ8GCSqGSIb3DQEHAaCCCJAEg...eX1N5AgIIAA== --thumbprint D0C9B442DE249F55D10CDA1A2418952DC7D407A3
+```
+
+Log in to Microsoft 365 using a system assigned managed identity. Applies to Azure resources with managed identity enabled,
+such as Azure Virtual Machines, Azure App Service or Azure Functions
+
+```sh
+m365 login --authType identity
+```
+
+Log in to Microsoft 365 using managed identity in Azure Cloud Shell. Uses the identity of the current user.
+
+```sh
+m365 login --authType identity
+```
+
+Log in to Microsoft 365 using a user-assigned managed identity. Client id or principal id also known as object id value can be specified in the `userName` option. Applies to Azure resources with managed identity enabled, such as Azure Virtual Machines, Azure App Service or Azure Functions
+
+```sh
+m365 login --authType identity --userName ac9fbed5-804c-4362-a369-21a4ec51109e
+```
+
+Log in to Microsoft 365 using your own multitenant Azure AD application
+
+```sh
+m365 login --appId 31359c7f-bd7e-475c-86db-fdb8c937548c
+```
+
+Log in to Microsoft 365 using your own Azure AD application that's restricted only to allow accounts from the specific tenant
+
+```sh
+m365 login --appId 31359c7f-bd7e-475c-86db-fdb8c937548c --tenant 31359c7f-bd7e-475c-86db-fdb8c937548a
+```
+
+Log in to Microsoft 365 using the interactive browser authentication. Uses the identity of the current user.
+
+```sh
+m365 login --authType browser
+```
+
+Log in to Microsoft 365 using a client secret.
+
+```sh
+m365 login --authType secret --secret topSeCr3t@007
+```
+
+## Response
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```json
+  To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code CQBMTLEFC to authenticate.
+  ```
+
+  </TabItem>
+  <TabItem value="Text">
+
+  ```text
+  To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code CQBMTLEFC to authenticate.
+  ```
+
+  </TabItem>
+  <TabItem value="CSV">
+
+  ```csv
+  To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code CQBMTLEFC to authenticate.
+  ```
+
+  </TabItem>
+  <TabItem value="Markdown">
+
+  ```md
+  To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code CQBMTLEFC to authenticate.
+  ```
+
+  </TabItem>
+</Tabs>
+

package/docs/docs/cmd/logout.mdx

@@ -0,0 +1,37 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# logout
+
+Log out from Microsoft 365
+
+## Usage
+
+```sh
+m365 logout [options]
+```
+
+## Options
+
+<Global />
+
+## Remarks
+
+The `logout` command logs out from Microsoft 365 and removes any access and refresh tokens from memory
+
+## Examples
+
+Log out from Microsoft 365
+
+```sh
+m365 logout
+```
+
+Log out from Microsoft 365 in debug mode including detailed debug information in the console output
+
+```sh
+m365 logout --debug
+```
+
+## Response
+
+The command won't return a response on success.