GraphAppToolkit

New-MailEnabledSendingGroup -Name <String> [-Alias <String>] -PrimarySmtpAddress <String> [-LogOutputPath <String>] [-WhatIf] [-Confirm] [<CommonParameters>]

New-MailEnabledSendingGroup -Name <String> [-Alias <String>] -DefaultDomain <String> [-LogOutputPath <String>] [-WhatIf] [-Confirm] [<CommonParameters>]

- Requires connectivity to Exchange Online (Connect-TkMsService -ExchangeOnline). - The caller must have sufficient privileges to create or modify distribution groups. - DefaultParameterSetName = 'CustomDomain'.

EXAMPLE 1

New-MailEnabledSendingGroup -Name "SecureSenders" -DefaultDomain "contoso.com"
Creates a new mail-enabled security group named "SecureSenders" with a primary SMTP address
of SecureSenders@contoso.com.

EXAMPLE 2

New-MailEnabledSendingGroup -Name "SecureSenders" -Alias "Senders" -PrimarySmtpAddress "Senders@customdomain.org"
Creates a new mail-enabled security group named "SecureSenders" with an alias "Senders"
and a primary SMTP address of Senders@customdomain.org.

Publish-TkEmailApp [-AppPrefix <String>] -AuthorizedSenderUserName <String> -MailEnabledSendingGroup <String> [-CertPrefix <String>] [-CertThumbprint <String>] [-KeyExportPolicy <String>] [-VaultName <String>] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [-LogOutput <String>] [-WhatIf] [-Confirm] [<CommonParameters>]

Publish-TkEmailApp -ExistingAppObjectId <String> -CertPrefix <String> [-CertThumbprint <String>] [-KeyExportPolicy <String>] [-VaultName <String>] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [-LogOutput <String>] [-WhatIf] [-Confirm] [<CommonParameters>]

This cmdlet requires that the user running the cmdlet have the necessary permissions to create the app and connect to Exchange Online.

EXAMPLE 1

# 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-<Session AD Domain>-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-<Session AD Domain>-As-helpdesk'
        CertificateSubject     = 'GraphToolKit-GTK-<Session AD Domain>-As-helpdesk'
        AppRestrictedSendGroup = 'CTSO-GraphAPIMail@contoso.com'
        CertExpires            = 'yyyy-MM-dd HH:mm:ss'
        CertThumbprint         = 'your-cert-thumbprint'
        ConsentUrl             = 'https://login.microsoftonline.com/<your-tenant-id>/adminconsent?client_id=<your-app-id>'
        DefaultDomain          = 'contoso.com'
        SendAsUser             = 'helpdesk'
        SendAsUserEmail        = 'helpdesk@contoso.com'
        TenantID               = 'your-tenant-id'
    }

EXAMPLE 2

# 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-<Session AD Domain>-As-helpdesk'
    $params = @{
        AppId                  = 'your-app-id'
        Id                     = 'your-app-object-id'
        AppName                = 'GraphToolKit-Gtk-<Session AD Domain>-As-helpdesk'
        CertificateSubject     = 'GraphToolKit-CTSO-<Session AD Domain>-As-helpdesk'
        AppRestrictedSendGroup = 'CTSO-GraphAPIMail@contoso.com'
        CertExpires            = 'yyyy-MM-dd HH:mm:ss'
        CertThumbprint         = 'your-cert-thumbprint'
        ConsentUrl             = 'https://login.microsoftonline.com/<your-tenant-id>/adminconsent?client_id=<your-app-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": "<Public IP Address of the client where the app was called>",
        "New-Company_Host": "<Host of the client where the app was called>",
        "NewCoolCompany_ClientIP": "<Public IP Address of the client where the app was called>",
        "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.

Publish-TkM365AuditApp [[-AppPrefix] <String>] [[-CertThumbprint] <String>] [[-KeyExportPolicy] <String>] [[-VaultName] <String>] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [<CommonParameters>]

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'

EXAMPLE 1

Publish-TkM365AuditApp -AppPrefix "CS12" -ReturnParamSplat
Creates a new M365 Audit App with the prefix "CS12", returns a parameter splat, and stores
the credentials in the default vault.

Publish-TkMemPolicyManagerApp [-AppPrefix] <String> [[-CertThumbprint] <String>] [[-KeyExportPolicy] <String>] [[-VaultName] <String>] [-OverwriteVaultSecret] [-ReadWrite] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [<CommonParameters>]

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'

EXAMPLE 1

Publish-TkMemPolicyManagerApp -AppPrefix "CORP" -ReadWrite
Creates a new MEM Policy Manager App with read-write permissions, retrieves or
creates a certificate, and stores the credentials in the default vault.

Send-TkEmailAppMessage -AppName <String> -To <String> -FromAddress <String> -Subject <String> -EmailBody <String> [-AttachmentPath <String[]>] [-VaultName <String>] [-WhatIf] [-Confirm] [<CommonParameters>]

Send-TkEmailAppMessage -AppId <String> -TenantId <String> -CertThumbprint <String> -To <String> -FromAddress <String> -Subject <String> -EmailBody <String> [-AttachmentPath <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]

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

EXAMPLE 1

# Using the 'Vault' parameter set
Send-TkEmailAppMessage -AppName "GraphEmailApp" -To "recipient@example.com" -FromAddress "sender@example.com" `
    -Subject "Test Email" -EmailBody "This is a test email."
Retrieves the app's credentials (AppId, TenantId, CertThumbprint) from the local vault under the
secret name "GraphEmailApp" and sends an email.

EXAMPLE 2

# Using the 'Manual' parameter set
Send-TkEmailAppMessage -AppId "00000000-1111-2222-3333-444444444444" -TenantId "contoso.onmicrosoft.com" `
    -CertThumbprint "AABBCCDDEEFF11223344556677889900" -To "recipient@example.com" -FromAddress "sender@example.com" `
    -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.