diff --git a/.gitignore b/.gitignore index 23fea0e..e78aadc 100644 --- a/.gitignore +++ b/.gitignore @@ -17,4 +17,5 @@ node_modules package-lock.json ZZBuild-Help.ps1 test1.ps1 -helpdoc.ps1 \ No newline at end of file +helpdoc.ps1 +StyleGuide.md \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 142d3ac..1579183 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Added Get-TkMsalToken cmdlet to retrieve an MSAL token using API calls. +- Added Managed Identity support for Get-TkMsalToken cmdlet (Needs to be tested). +- SecureString support for Get-TkMsalToken cmdlet. +- Formatting alignment for cmdlets. + +### Fixed + +- Fixed authentication context for MgGraph. + +### Changed + +- Updated private function names to be more descriptive. +- Removed MSAL.PS dependency from Send-TkEmailAppMessage function. +- Removed Send-TkEmailAppMessage module install if manual parameters are provided. + +## [0.2.0] - 2025-03-14 + +### Added + - Updated docs for the module. - Release Candidate - Update wiki pages. diff --git a/README.md b/README.md index 441d7b7..a715f76 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,6 @@ The **GraphAppToolkit** module provides a set of functions and classes to quickl - Microsoft.Graph - Microsoft.PowerShell.SecretManagement - SecretManagement.JustinGrote.CredMan -- MSAL.PS ### Requirements @@ -108,7 +107,7 @@ The following Private Functions support the module’s internal processes and ar - **Connect-TkMsService** - **ConvertTo-ParameterSplat** - **Initialize-TkAppAuthCertificate** -- **Initialize-TkAppSpRegistration** +- **New-TkAppSpOauth2Registration** - **Initialize-TkModuleEnv** - **Initialize-TkAppName** - **New-TkAppRegistration** @@ -266,9 +265,9 @@ Creates or retrieves a mail-enabled security group with a custom or default doma ### Syntax ```powershell -New-MailEnabledSendingGroup -Name [-Alias ] -PrimarySmtpAddress [-WhatIf] [-Confirm] [] +New-MailEnabledSendingGroup -Name [-Alias ] -PrimarySmtpAddress [-LogOutputPath ] [-WhatIf] [-Confirm] [] -New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain [-WhatIf] [-Confirm] [] +New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain [-LogOutputPath ] [-WhatIf] [-Confirm] [] @@ -279,8 +278,9 @@ New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain Name | | The name of the mail-enabled security group to create or retrieve. This is also used as the alias if no separate Alias parameter is provided. | true | false | | | Alias | | An optional alias for the group. If omitted, the group name is used as the alias. | false | false | | -| PrimarySmtpAddress | | \(CustomDomain parameter set\\) The full SMTP address for the group \(e.g. "MyGroup@contoso.com"\\). This parameter is mandatory when using the 'CustomDomain' parameter set. | true | false | | -| DefaultDomain | | \(DefaultDomain parameter set\\) The domain portion to be appended to the group alias \(e.g. "Alias@DefaultDomain"\\). This parameter is mandatory when using the 'DefaultDomain' parameter set. | true | false | | +| PrimarySmtpAddress | | \\(CustomDomain parameter set\) The full SMTP address for the group \\(e.g. "MyGroup@contoso.com"\). This parameter is mandatory when using the 'CustomDomain' parameter set. | true | false | | +| DefaultDomain | | \\(DefaultDomain parameter set\) The domain portion to be appended to the group alias \\(e.g. "Alias@DefaultDomain"\). This parameter is mandatory when using the 'DefaultDomain' parameter set. | true | false | | +| LogOutputPath | | An optional path to output the log file. If not provided, logs will not be written to a file. | false | false | | | WhatIf | wi | | false | false | | | Confirm | cf | | false | false | | ### Inputs @@ -290,7 +290,7 @@ New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain ] -AuthorizedSenderUserName -MailEnabledSendingGroup [-CertPrefix ] [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [] +Publish-TkEmailApp [-AppPrefix ] -AuthorizedSenderUserName -MailEnabledSendingGroup [-CertPrefix ] [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [-LogOutput ] [-WhatIf] [-Confirm] [] -Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [] +Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [-LogOutput ] [-WhatIf] [-Confirm] [] @@ -337,6 +337,9 @@ Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThum | OverwriteVaultSecret | | If specified, overwrite the vault secret if it already exists. | false | false | False | | ReturnParamSplat | | If specified, return the parameter splat for use in other functions. | false | false | False | | DoNotUseDomainSuffix | | Switch to add session domain suffix to the app name. | false | false | False | +| LogOutput | | If specified, log the output to the console. | false | false | | +| WhatIf | wi | | false | false | | +| Confirm | cf | | false | false | | ### Note This cmdlet requires that the user running the cmdlet have the necessary permissions to create the app and connect to Exchange Online. @@ -435,7 +438,7 @@ Publish-TkEmailApp @useExistingParams ## Publish-TkM365AuditApp ### Synopsis -Publishes \(creates\\) a new M365 Audit App registration in Entra ID \(Azure AD\\) with a specified certificate. +Publishes \\(creates\) a new M365 Audit App registration in Entra ID \\(Azure AD\) with a specified certificate. ### Syntax ```powershell @@ -448,9 +451,9 @@ Publish-TkM365AuditApp [[-AppPrefix] ] [[-CertThumbprint] ] [[-K ### Parameters | Name | Alias | Description | Required? | Pipeline Input | Default Value | | - | - | - | - | - | - | -| AppPrefix | | A short prefix \(2-4 alphanumeric characters\\) used to build the app name. Defaults to "Gtk" if not specified. Example app name: GraphToolKit-MSN-GraphApp-MyDomain-As-helpDesk | false | false | Gtk | +| AppPrefix | | A short prefix \\(2-4 alphanumeric characters\) used to build the app name. Defaults to "Gtk" if not specified. Example app name: GraphToolKit-MSN-GraphApp-MyDomain-As-helpDesk | false | false | Gtk | | CertThumbprint | | The thumbprint of an existing certificate in the current user's certificate store. If not provided, a new self-signed certificate is created. | false | false | | -| KeyExportPolicy | | Specifies whether the newly created certificate \(if no thumbprint is provided\\) is 'Exportable' or 'NonExportable'. Defaults to 'NonExportable'. | false | false | NonExportable | +| KeyExportPolicy | | Specifies whether the newly created certificate \\(if no thumbprint is provided\) is 'Exportable' or 'NonExportable'. Defaults to 'NonExportable'. | false | false | NonExportable | | VaultName | | The SecretManagement vault name in which to store the app credentials. Defaults to "M365AuditAppLocalStore" if not specified. | false | false | M365AuditAppLocalStore | | OverwriteVaultSecret | | If specified, overwrites an existing secret in the specified vault if it already exists. | false | false | False | | ReturnParamSplat | | If specified, returns a parameter splat string for use in other functions, instead of the default PSCustomObject containing the app details. | false | false | False | @@ -459,10 +462,10 @@ Publish-TkM365AuditApp [[-AppPrefix] ] [[-CertThumbprint] ] [[-K - None. This function does not accept pipeline input. ### Outputs - - By default, returns a PSCustomObject with details of the new app \(AppId, ObjectId, TenantId, certificate thumbprint, expiration, etc.\\). If -ReturnParamSplat is used, returns a parameter splat string. + - By default, returns a PSCustomObject with details of the new app \\(AppId, ObjectId, TenantId, certificate thumbprint, expiration, etc.\). If -ReturnParamSplat is used, returns a parameter splat string. ### Note -Requires the Microsoft.Graph and ExchangeOnlineManagement modules for app creation and role assignment. The user must have sufficient privileges to create and manage applications in Azure AD, and to assign roles. After creation, admin consent may be required for the assigned permissions. Permissions required for app registration: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All', 'RoleManagement.ReadWrite.Directory' Permissions granted to the app: \(Exchange Administrator and Global Reader Roles are also added to the service principal.\\) 'AppCatalog.ReadWrite.All', 'Channel.Delete.All', 'ChannelMember.ReadWrite.All', 'ChannelSettings.ReadWrite.All', 'Directory.Read.All', 'Group.ReadWrite.All', 'Organization.Read.All', 'Policy.Read.All', 'Domain.Read.All', 'TeamSettings.ReadWrite.All', 'User.Read.All', 'Sites.Read.All', 'Sites.FullControl.All', 'Exchange.ManageAsApp' +Requires the Microsoft.Graph and ExchangeOnlineManagement modules for app creation and role assignment. The user must have sufficient privileges to create and manage applications in Azure AD, and to assign roles. After creation, admin consent may be required for the assigned permissions. Permissions required for app registration: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All', 'RoleManagement.ReadWrite.Directory' Permissions granted to the app: \\(Exchange Administrator and Global Reader Roles are also added to the service principal.\) 'AppCatalog.ReadWrite.All', 'Channel.Delete.All', 'ChannelMember.ReadWrite.All', 'ChannelSettings.ReadWrite.All', 'Directory.Read.All', 'Group.ReadWrite.All', 'Organization.Read.All', 'Policy.Read.All', 'Domain.Read.All', 'TeamSettings.ReadWrite.All', 'User.Read.All', 'Sites.Read.All', 'Sites.FullControl.All', 'Exchange.ManageAsApp' ### Examples **EXAMPLE 1** @@ -475,7 +478,7 @@ the credentials in the default vault. ## Publish-TkMemPolicyManagerApp ### Synopsis -Publishes a new MEM \(Intune\\) Policy Manager App in Azure AD with read-only or read-write permissions. +Publishes a new MEM \\(Intune\) Policy Manager App in Azure AD with read-only or read-write permissions. ### Syntax ```powershell @@ -488,7 +491,7 @@ Publish-TkMemPolicyManagerApp [-AppPrefix] [[-CertThumbprint] ] ### Parameters | Name | Alias | Description | Required? | Pipeline Input | Default Value | | - | - | - | - | - | - | -| AppPrefix | | A 2-4 character prefix used to build the application name \(e.g., CORP, MSN\\). This helps uniquely identify the app in Azure AD. | true | false | | +| AppPrefix | | A 2-4 character prefix used to build the application name \\(e.g., CORP, MSN\). This helps uniquely identify the app in Azure AD. | true | false | | | CertThumbprint | | The thumbprint of an existing certificate in the current user's certificate store. If omitted, a new self-signed certificate is created. | false | false | | | KeyExportPolicy | | Specifies whether the newly created certificate is 'Exportable' or 'NonExportable'. Defaults to 'NonExportable' if not specified. | false | false | NonExportable | | VaultName | | The name of the SecretManagement vault in which to store the app credentials. Defaults to 'MemPolicyManagerLocalStore'. | false | false | MemPolicyManagerLocalStore | @@ -500,7 +503,7 @@ Publish-TkMemPolicyManagerApp [-AppPrefix] [[-CertThumbprint] ] - None. This function does not accept pipeline input. ### Outputs - - By default, returns a PSCustomObject \(TkMemPolicyManagerAppParams\\) with details of the newly created app \(AppId, certificate thumbprint, tenant ID, etc.\\). If -ReturnParamSplat is used, returns a parameter splat string. + - By default, returns a PSCustomObject \\(TkMemPolicyManagerAppParams\) with details of the newly created app \\(AppId, certificate thumbprint, tenant ID, etc.\). If -ReturnParamSplat is used, returns a parameter splat string. ### Note This function requires the Microsoft.Graph module for application creation and the user must have permissions in Azure AD to register and grant permissions to the application. After creation, admin consent may be needed to finalize the permission grants. Permissions required for app registration:: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All' Permissions required for read-only access: 'DeviceManagementConfiguration.Read.All', 'DeviceManagementApps.Read.All', 'DeviceManagementManagedDevices.Read.All', 'Policy.Read.ConditionalAccess', 'Policy.Read.All' Permissions required for read-write access: 'DeviceManagementConfiguration.ReadWrite.All', 'DeviceManagementApps.ReadWrite.All', 'DeviceManagementManagedDevices.ReadWrite.All', 'Policy.ReadWrite.ConditionalAccess', 'Policy.Read.All' @@ -531,20 +534,20 @@ Send-TkEmailAppMessage -AppId -TenantId -CertThumbprint AppName | | \\[Vault Parameter Set Only\\] The name of the pre-created Microsoft Graph Email App \(stored in GraphEmailAppLocalStore\\). Used only if the 'Vault' parameter set is chosen. The function retrieves the AppId, TenantId, and certificate thumbprint from the vault entry. | true | false | | -| AppId | | \\[Manual Parameter Set Only\\] The Azure AD application \(client\\) ID to use for sending the email. Must be used together with TenantId and CertThumbprint in the 'Manual' parameter set. | true | false | | -| TenantId | | \\[Manual Parameter Set Only\\] The Azure AD tenant ID \(GUID or domain name\\). Must be used together with AppId and CertThumbprint in the 'Manual' parameter set. | true | false | | -| CertThumbprint | | \\[Manual Parameter Set Only\\] The certificate thumbprint \(in Cert:\\CurrentUser\\My\\) used for authenticating as the Azure AD app. Must be used together with AppId and TenantId in the 'Manual' parameter set. | true | false | | +| AppName | | \[Vault Parameter Set Only\\] The name of the pre-created Microsoft Graph Email App \\(stored in GraphEmailAppLocalStore\). Used only if the 'Vault' parameter set is chosen. The function retrieves the AppId, TenantId, and certificate thumbprint from the vault entry. | true | false | | +| AppId | | \[Manual Parameter Set Only\\] The Azure AD application \\(client\) ID to use for sending the email. Must be used together with TenantId and CertThumbprint in the 'Manual' parameter set. | true | false | | +| TenantId | | \[Manual Parameter Set Only\\] The Azure AD tenant ID \\(GUID or domain name\). Must be used together with AppId and CertThumbprint in the 'Manual' parameter set. | true | false | | +| CertThumbprint | | \[Manual Parameter Set Only\\] The certificate thumbprint \\(in Cert:\\CurrentUser\\My\) used for authenticating as the Azure AD app. Must be used together with AppId and TenantId in the 'Manual' parameter set. | true | false | | | To | | The email address of the recipient. | true | false | | | FromAddress | | The email address of the sender who is authorized to send email as configured in the Graph Email App. | true | false | | | Subject | | The subject line of the email. | true | false | | | EmailBody | | The body text of the email. | true | false | | | AttachmentPath | | An array of file paths for any attachments to include in the email. Each path must exist as a leaf file. | false | false | | -| VaultName | | \\[Vault Parameter Set Only\\] The name of the vault to retrieve the GraphEmailApp object. Default is 'GraphEmailAppLocalStore'. | false | false | GraphEmailAppLocalStore | +| VaultName | | \[Vault Parameter Set Only\\] The name of the vault to retrieve the GraphEmailApp object. Default is 'GraphEmailAppLocalStore'. | false | false | GraphEmailAppLocalStore | | WhatIf | wi | | false | false | | | Confirm | cf | | false | false | | ### Note -- This function requires the Microsoft.Graph, SecretManagement, SecretManagement.JustinGrote.CredMan, and MSAL.PS modules to be installed \(handled automatically via Initialize-TkModuleEnv\\). - For the 'Vault' parameter set, the local vault secret must store JSON properties including AppId, TenantID, and CertThumbprint. - Refer to https://learn.microsoft.com/en-us/graph/outlook-send-mail for details on sending mail via Microsoft Graph. +- This function requires the Microsoft.Graph, SecretManagement, SecretManagement.JustinGrote.CredMan, and MSAL.PS modules to be installed \\(handled automatically via Initialize-TkModuleEnv\). - For the 'Vault' parameter set, the local vault secret must store JSON properties including AppId, TenantID, and CertThumbprint. - Refer to https://learn.microsoft.com/en-us/graph/outlook-send-mail for details on sending mail via Microsoft Graph. ### Examples **EXAMPLE 1** diff --git a/README2.md b/README2.md index 22ee117..0eaf606 100644 --- a/README2.md +++ b/README2.md @@ -5,9 +5,9 @@ Creates or retrieves a mail-enabled security group with a custom or default doma ### Syntax ```powershell -New-MailEnabledSendingGroup -Name [-Alias ] -PrimarySmtpAddress [-WhatIf] [-Confirm] [] +New-MailEnabledSendingGroup -Name [-Alias ] -PrimarySmtpAddress [-LogOutputPath ] [-WhatIf] [-Confirm] [] -New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain [-WhatIf] [-Confirm] [] +New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain [-LogOutputPath ] [-WhatIf] [-Confirm] [] @@ -18,8 +18,9 @@ New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain Name | | The name of the mail-enabled security group to create or retrieve. This is also used as the alias if no separate Alias parameter is provided. | true | false | | | Alias | | An optional alias for the group. If omitted, the group name is used as the alias. | false | false | | -| PrimarySmtpAddress | | \(CustomDomain parameter set\\) The full SMTP address for the group \(e.g. "MyGroup@contoso.com"\\). This parameter is mandatory when using the 'CustomDomain' parameter set. | true | false | | -| DefaultDomain | | \(DefaultDomain parameter set\\) The domain portion to be appended to the group alias \(e.g. "Alias@DefaultDomain"\\). This parameter is mandatory when using the 'DefaultDomain' parameter set. | true | false | | +| PrimarySmtpAddress | | \\(CustomDomain parameter set\) The full SMTP address for the group \\(e.g. "MyGroup@contoso.com"\). This parameter is mandatory when using the 'CustomDomain' parameter set. | true | false | | +| DefaultDomain | | \\(DefaultDomain parameter set\) The domain portion to be appended to the group alias \\(e.g. "Alias@DefaultDomain"\). This parameter is mandatory when using the 'DefaultDomain' parameter set. | true | false | | +| LogOutputPath | | An optional path to output the log file. If not provided, logs will not be written to a file. | false | false | | | WhatIf | wi | | false | false | | | Confirm | cf | | false | false | | ### Inputs @@ -29,7 +30,7 @@ New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain ] -AuthorizedSenderUserName -MailEnabledSendingGroup [-CertPrefix ] [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [] +Publish-TkEmailApp [-AppPrefix ] -AuthorizedSenderUserName -MailEnabledSendingGroup [-CertPrefix ] [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [-LogOutput ] [-WhatIf] [-Confirm] [] -Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [] +Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [-LogOutput ] [-WhatIf] [-Confirm] [] @@ -76,6 +77,9 @@ Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThum | OverwriteVaultSecret | | If specified, overwrite the vault secret if it already exists. | false | false | False | | ReturnParamSplat | | If specified, return the parameter splat for use in other functions. | false | false | False | | DoNotUseDomainSuffix | | Switch to add session domain suffix to the app name. | false | false | False | +| LogOutput | | If specified, log the output to the console. | false | false | | +| WhatIf | wi | | false | false | | +| Confirm | cf | | false | false | | ### Note This cmdlet requires that the user running the cmdlet have the necessary permissions to create the app and connect to Exchange Online. @@ -174,7 +178,7 @@ Publish-TkEmailApp @useExistingParams ## Publish-TkM365AuditApp ### Synopsis -Publishes \(creates\\) a new M365 Audit App registration in Entra ID \(Azure AD\\) with a specified certificate. +Publishes \\(creates\) a new M365 Audit App registration in Entra ID \\(Azure AD\) with a specified certificate. ### Syntax ```powershell @@ -187,9 +191,9 @@ Publish-TkM365AuditApp [[-AppPrefix] ] [[-CertThumbprint] ] [[-K ### Parameters | Name | Alias | Description | Required? | Pipeline Input | Default Value | | - | - | - | - | - | - | -| AppPrefix | | A short prefix \(2-4 alphanumeric characters\\) used to build the app name. Defaults to "Gtk" if not specified. Example app name: GraphToolKit-MSN-GraphApp-MyDomain-As-helpDesk | false | false | Gtk | +| AppPrefix | | A short prefix \\(2-4 alphanumeric characters\) used to build the app name. Defaults to "Gtk" if not specified. Example app name: GraphToolKit-MSN-GraphApp-MyDomain-As-helpDesk | false | false | Gtk | | CertThumbprint | | The thumbprint of an existing certificate in the current user's certificate store. If not provided, a new self-signed certificate is created. | false | false | | -| KeyExportPolicy | | Specifies whether the newly created certificate \(if no thumbprint is provided\\) is 'Exportable' or 'NonExportable'. Defaults to 'NonExportable'. | false | false | NonExportable | +| KeyExportPolicy | | Specifies whether the newly created certificate \\(if no thumbprint is provided\) is 'Exportable' or 'NonExportable'. Defaults to 'NonExportable'. | false | false | NonExportable | | VaultName | | The SecretManagement vault name in which to store the app credentials. Defaults to "M365AuditAppLocalStore" if not specified. | false | false | M365AuditAppLocalStore | | OverwriteVaultSecret | | If specified, overwrites an existing secret in the specified vault if it already exists. | false | false | False | | ReturnParamSplat | | If specified, returns a parameter splat string for use in other functions, instead of the default PSCustomObject containing the app details. | false | false | False | @@ -198,10 +202,10 @@ Publish-TkM365AuditApp [[-AppPrefix] ] [[-CertThumbprint] ] [[-K - None. This function does not accept pipeline input. ### Outputs - - By default, returns a PSCustomObject with details of the new app \(AppId, ObjectId, TenantId, certificate thumbprint, expiration, etc.\\). If -ReturnParamSplat is used, returns a parameter splat string. + - By default, returns a PSCustomObject with details of the new app \\(AppId, ObjectId, TenantId, certificate thumbprint, expiration, etc.\). If -ReturnParamSplat is used, returns a parameter splat string. ### Note -Requires the Microsoft.Graph and ExchangeOnlineManagement modules for app creation and role assignment. The user must have sufficient privileges to create and manage applications in Azure AD, and to assign roles. After creation, admin consent may be required for the assigned permissions. Permissions required for app registration: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All', 'RoleManagement.ReadWrite.Directory' Permissions granted to the app: \(Exchange Administrator and Global Reader Roles are also added to the service principal.\\) 'AppCatalog.ReadWrite.All', 'Channel.Delete.All', 'ChannelMember.ReadWrite.All', 'ChannelSettings.ReadWrite.All', 'Directory.Read.All', 'Group.ReadWrite.All', 'Organization.Read.All', 'Policy.Read.All', 'Domain.Read.All', 'TeamSettings.ReadWrite.All', 'User.Read.All', 'Sites.Read.All', 'Sites.FullControl.All', 'Exchange.ManageAsApp' +Requires the Microsoft.Graph and ExchangeOnlineManagement modules for app creation and role assignment. The user must have sufficient privileges to create and manage applications in Azure AD, and to assign roles. After creation, admin consent may be required for the assigned permissions. Permissions required for app registration: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All', 'RoleManagement.ReadWrite.Directory' Permissions granted to the app: \\(Exchange Administrator and Global Reader Roles are also added to the service principal.\) 'AppCatalog.ReadWrite.All', 'Channel.Delete.All', 'ChannelMember.ReadWrite.All', 'ChannelSettings.ReadWrite.All', 'Directory.Read.All', 'Group.ReadWrite.All', 'Organization.Read.All', 'Policy.Read.All', 'Domain.Read.All', 'TeamSettings.ReadWrite.All', 'User.Read.All', 'Sites.Read.All', 'Sites.FullControl.All', 'Exchange.ManageAsApp' ### Examples **EXAMPLE 1** @@ -214,7 +218,7 @@ the credentials in the default vault. ## Publish-TkMemPolicyManagerApp ### Synopsis -Publishes a new MEM \(Intune\\) Policy Manager App in Azure AD with read-only or read-write permissions. +Publishes a new MEM \\(Intune\) Policy Manager App in Azure AD with read-only or read-write permissions. ### Syntax ```powershell @@ -227,7 +231,7 @@ Publish-TkMemPolicyManagerApp [-AppPrefix] [[-CertThumbprint] ] ### Parameters | Name | Alias | Description | Required? | Pipeline Input | Default Value | | - | - | - | - | - | - | -| AppPrefix | | A 2-4 character prefix used to build the application name \(e.g., CORP, MSN\\). This helps uniquely identify the app in Azure AD. | true | false | | +| AppPrefix | | A 2-4 character prefix used to build the application name \\(e.g., CORP, MSN\). This helps uniquely identify the app in Azure AD. | true | false | | | CertThumbprint | | The thumbprint of an existing certificate in the current user's certificate store. If omitted, a new self-signed certificate is created. | false | false | | | KeyExportPolicy | | Specifies whether the newly created certificate is 'Exportable' or 'NonExportable'. Defaults to 'NonExportable' if not specified. | false | false | NonExportable | | VaultName | | The name of the SecretManagement vault in which to store the app credentials. Defaults to 'MemPolicyManagerLocalStore'. | false | false | MemPolicyManagerLocalStore | @@ -239,7 +243,7 @@ Publish-TkMemPolicyManagerApp [-AppPrefix] [[-CertThumbprint] ] - None. This function does not accept pipeline input. ### Outputs - - By default, returns a PSCustomObject \(TkMemPolicyManagerAppParams\\) with details of the newly created app \(AppId, certificate thumbprint, tenant ID, etc.\\). If -ReturnParamSplat is used, returns a parameter splat string. + - By default, returns a PSCustomObject \\(TkMemPolicyManagerAppParams\) with details of the newly created app \\(AppId, certificate thumbprint, tenant ID, etc.\). If -ReturnParamSplat is used, returns a parameter splat string. ### Note This function requires the Microsoft.Graph module for application creation and the user must have permissions in Azure AD to register and grant permissions to the application. After creation, admin consent may be needed to finalize the permission grants. Permissions required for app registration:: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All' Permissions required for read-only access: 'DeviceManagementConfiguration.Read.All', 'DeviceManagementApps.Read.All', 'DeviceManagementManagedDevices.Read.All', 'Policy.Read.ConditionalAccess', 'Policy.Read.All' Permissions required for read-write access: 'DeviceManagementConfiguration.ReadWrite.All', 'DeviceManagementApps.ReadWrite.All', 'DeviceManagementManagedDevices.ReadWrite.All', 'Policy.ReadWrite.ConditionalAccess', 'Policy.Read.All' @@ -270,20 +274,20 @@ Send-TkEmailAppMessage -AppId -TenantId -CertThumbprint AppName | | \\[Vault Parameter Set Only\\] The name of the pre-created Microsoft Graph Email App \(stored in GraphEmailAppLocalStore\\). Used only if the 'Vault' parameter set is chosen. The function retrieves the AppId, TenantId, and certificate thumbprint from the vault entry. | true | false | | -| AppId | | \\[Manual Parameter Set Only\\] The Azure AD application \(client\\) ID to use for sending the email. Must be used together with TenantId and CertThumbprint in the 'Manual' parameter set. | true | false | | -| TenantId | | \\[Manual Parameter Set Only\\] The Azure AD tenant ID \(GUID or domain name\\). Must be used together with AppId and CertThumbprint in the 'Manual' parameter set. | true | false | | -| CertThumbprint | | \\[Manual Parameter Set Only\\] The certificate thumbprint \(in Cert:\\CurrentUser\\My\\) used for authenticating as the Azure AD app. Must be used together with AppId and TenantId in the 'Manual' parameter set. | true | false | | +| AppName | | \[Vault Parameter Set Only\\] The name of the pre-created Microsoft Graph Email App \\(stored in GraphEmailAppLocalStore\). Used only if the 'Vault' parameter set is chosen. The function retrieves the AppId, TenantId, and certificate thumbprint from the vault entry. | true | false | | +| AppId | | \[Manual Parameter Set Only\\] The Azure AD application \\(client\) ID to use for sending the email. Must be used together with TenantId and CertThumbprint in the 'Manual' parameter set. | true | false | | +| TenantId | | \[Manual Parameter Set Only\\] The Azure AD tenant ID \\(GUID or domain name\). Must be used together with AppId and CertThumbprint in the 'Manual' parameter set. | true | false | | +| CertThumbprint | | \[Manual Parameter Set Only\\] The certificate thumbprint \\(in Cert:\\CurrentUser\\My\) used for authenticating as the Azure AD app. Must be used together with AppId and TenantId in the 'Manual' parameter set. | true | false | | | To | | The email address of the recipient. | true | false | | | FromAddress | | The email address of the sender who is authorized to send email as configured in the Graph Email App. | true | false | | | Subject | | The subject line of the email. | true | false | | | EmailBody | | The body text of the email. | true | false | | | AttachmentPath | | An array of file paths for any attachments to include in the email. Each path must exist as a leaf file. | false | false | | -| VaultName | | \\[Vault Parameter Set Only\\] The name of the vault to retrieve the GraphEmailApp object. Default is 'GraphEmailAppLocalStore'. | false | false | GraphEmailAppLocalStore | +| VaultName | | \[Vault Parameter Set Only\\] The name of the vault to retrieve the GraphEmailApp object. Default is 'GraphEmailAppLocalStore'. | false | false | GraphEmailAppLocalStore | | WhatIf | wi | | false | false | | | Confirm | cf | | false | false | | ### Note -- This function requires the Microsoft.Graph, SecretManagement, SecretManagement.JustinGrote.CredMan, and MSAL.PS modules to be installed \(handled automatically via Initialize-TkModuleEnv\\). - For the 'Vault' parameter set, the local vault secret must store JSON properties including AppId, TenantID, and CertThumbprint. - Refer to https://learn.microsoft.com/en-us/graph/outlook-send-mail for details on sending mail via Microsoft Graph. +- This function requires the Microsoft.Graph, SecretManagement, SecretManagement.JustinGrote.CredMan, and MSAL.PS modules to be installed \\(handled automatically via Initialize-TkModuleEnv\). - For the 'Vault' parameter set, the local vault secret must store JSON properties including AppId, TenantID, and CertThumbprint. - Refer to https://learn.microsoft.com/en-us/graph/outlook-send-mail for details on sending mail via Microsoft Graph. ### Examples **EXAMPLE 1** diff --git a/docs/index.html b/docs/index.html index 49154fe..c431dd0 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2,7 +2,7 @@