Merge pull request #3488 from andikrueger/Documentation-Update-M365DS…

…CAzureADApp documentation Update-M365DSCAzureAdApp #3487
microsoft · Jul 26, 2023 · 221c8b9 · 221c8b9
2 parents 046d658 + 9dbebb4
commit 221c8b9
Show file tree

Hide file tree

Showing 3 changed files with 111 additions and 18 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -115,7 +115,7 @@
     FIXES #3417
   * Update-M365DSCModule now forces a reload of the latest version of the Microsoft365DSC module.
     FIXES [#3326](https://github.com/microsoft/Microsoft365DSC/issues/3326)
-  * Update-M365DSCAyureADApplication
+  * Update-M365DSCAzureADApplication
     Added retry logic to catch the "Key credential end date is invalid" error when updating the application certificate.
     FIXES [#3426](https://github.com/microsoft/Microsoft365DSC/issues/3426)
 * DEPENDENCIES

diff --git a/Modules/Microsoft365DSC/Modules/M365DSCPermissions.psm1 b/Modules/Microsoft365DSC/Modules/M365DSCPermissions.psm1
@@ -1191,6 +1191,19 @@ This application can then be used for Application Authentication.
 The provided permissions have to be as an array of hashtables, with Api=Graph, SharePoint
 or Exchange and PermissionsName set to a list of permissions. See examples for more information.
 
+NOTE:
+Please make sure you have the following permissions for the 'Microsoft Graph Command Line Tools'
+Enterprise Application in your tenant:
+
+- Application.ReadWrite.All
+
+You can add this scope to the 'Microsoft Graph Command Line Tools' Enterprise Application by running
+the following command:
+
+```powershell
+Connect-MgGraph -Scopes 'Application.ReadWrite.All'
+```
+
 NOTE:
 If consent cannot be given for whatever reason, make sure all these permissions are
 given Admin Consent by browsing to the App Registration in Azure AD > API Permissions
@@ -1205,15 +1218,70 @@ If you want to configure App-Only permission for Exchange, as described here:
 https://docs.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-2-assign-api-permissions-to-the-application
 Using the following permission will achieve exactly that: @{Api='Exchange';PermissionsName='Exchange.ManageAsApp'}
 
+Note 2:
+If you want to configure App-Only permission for Security and compliance, please refer to this information on how to setup the permissions:
+https://microsoft365dsc.com/user-guide/get-started/authentication-and-permissions/#security-and-compliance-center-permissions
+
+Note 3:
+If you want to configure App-Only permission for Power Platform, please refer to this information on how to setup the permissions:
+https://microsoft365dsc.com/user-guide/get-started/authentication-and-permissions/#power-apps-permissions
+
+
+.Parameter ApplicationName
+The name of the application to create or update. Default value is 'Microsoft365DSC'.
+
+.Parameter Permissions
+The permissions to assign to the application. This has to be an array of hashtables, with Api=Graph, SharePoint or Exchange and PermissionsName set to a list of permissions. See examples for more information.
+
+.Parameter Type
+The type of credential to create. Default value is 'Secret'. Valid values are 'Secret' and 'Certificate'.
+
+.Parameter MonthsValid
+The number of months the certificate should be valid. Default value is 12.
+
+.Parameter CreateNewSecret
+If specified, a new secret will be created for the application. -CreateNewSecret or -CertificatePath can be used, not both.
+
+.Parameter CertificatePath
+The path to the certificate to be uploaded for the app registration. If using with -CreateSelfSignedCertificate - a file with this name will be created and uploaded (file must not exist). Otherwise the file must already exist. Cannot be used with -CreateNewSecret simultaneously.
+
+.Parameter CreateSelfSignedCertificate
+If specified, a self-signed certificate will be created for the application. -CreateSelfSignedCertificate or -CertificatePath can be used, not both.
+
+.Parameter AdminConsent
+If specified, admin consent will be granted for the application.
+
+.Parameter Credential
+The credential to use for authenticating the request. Mutually exclusive with -TenantId.
+
+.Parameter ApplicationId
+The ApplicationId to use for authenticating the request. -Credential or -ApplicationId can be used, not both.
+
+.Parameter TenantId
+The name of the tenant to use for the request. Must be in the form of contoso.onmicrosoft.com. Mutually exclusive with -Credential.
+
+.Parameter ApplicationSecret
+The ApplicationSecret to use for authenticating the request. -Credential or -ApplicationSecret can be used, not both.
+
+.Parameter CertificateThumbprint
+Thumbprint of an existing auth certificate to use for authenticating the request. Mutually exclusive with -Credential.
+
+.Parameter ManagedIdentity
+If specified, Managed Identity will be used for authenticating the request. -Credential or -ApplicationId or -ManagedIdentity can be used, only one of them.
+
 .Example
 Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions @(@{Api='SharePoint';PermissionName='Sites.FullControl.All'}) -AdminConsent -Type Secret -Credential $creds
 
-.Example
+.EXAMPLE
 Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions @(@{Api='Graph';PermissionName='Domain.Read.All'}) -AdminConsent  -Credential $creds -Type Certificate -CreateSelfSignedCertificate -CertificatePath c:\Temp\M365DSC.cer
 
-.Example
+.EXAMPLE
 Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions @(@{Api='SharePoint';PermissionName='Sites.FullControl.All'},@{Api='Graph';PermissionName='Group.ReadWrite.All'},@{Api='Exchange';PermissionName='Exchange.ManageAsApp'}) -AdminConsent -Credential $creds -Type Certificate -CertificatePath c:\Temp\M365DSC.cer
 
+.EXAMPLE
+Update-M365DSCAzureAdApplication -ApplicationName $Microsoft365DSC -Permissions $(Get-M365DSCCompiledPermissionList -ResourceNameList Get-M365DSCAllResources -PermissionType Application -AccessType Read) -Type Certificate -CreateSelfSignedCertificate -AdminConsent -MonthsValid 12 -Credential $creds -CertificatePath c:\Temp\M365DSC.cer
+
+
 .Functionality
 Public
 #>

diff --git a/docs/docs/user-guide/cmdlets/Update-M365DSCAzureAdApplication.md b/docs/docs/user-guide/cmdlets/Update-M365DSCAzureAdApplication.md
@@ -10,6 +10,19 @@ This application can then be used for Application Authentication.
 The provided permissions have to be as an array of hashtables, with Api=Graph, SharePoint
 or Exchange and PermissionsName set to a list of permissions. See examples for more information.
 
+NOTE:
+Please make sure you have the following permissions for the 'Microsoft Graph Command Line Tools'
+Enterprise Application in your tenant:
+
+- Application.ReadWrite.All
+
+You can add this scope to the 'Microsoft Graph Command Line Tools' Enterprise Application by running
+the following command:
+
+```powershell
+Connect-MgGraph -Scopes 'Application.ReadWrite.All'
+```
+
 NOTE:
 If consent cannot be given for whatever reason, make sure all these permissions are
 given Admin Consent by browsing to the App Registration in Azure AD > API Permissions
@@ -24,6 +37,14 @@ If you want to configure App-Only permission for Exchange, as described here:
 https://docs.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-2-assign-api-permissions-to-the-application
 Using the following permission will achieve exactly that: @{Api='Exchange';PermissionsName='Exchange.ManageAsApp'}
 
+Note 2:
+If you want to configure App-Only permission for Security and compliance, please refer to this information on how to setup the permissions:
+https://microsoft365dsc.com/user-guide/get-started/authentication-and-permissions/#security-and-compliance-center-permissions
+
+Note 3:
+If you want to configure App-Only permission for Power Platform, please refer to this information on how to setup the permissions:
+https://microsoft365dsc.com/user-guide/get-started/authentication-and-permissions/#power-apps-permissions
+
 ## Output
 
 This function does not generate any output.
@@ -32,22 +53,22 @@ This function does not generate any output.
 
 | Parameter | Required | DataType | Default Value | Allowed Values | Description |
 | --- | --- | --- | --- | --- | --- |
-| ApplicationName | False | String | Microsoft365DSC |  |  |
-| Permissions | True True | Hashtable[] |  |  |  |
-| Type | False | String | Secret | Secret, Certificate |  |
-| MonthsValid | False | Int32 | 12 |  |  |
-| CreateNewSecret | False | SwitchParameter |  |  |  |
-| CertificatePath | False | String |  |  |  |
-| CreateSelfSignedCertificate | False | SwitchParameter |  |  |  |
-| AdminConsent | False | SwitchParameter |  |  |  |
-| Credential | False | PSCredential |  |  |  |
-| ApplicationId | False | String |  |  |  |
-| TenantId | False | String |  |  |  |
-| ApplicationSecret | False | PSCredential |  |  |  |
-| CertificateThumbprint | False | String |  |  |  |
-| ManagedIdentity | False | SwitchParameter |  |  |  |
+| ApplicationName | False | String | Microsoft365DSC |  | The name of the application to create or update. Default value is 'Microsoft365DSC'. |
+| Permissions | True True | Hashtable[] |  |  | The permissions to assign to the application. This has to be an array of hashtables, with Api=Graph, SharePoint or Exchange and PermissionsName set to a list of permissions. See examples for more information. |
+| Type | False | String | Secret | Secret, Certificate | The type of credential to create. Default value is 'Secret'. Valid values are 'Secret' and 'Certificate'. |
+| MonthsValid | False | Int32 | 12 |  | The number of months the certificate should be valid. Default value is 12. |
+| CreateNewSecret | False | SwitchParameter |  |  | If specified, a new secret will be created for the application. -CreateNewSecret or -CertificatePath can be used, not both. |
+| CertificatePath | False | String |  |  | The path to the certificate to use for the application. -CreateNewSecret or -CertificatePath can be used, not both. |
+| CreateSelfSignedCertificate | False | SwitchParameter |  |  | If specified, a self-signed certificate will be created for the application. -CreateSelfSignedCertificate or -CertificatePath can be used, not both. |
+| AdminConsent | False | SwitchParameter |  |  | If specified, admin consent will be granted for the application. |
+| Credential | False | PSCredential |  |  | The credential to use for authenticating the request. |
+| ApplicationId | False | String |  |  | The ApplicationId to use for authenticating the request. -Credential or -ApplicationId can be used, not both. |
+| TenantId | False | String |  |  | The TenantId to use for the request. The TenantId needs to be in the form of contoso.onmicrosoft.com. -Credential or -TenantId can be used, not both. |
+| ApplicationSecret | False | PSCredential |  |  | The ApplicationSecret to use for authenticating the request. -Credential or -ApplicationSecret can be used, not both. |
+| CertificateThumbprint | False | String |  |  | The CertificateThumbprint to use for authenticating the request. -Credential or -CertificateThumbprint can be used, not both. |
+| ManagedIdentity | False | SwitchParameter |  |  | If specified, Managed Identity will be used for authenticating the request. -Credential or -ApplicationId or -ManagedIdentity can be used, only one of them. |
 | Message | True | String |  |  |  |
-| Type | False | String | Info | Error, Warning, Info |  |
+| Type | False | String | Info | Error, Warning, Info | The type of credential to create. Default value is 'Secret'. Valid values are 'Secret' and 'Certificate'. |
 
 ## Examples
 
@@ -63,4 +84,8 @@ This function does not generate any output.
 
 `Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions @(@{Api='SharePoint';PermissionName='Sites.FullControl.All'},@{Api='Graph';PermissionName='Group.ReadWrite.All'},@{Api='Exchange';PermissionName='Exchange.ManageAsApp'}) -AdminConsent -Credential $creds -Type Certificate -CertificatePath c:\Temp\M365DSC.cer`
 
+-------------------------- EXAMPLE 4 --------------------------
+
+`Update-M365DSCAzureAdApplication -ApplicationName $Microsoft365DSC -Permissions $(Get-M365DSCCompiledPermissionList -ResourceNameList Get-M365DSCAllResources -PermissionType Application -AccessType Read) -Type Certificate -CreateSelfSignedCertificate -AdminConsent -MonthsValid 12 -Credential $creds -CertificatePath c:\Temp\M365DSC.cer`
+