Update-M365DSCAzureAdApplication

Description

This function creates or updates an application in Azure AD. It assigns permissions, grants consent and creates a secret or uploads a certificate to the application.

This application can then be used for Application Authentication.

With Type set to ManagedIdentity, the function assigns the permissions to an existing managed identity instead. It creates no application, grants no consent and creates no credential.

The provided permissions have to be as an array of hashtables, with Api set to the name of the API owning the permission and PermissionName set to the permission itself. The Api value is any API name a resource settings file uses, such as 'Office 365 Exchange Online' or 'Azure Service Management', one of the Microsoft365DSC aliases 'Graph', 'SharePoint' and 'Exchange', or an application id. 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:

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 and clicking the "Grant admin consent for " button.

More information: Graph API permissions: https://docs.microsoft.com/en-us/graph/permissions-reference Exchange permissions: https://docs.microsoft.com/en-us/exchange/permissions-exo/permissions-exo

Note: 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.

Parameters

Parameter	Required	DataType	Default Value	Allowed Values	Description
ApplicationName	False	String	Microsoft365DSC		Specifies the application display name. With Type set to ManagedIdentity, specifies the display name, object id or client id of the managed identity.
Permissions	True True	Hashtable[]			Specifies permission definitions to assign.
Type	False	String	Secret	Secret, Certificate, ManagedIdentity	Specifies whether the app should use a secret or certificate credential, or whether the permissions are assigned to an existing managed identity.
MonthsValid	False	Int32	12		Specifies the validity period in months for newly created credentials.
CreateNewSecret	False	SwitchParameter			Indicates that a new secret should be created when using secret mode.
CertificatePath	False	String			Specifies the certificate file path to upload or create.
CreateSelfSignedCertificate	False	SwitchParameter			If specified, a self-signed certificate will be created for the application. Once specified, -CertificatePath is required as well. The certificate is create in the Cert:\CurrentUser\My store and will be exported to the path specified in -CertificatePath. If you require the certificate with the private key, you can export it from the certificate store after running the command using the Export-PfxCertificate cmdlet.
AdminConsent	False	SwitchParameter			Indicates that admin consent flow should be executed.
Credential	False	PSCredential			Specifies delegated credentials used for interactive operations.
ApplicationId	False	String			Specifies the application id used for app-based authentication.
TenantId	False	String			Specifies the tenant id or tenant domain used for authentication.
ApplicationSecret	False	PSCredential			Specifies the application secret used for app-based authentication.
CertificateThumbprint	False	String			Specifies the certificate thumbprint used for app-based authentication.
ManagedIdentity	False	SwitchParameter			Indicates that managed identity authentication should be used.
Message	True	String
Type	False	String	Info	Error, Warning, Info	Specifies whether the app should use a secret or certificate credential, or whether the permissions are assigned to an existing managed identity.

Examples

-------------------------- EXAMPLE 1 --------------------------

$creds = Get-Credential PS> Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions @(@{Api='SharePoint';PermissionName='Sites.FullControl.All'}) -AdminConsent -Type Secret -Credential $creds

-------------------------- EXAMPLE 2 --------------------------

$creds = Get-Credential PS> Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions @(@{Api='Graph';PermissionName='Domain.Read.All'}) -AdminConsent -Credential $creds -Type Certificate -CreateSelfSignedCertificate -CertificatePath c:\Temp\M365DSC.cer

-------------------------- EXAMPLE 3 --------------------------

$creds = Get-Credential PS> 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 --------------------------

$creds = Get-Credential PS> Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions $((Get-M365DSCCompiledPermissionList -ResourceNameList (Get-M365DSCAllResources) -PermissionType Application -AccessType Read).Permissions) -Type Certificate -CreateSelfSignedCertificate -AdminConsent -MonthsValid 12 -Credential $creds -CertificatePath c:\Temp\M365DSC.cer

-------------------------- EXAMPLE 5 --------------------------

$creds = Get-Credential PS> Update-M365DSCAzureAdApplication -ApplicationName 'm365dsc-automation' -Permissions @(@{Api='Graph';PermissionName='Group.ReadWrite.All'},@{Api='Exchange';PermissionName='Exchange.ManageAsApp'}) -Type ManagedIdentity -Credential $creds