diff --git a/.gitignore b/.gitignore index e78aadc..a6be20d 100644 --- a/.gitignore +++ b/.gitignore @@ -18,4 +18,6 @@ package-lock.json ZZBuild-Help.ps1 test1.ps1 helpdoc.ps1 -StyleGuide.md \ No newline at end of file +StyleGuide.md +.copilot/ +samplescript.ps1 diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..7ba8a5e --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,16 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "PowerShell: Launch Current File", + "type": "PowerShell", + "request": "launch", + "script": "${file}", + "args": [], + "createTemporaryIntegratedConsole": true + } + ] +} \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 1579183..3e980fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- Fixed module installation logic to correctly register the module after build and import. +- Fixed parameter handling in module manifest and public functions for better consistency. +- Fixed minimum PowerShell version declaration and validation during install. +- Minor internal refactor related to domain-suffix optional parameter handling. + +### Changed + +- Made the domain suffix optional during app name initialization for greater flexibility in tenant naming conventions. + +## [0.2.1] - 2025-03-17 + ### Added - Added Get-TkMsalToken cmdlet to retrieve an MSAL token using API calls. diff --git a/Cmdlets_Mapping.csv b/Cmdlets_Mapping.csv new file mode 100644 index 0000000..ba8ead6 --- /dev/null +++ b/Cmdlets_Mapping.csv @@ -0,0 +1,29 @@ +Function Name,Visibility,Used Cmdlets +Connect-TkMsService,Private,"Get-MgUser, Get-MgContext, Get-MgOrganization, Remove-MgContext, Connect-MgGraph, Disconnect-ExchangeOnline, Connect-ExchangeOnline" +ConvertTo-ParameterSplat,Private,Write-AuditLog +Get-TkExistingCert,Private,"Get-ChildItem, Where-Object, Remove-Item, Write-AuditLog" +Get-TkExistingSecret,Private,"Get-Secret, Write-AuditLog" +Get-TkMsalToken,Private,"Invoke-RestMethod, Write-AuditLog" +Initialize-TkAppAuthCertificate,Private,"Get-ChildItem, New-SelfSignedCertificate, Write-AuditLog" +Initialize-TkAppName,Private,Write-AuditLog +Initialize-TkEmailAppParamsObject,Private, +Initialize-TkM365AuditAppParamsObject,Private, +Initialize-TkMemPolicyManagerAppParamsObject,Private, +Initialize-TkModuleEnv,Private,"Install-Module, Import-Module, Get-Module, Write-AuditLog" +Initialize-TkRequiredResourcePermissionObject,Private,"Get-MgServicePrincipal, Find-MgGraphPermission, Write-AuditLog" +New-TkAppRegistration,Private,"Get-ChildItem, New-MgApplication, Write-AuditLog" +New-TkAppSpOauth2Registration,Private,Write-AuditLog +Connect-TkMsService,Private,"Get-MgUser, Get-MgContext, Get-MgOrganization, Remove-MgContext, Connect-MgGraph, Disconnect-ExchangeOnline, Connect-ExchangeOnline" +ConvertTo-ParameterSplat,Private,Write-AuditLog +Get-TkExistingCert,Public,"Get-ChildItem, Where-Object, Remove-Item, Write-AuditLog" +Get-TkExistingSecret,Public,"Get-Secret, Write-AuditLog" +Get-TkMsalToken,Public,"Invoke-RestMethod, Write-AuditLog" +Initialize-TkAppAuthCertificate,Public,"Get-ChildItem, New-SelfSignedCertificate, Write-AuditLog" +Initialize-TkAppName,Public,Write-AuditLog +Initialize-TkEmailAppParamsObject,Public, +Initialize-TkM365AuditAppParamsObject,Public, +Initialize-TkMemPolicyManagerAppParamsObject,Public, +Initialize-TkModuleEnv,Public,"Install-Module, Import-Module, Get-Module, Write-AuditLog" +Initialize-TkRequiredResourcePermissionObject,Public,"Get-MgServicePrincipal, Find-MgGraphPermission, Write-AuditLog" +New-TkAppRegistration,Public,"Get-ChildItem, New-MgApplication, Write-AuditLog" +New-TkAppSpOauth2Registration,Public,Write-AuditLog diff --git a/README.md b/README.md index a715f76..990f1cb 100644 --- a/README.md +++ b/README.md @@ -278,8 +278,8 @@ 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 | | @@ -290,7 +290,7 @@ New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain ] + 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] [-LogOutput ] [-WhatIf] [-Confirm] [] @@ -326,13 +328,13 @@ Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThum ### Parameters | Name | Alias | Description | Required? | Pipeline Input | Default Value | | - | - | - | - | - | - | -| AppPrefix | | The prefix used to initialize the Graph Email App. Must be 2-4 characters, letters, and numbers only. Default is 'Gtk'. | false | false | Gtk | +| AppPrefix | | The prefix used to initialize the Graph Email App. Must be 2-4 characters, letters, and numbers only. The default value is 'Gtk'. | false | false | Gtk | | AuthorizedSenderUserName | | The username of the authorized sender. Must be a valid email address. | true | false | | | MailEnabledSendingGroup | | The mail-enabled security group. Must be a valid email address. | true | false | | | ExistingAppObjectId | | The AppId of the existing App Registration to which you want to attach a certificate. Must be a valid GUID. | true | false | | | CertPrefix | | Prefix to add to the certificate subject for the existing app. | false | false | | | CertThumbprint | | The thumbprint of the certificate to be retrieved. Must be a valid 40-character hexadecimal string. | false | false | | -| KeyExportPolicy | | Key export policy for the certificate. Valid values are 'Exportable' and 'NonExportable'. Default is 'NonExportable'. | false | false | NonExportable | +| KeyExportPolicy | | Key export policy for the certificate. Valid values are 'Exportable' and 'NonExportable'. The default value is 'NonExportable'. | false | false | NonExportable | | VaultName | | If specified, use a custom vault name. Otherwise, use the default 'GraphEmailAppLocalStore'. | false | false | GraphEmailAppLocalStore | | 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 | @@ -438,7 +440,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 @@ -451,9 +453,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 | @@ -462,10 +464,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** @@ -478,7 +480,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 @@ -491,7 +493,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 | @@ -503,7 +505,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' @@ -534,20 +536,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** @@ -568,3 +570,5 @@ Send-TkEmailAppMessage -AppId "00000000-1111-2222-3333-444444444444" -TenantId " -Subject "Manual Email" -EmailBody "Hello from Manual!" Uses the provided AppId, TenantId, and CertThumbprint directly (no vault) to obtain a token and send an email. ``` + + diff --git a/README2.md b/README2.md index 0eaf606..07e6fd3 100644 --- a/README2.md +++ b/README2.md @@ -18,8 +18,8 @@ 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 | | @@ -30,7 +30,7 @@ New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain ] + 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] [-LogOutput ] [-WhatIf] [-Confirm] [] @@ -66,13 +68,13 @@ Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThum ### Parameters | Name | Alias | Description | Required? | Pipeline Input | Default Value | | - | - | - | - | - | - | -| AppPrefix | | The prefix used to initialize the Graph Email App. Must be 2-4 characters, letters, and numbers only. Default is 'Gtk'. | false | false | Gtk | +| AppPrefix | | The prefix used to initialize the Graph Email App. Must be 2-4 characters, letters, and numbers only. The default value is 'Gtk'. | false | false | Gtk | | AuthorizedSenderUserName | | The username of the authorized sender. Must be a valid email address. | true | false | | | MailEnabledSendingGroup | | The mail-enabled security group. Must be a valid email address. | true | false | | | ExistingAppObjectId | | The AppId of the existing App Registration to which you want to attach a certificate. Must be a valid GUID. | true | false | | | CertPrefix | | Prefix to add to the certificate subject for the existing app. | false | false | | | CertThumbprint | | The thumbprint of the certificate to be retrieved. Must be a valid 40-character hexadecimal string. | false | false | | -| KeyExportPolicy | | Key export policy for the certificate. Valid values are 'Exportable' and 'NonExportable'. Default is 'NonExportable'. | false | false | NonExportable | +| KeyExportPolicy | | Key export policy for the certificate. Valid values are 'Exportable' and 'NonExportable'. The default value is 'NonExportable'. | false | false | NonExportable | | VaultName | | If specified, use a custom vault name. Otherwise, use the default 'GraphEmailAppLocalStore'. | false | false | GraphEmailAppLocalStore | | 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 | @@ -178,7 +180,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 @@ -191,9 +193,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 | @@ -202,10 +204,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** @@ -218,7 +220,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 @@ -231,7 +233,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 | @@ -243,7 +245,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' @@ -274,20 +276,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/RequiredModules.psd1 b/RequiredModules.psd1 index ef2098d..9203e9a 100644 --- a/RequiredModules.psd1 +++ b/RequiredModules.psd1 @@ -14,7 +14,4 @@ ChangelogManagement = 'latest' Sampler = 'latest' 'Sampler.GitHubTasks' = 'latest' - - } - diff --git a/docs/index.html b/docs/index.html index c431dd0..6a6d7e9 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2,7 +2,7 @@