From 01d05436a108d9eaa6d1101ae39442c5cac1a2e0 Mon Sep 17 00:00:00 2001 From: DrIOS <58635327+DrIOSX@users.noreply.github.com> Date: Fri, 14 Mar 2025 14:00:57 -0500 Subject: [PATCH 1/4] add: docs and release candidate --- CHANGELOG.md | 7 + README.md | 228 ++++++++++++++++++--------- README2.md | 124 ++++++++++++--- docs/index.html | 103 ++++++++++-- help/GraphAppToolkit.md | 3 +- source/Public/Publish-TkEmailApp.ps1 | 97 ++++++++++-- 6 files changed, 432 insertions(+), 130 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b72a3b..d5ee4af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Updated docs for the module. +- Release Candidate + +## [0.2.0-preview0001] - 2025-03-14 + +### Added + - Added cert options to the GraphAppToolkit send email. - Updated auth methods to invoke needed permissions only. - Added private functions to handle existing certs and secrets. diff --git a/README.md b/README.md index 643c1dc..ab9233e 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ These private functions handle core logic like certificate generation, connectin ```powershell $DefaultDomain = 'contoso.com' $MailEnabledSendingGroupToCreate = "CTSO-GraphAPIMail" -# Creates a mail-enabled security group named "MySenders" using a default domain +# Creates a mail-enabled security group named "CTSO-GraphAPIMail" using a default domain $group = New-MailEnabledSendingGroup -Name $MailEnabledSendingGroupToCreate -DefaultDomain $DefaultDomain ``` @@ -146,9 +146,7 @@ $LicensedUserToSendAs = 'helpdesk@contoso.com' $TwoToFourLetterCompanyAbbreviation = "CTSO" Publish-TkEmailApp ` -AppPrefix $TwoToFourLetterCompanyAbbreviation ` - -AuthorizedSenderUserName $LicensedUserToSendA ---- -s ` + -AuthorizedSenderUserName $LicensedUserToSendAs ` -MailEnabledSendingGroup $group.PrimarySmtpAddress ` -ReturnParamSplat @@ -261,8 +259,7 @@ Publish-TkM365AuditApp -AppPrefix "CSN" -CertThumbprint "FACEBEEFBEEFAABBCCDDEEF Publish-TkMemPolicyManagerApp -AppPrefix "MEM" -ReadWrite ``` -# GraphAppToolkit Module Public Functions - +# GraphAppToolkit Module ## New-MailEnabledSendingGroup ### Synopsis Creates or retrieves a mail-enabled security group with a custom or default domain. @@ -278,14 +275,14 @@ 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 | | -| WhatIf | wi | | false | false | | -| Confirm | cf | | false | false | | +| Name | Alias | Description | Required? | Pipeline Input | Default Value | +| - | - | - | - | - | - | +| 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 | | +| WhatIf | wi | | false | false | | +| Confirm | cf | | false | false | | ### Inputs - None. This function does not accept pipeline input. @@ -293,7 +290,7 @@ New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain ] -AuthorizedSenderUserName -MailEnabledSendingGroup [-CertPrefix ] [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [] +Publish-TkEmailApp [-AppPrefix ] -AuthorizedSenderUserName -MailEnabledSendingGroup [-CertPrefix ] [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [] -Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [] +Publish-TkEmailApp -ExistingAppObjectId -CertPrefix [-CertThumbprint ] [-KeyExportPolicy ] [-VaultName ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [] ``` ### 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 | -| 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 | -| 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 | +| 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 | +| 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 | +| 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 | +| DoNotUseDomainSuffix | | Switch to add session domain suffix to the app name. | false | 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. Permissions required: - 'Application.ReadWrite.All' - 'DelegatedPermissionGrant.ReadWrite.All' - 'Directory.ReadWrite.All' - 'RoleManagement.ReadWrite.Directory' +This cmdlet requires that the user running the cmdlet have the necessary permissions to create the app and connect to Exchange Online. ### Examples **EXAMPLE 1** ```powershell -Publish-TkEmailApp -AppPrefix 'Gtk' -AuthorizedSenderUserName 'user@example.com' -MailEnabledSendingGroup 'group@example.com' +# Permissions required for app registration: +- 'Application.ReadWrite.All' +- 'DelegatedPermissionGrant.ReadWrite.All' +- 'Directory.ReadWrite.All' +- 'RoleManagement.ReadWrite.Directory' +# Permissions granted to the app: +- 'Mail.Send' (Application) - Send mail as any user +Exchange application policy restricts send to a mail enabled security group +# Ensure a mail enabled sending group is created first: +$DefaultDomain = 'contoso.com' +$MailEnabledSendingGroupToCreate = "CTSO-GraphAPIMail" +# Creates a mail-enabled security group named "MySenders" using a default domain +$group = New-MailEnabledSendingGroup -Name $MailEnabledSendingGroupToCreate -DefaultDomain $DefaultDomain +# Create a new Graph Email App for a single tenant +$LicensedUserToSendAs = 'helpdesk@contoso.com' +Publish-TkEmailApp ` +-AuthorizedSenderUserName $LicensedUserToSendAs ` +-MailEnabledSendingGroup $group.PrimarySmtpAddress ` +-ReturnParamSplat +# Returns an app named like 'GraphToolKit-Gtk--As-helpdesk' +# Returns a param splat that can be used as input for the send mail function: +# Example: +$params = @{ +AppId = 'your-app-id' +Id = 'your-app-object-id' +AppName = 'GraphToolKit-Gtk--As-helpdesk' +CertificateSubject = 'GraphToolKit-GTK--As-helpdesk' +AppRestrictedSendGroup = 'CTSO-GraphAPIMail@contoso.com' +CertExpires = 'yyyy-MM-dd HH:mm:ss' +CertThumbprint = 'your-cert-thumbprint' +ConsentUrl = 'https://login.microsoftonline.com//adminconsent?client_id=' +DefaultDomain = 'contoso.com' +SendAsUser = 'helpdesk' +SendAsUserEmail = 'helpdesk@contoso.com' +TenantID = 'your-tenant-id' +} ``` -Creates a new Graph Email App with the specified parameters. + **EXAMPLE 2** ```powershell -Publish-TkEmailApp -ExistingAppObjectId '12345678-1234-1234-1234-1234567890ab' -CertPrefix 'Cert' +# Create a multi client app registration where one app exists and multiple certificates are associated to the app: +# Initial setup: +# Create the group as before (or reuse the existing group) and run the following commands: +$LicensedUserToSendAs = 'helpdesk@contoso.com' +$CertPrefix = "CTSO" # First Company prefix. This will be used to prefix the certificate subject. +Publish-TkEmailApp ` +-CertPrefix $CertPrefix ` +-AuthorizedSenderUserName $LicensedUserToSendAs ` +-MailEnabledSendingGroup $group.PrimarySmtpAddress ` +-ReturnParamSplat +# Returns an app named like 'GraphToolKit-Gtk--As-helpdesk' +$params = @{ +AppId = 'your-app-id' +Id = 'your-app-object-id' +AppName = 'GraphToolKit-Gtk--As-helpdesk' +CertificateSubject = 'GraphToolKit-CTSO--As-helpdesk' +AppRestrictedSendGroup = 'CTSO-GraphAPIMail@contoso.com' +CertExpires = 'yyyy-MM-dd HH:mm:ss' +CertThumbprint = 'your-cert-thumbprint' +ConsentUrl = 'https://login.microsoftonline.com//adminconsent?client_id=' +DefaultDomain = 'contoso.com' +SendAsUser = 'helpdesk' +SendAsUserEmail = 'helpdesk@contoso.com' +TenantID = 'your-tenant-id' +} +$useExistingParams = @{ +ExistingAppObjectId = $params.Id +CertPrefix = 'NewCompany' +OverwriteVaultSecret = $true # optional, if you want to overwrite the existing vault secret +ReturnParamSplat = $true # optional, returns the param splat +} +Publish-TkEmailApp @useExistingParams +# The new Cert will be prefixed with the new company prefix and will allow the current client to authenticate. +# Back in the app registrations console, if you look at the internal notes in the properties of the app: +# The app's "Internal Notes" will be populated with the following json: +# Assists in tracking the app's usage and configuration. +{ +"GraphEmailAppFor": "helpdesk@contoso.com", +"RestrictedToGroup": "CTSO-GraphAPIMail@contoso.com", +"AppPermissions": "Mail.Send", +"New-Company_ClientIP": "", +"New-Company_Host": "", +"NewCoolCompany_ClientIP": "", +"NewCoolCompany_Host": "Host of the client where the app was called>" +} +# New cert additions added through the toolkit will append new client info to these notes. ``` -Uses an existing app and attaches a certificate with the specified prefix. + ## 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 -Publish-TkM365AuditApp [[-AppPrefix] ] [[-CertThumbprint] ] [[-KeyExportPolicy] ] [[-VaultName] ] [-OverwriteVaultSecret] [-ReturnParamSplat] [] +Publish-TkM365AuditApp [[-AppPrefix] ] [[-CertThumbprint] ] [[-KeyExportPolicy] ] [[-VaultName] ] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [] ``` ### 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 | -| 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 | -| 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 | +| 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 | +| 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 | +| 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 | +| DoNotUseDomainSuffix | | If specified, does not append the domain suffix to the app name. | false | false | False | ### Inputs - 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: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All', 'RoleManagement.ReadWrite.Directory' +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** @@ -396,34 +475,35 @@ 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 -Publish-TkMemPolicyManagerApp [-AppPrefix] [[-CertThumbprint] ] [[-KeyExportPolicy] ] [[-VaultName] ] [-OverwriteVaultSecret] [-ReadWrite] [-ReturnParamSplat] [] +Publish-TkMemPolicyManagerApp [-AppPrefix] [[-CertThumbprint] ] [[-KeyExportPolicy] ] [[-VaultName] ] [-OverwriteVaultSecret] [-ReadWrite] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [] ``` ### 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 | | -| 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 | -| OverwriteVaultSecret | | If specified, overwrites any existing secret of the same name in the vault. | false | false | False | -| ReadWrite | | If specified, grants read-write MEM/Intune permissions. Otherwise, read-only permissions are granted. | false | false | False | -| ReturnParamSplat | | If specified, returns a parameter splat string for use in other functions. Otherwise, returns a PSCustomObject containing the app details. | false | false | False | +| 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 | | +| 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 | +| OverwriteVaultSecret | | If specified, overwrites any existing secret of the same name in the vault. | false | false | False | +| ReadWrite | | If specified, grants read-write MEM/Intune permissions. Otherwise, read-only permissions are granted. | false | false | False | +| ReturnParamSplat | | If specified, returns a parameter splat string for use in other functions. Otherwise, returns a PSCustomObject containing the app details. | false | false | False | +| DoNotUseDomainSuffix | | If specified, the function does not append the domain suffix to the app name. | false | false | False | ### Inputs - 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: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All', 'RoleManagement.ReadWrite.Directory' +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' ### Examples **EXAMPLE 1** @@ -449,22 +529,22 @@ 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 | | -| 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 | -| WhatIf | wi | | false | false | | -| Confirm | cf | | false | false | | +| Name | Alias | Description | Required? | Pipeline Input | Default Value | +| - | - | - | - | - | - | +| 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 | +| 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 bdf68b4..5ed0aa4 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 | | | WhatIf | wi | | false | false | | | Confirm | cf | | false | false | | ### Inputs @@ -29,7 +29,7 @@ New-MailEnabledSendingGroup -Name [-Alias ] -DefaultDomain -CertPrefix [-CertThum | 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 | ### Note -This cmdlet requires that the user running the cmdlet have the necessary permissions to create the app and connect to Exchange Online. Permissions required for app registration: - 'Application.ReadWrite.All' - 'DelegatedPermissionGrant.ReadWrite.All' - 'Directory.ReadWrite.All' - 'RoleManagement.ReadWrite.Directory' Permissions granted to the app: - 'Mail.Send' \(Application\\) - Send mail as any user Exchange application policy restricts send to a mail enabled security group +This cmdlet requires that the user running the cmdlet have the necessary permissions to create the app and connect to Exchange Online. ### Examples **EXAMPLE 1** ```powershell -Publish-TkEmailApp -AppPrefix 'Gtk' -AuthorizedSenderUserName 'user@example.com' -MailEnabledSendingGroup 'group@example.com' +# Permissions required for app registration: +- 'Application.ReadWrite.All' +- 'DelegatedPermissionGrant.ReadWrite.All' +- 'Directory.ReadWrite.All' +- 'RoleManagement.ReadWrite.Directory' +# Permissions granted to the app: +- 'Mail.Send' (Application) - Send mail as any user +Exchange application policy restricts send to a mail enabled security group +# Ensure a mail enabled sending group is created first: +$DefaultDomain = 'contoso.com' +$MailEnabledSendingGroupToCreate = "CTSO-GraphAPIMail" +# Creates a mail-enabled security group named "MySenders" using a default domain +$group = New-MailEnabledSendingGroup -Name $MailEnabledSendingGroupToCreate -DefaultDomain $DefaultDomain +# Create a new Graph Email App for a single tenant +$LicensedUserToSendAs = 'helpdesk@contoso.com' +Publish-TkEmailApp ` +-AuthorizedSenderUserName $LicensedUserToSendAs ` +-MailEnabledSendingGroup $group.PrimarySmtpAddress ` +-ReturnParamSplat +# Returns an app named like 'GraphToolKit-Gtk--As-helpdesk' +# Returns a param splat that can be used as input for the send mail function: +# Example: +$params = @{ +AppId = 'your-app-id' +Id = 'your-app-object-id' +AppName = 'GraphToolKit-Gtk--As-helpdesk' +CertificateSubject = 'GraphToolKit-GTK--As-helpdesk' +AppRestrictedSendGroup = 'CTSO-GraphAPIMail@contoso.com' +CertExpires = 'yyyy-MM-dd HH:mm:ss' +CertThumbprint = 'your-cert-thumbprint' +ConsentUrl = 'https://login.microsoftonline.com//adminconsent?client_id=' +DefaultDomain = 'contoso.com' +SendAsUser = 'helpdesk' +SendAsUserEmail = 'helpdesk@contoso.com' +TenantID = 'your-tenant-id' +} ``` -Creates a new Graph Email App with the specified parameters. + **EXAMPLE 2** ```powershell -Publish-TkEmailApp -ExistingAppObjectId '12345678-1234-1234-1234-1234567890ab' -CertPrefix 'Cert' +# Create a multi client app registration where one app exists and multiple certificates are associated to the app: +# Initial setup: +# Create the group as before (or reuse the existing group) and run the following commands: +$LicensedUserToSendAs = 'helpdesk@contoso.com' +$CertPrefix = "CTSO" # First Company prefix. This will be used to prefix the certificate subject. +Publish-TkEmailApp ` +-CertPrefix $CertPrefix ` +-AuthorizedSenderUserName $LicensedUserToSendAs ` +-MailEnabledSendingGroup $group.PrimarySmtpAddress ` +-ReturnParamSplat +# Returns an app named like 'GraphToolKit-Gtk--As-helpdesk' +$params = @{ +AppId = 'your-app-id' +Id = 'your-app-object-id' +AppName = 'GraphToolKit-Gtk--As-helpdesk' +CertificateSubject = 'GraphToolKit-CTSO--As-helpdesk' +AppRestrictedSendGroup = 'CTSO-GraphAPIMail@contoso.com' +CertExpires = 'yyyy-MM-dd HH:mm:ss' +CertThumbprint = 'your-cert-thumbprint' +ConsentUrl = 'https://login.microsoftonline.com//adminconsent?client_id=' +DefaultDomain = 'contoso.com' +SendAsUser = 'helpdesk' +SendAsUserEmail = 'helpdesk@contoso.com' +TenantID = 'your-tenant-id' +} +$useExistingParams = @{ +ExistingAppObjectId = $params.Id +CertPrefix = 'NewCompany' +OverwriteVaultSecret = $true # optional, if you want to overwrite the existing vault secret +ReturnParamSplat = $true # optional, returns the param splat +} +Publish-TkEmailApp @useExistingParams +# The new Cert will be prefixed with the new company prefix and will allow the current client to authenticate. +# Back in the app registrations console, if you look at the internal notes in the properties of the app: +# The app's "Internal Notes" will be populated with the following json: +# Assists in tracking the app's usage and configuration. +{ +"GraphEmailAppFor": "helpdesk@contoso.com", +"RestrictedToGroup": "CTSO-GraphAPIMail@contoso.com", +"AppPermissions": "Mail.Send", +"New-Company_ClientIP": "", +"New-Company_Host": "", +"NewCoolCompany_ClientIP": "", +"NewCoolCompany_Host": "Host of the client where the app was called>" +} +# New cert additions added through the toolkit will append new client info to these notes. ``` -Uses an existing app and attaches a certificate with the specified prefix. + ## 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 @@ -107,9 +187,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 | @@ -118,10 +198,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** @@ -134,7 +214,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 @@ -147,7 +227,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 | @@ -159,7 +239,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' @@ -190,20 +270,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 2df905d..c21d71c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2,7 +2,7 @@