ExchangeOnline - mailbox permissions

[blindzero]

Problem Statement

There is currently no capability or Step Type in IdLE to set mailbox delegate permissions (e.g. FullAccess, SendAs, SendOnBehalf) for Exchange Online mailboxes.

For real-world JML workflows this is a common requirement (shared mailboxes, assistants, team mailboxes, role mailboxes). Today, workflow authors must implement this outside IdLE, which breaks:

• portability (logic moves into host scripts)
• deterministic plan/execute (permissions changes are not represented in the plan)
• testability (no contract-based/mocked implementation)

Proposed Solution

Add a provider-agnostic step and capability for mailbox permission convergence.

New Step Type

• IdLE.Step.Mailbox.EnsurePermissions
  • Purpose: idempotently converge delegate permissions for a mailbox.
  • Module: IdLE.Steps.Mailbox

Capability

• IdLE.Mailbox.Permissions.Ensure
  • Used for planning-time validation.

Step input contract (With)

With = @{
    Provider        = 'ExchangeOnline'        # optional, defaults to 'ExchangeOnline'
    IdentityKey     = 'shared@contoso.com'    # mailbox identity (UPN/SMTP)

    # Target permissions (data-only)
    Permissions     = @(
        @{ AssignedUser = 'user1@contoso.com'; Right = 'FullAccess'; Ensure = 'Present' }
        @{ AssignedUser = 'user2@contoso.com'; Right = 'SendAs';     Ensure = 'Present' }
        @{ AssignedUser = 'user3@contoso.com'; Right = 'SendOnBehalf'; Ensure = 'Absent' }
    )

    # AuthSession selection (same convention as other mailbox steps)
    AuthSessionName    = 'ExchangeOnline'     # optional, defaults to Provider
    AuthSessionOptions = @{ Role = 'Admin' }  # optional
}

Supported rights (v1)

Minimum viable scope (v1):

• FullAccess
• SendAs
• SendOnBehalf

Non-goals for v1 (nice-to-have later):

• folder-level permissions
• calendar delegation/processing options
• auto-mapping behavior controls

Provider contract extension

Extend the mailbox provider contract with a single, mockable method (name is a suggestion):

• EnsureMailboxPermissions(MailboxIdentity, Permissions, AuthSession)

Where Permissions is a data-only array (see above) and the provider returns a data-only result describing:

• desired vs. current
• computed changes (add/remove)
• performed operations (for execution)

Exchange Online provider implementation

In IdLE.Provider.ExchangeOnline, implement the contract using an internal adapter layer so it is testable without calling EXO:

• full access: Get-MailboxPermission, Add-MailboxPermission, Remove-MailboxPermission
• send as: Get-RecipientPermission, Add-RecipientPermission, Remove-RecipientPermission
• send on behalf: Get-Mailbox (or existing GetMailbox) + Set-Mailbox -GrantSendOnBehalfTo

Step behavior

• Read current state via provider.
• Compute delta deterministically.
• If no changes required: return Changed = $false.
• If changes required: execute provider method(s) and return Changed = $true.
• Emit structured events (no secrets).

Tests

• Unit tests for the step (delta computation, validation, idempotency) using a mock provider.
• Provider contract tests for Exchange Online provider using a mocked adapter.

Documentation

• Add step documentation via the generated step reference (docs/reference/steps.md) by updating step help and running the generator.
• Add/extend Exchange Online provider docs to include:
  • required capability
  • example workflow snippet for mailbox permissions

Impact

• New capability + new Step Type only. No breaking changes expected.
• Exchange Online provider gains an additional method and capability advertisement.
• Workflows can start using the new step immediately once provider supports it.

Additional Context

Repository review indicates IdLE.Steps.Mailbox currently exports only:

• IdLE.Step.Mailbox.GetInfo
• IdLE.Step.Mailbox.EnsureType
• IdLE.Step.Mailbox.EnsureOutOfOffice

and the Exchange Online provider advertises mailbox capabilities for info/type/OOO only.
This enhancement covers the missing mailbox delegate permissions use case.

Consider using pure Graph Access with Scope, not ExchangeOnlineManagement module, depending what is more likely already available or easier to integrate.