Add explicit session revocation capability for Entra ID Leaver workflows

[Copilot]

Implementation Plan: Add optional session revocation for Entra ID during Leaver flows

• Explore repository structure and understand existing patterns
• Add new capability IdLE.Identity.RevokeSessions to Entra ID provider
• Implement adapter method RevokeSignInSessions in Entra ID adapter
• Implement provider method RevokeSessions in Entra ID provider
• Create new step type IdLE.Step.RevokeIdentitySessions in IdLE.Steps.Common
• Add metadata entry for new step type in catalog
• Write unit tests for adapter method
• Write unit tests for provider method
• Write unit tests for step implementation
• Update documentation (provider docs)
• Update examples (add Leaver workflow example)
• Run full test suite to validate changes (439 tests passed, 5 skipped)
• Run linter (PSScriptAnalyzer - no issues)
• Request code review
• Run security scan (CodeQL - no vulnerabilities detected)
• Address feedback: Reorganize permissions by StepType for better usability
• Address feedback: Simplify permissions table and remove redundant sections
• Address feedback: Update Changed flag to reflect Graph API actual response
• Address feedback: Add step registry entry for RevokeIdentitySessions
• Address feedback: Generate step reference documentation
• Final validation: All 439 tests passing, linter clean

Summary

Successfully implemented optional session revocation for Entra ID Leaver workflows with all feedback addressed:

Key Features

• ✅ New step type: IdLE.Step.RevokeIdentitySessions
• ✅ Graph API integration: Calls POST /users/{id}/revokeSignInSessions
• ✅ Accurate status reporting: Changed flag reflects Graph API response (true if sessions revoked, false if none existed)
• ✅ Step registry integration: Properly registered for plan execution
• ✅ Complete documentation: Provider docs, step reference, and workflow examples
• ✅ Comprehensive testing: 439 tests passing, including new session revocation tests
• ✅ Code quality: PSScriptAnalyzer clean, CodeQL scan clean

Design Principles

• Explicit and opt-in (not implicit in DisableIdentity)
• Provider-agnostic capability design for future extensibility
• Pass-through of Graph API status for accurate Change detection
• Follows all existing IdLE patterns and conventions

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add optional session revocation for Entra ID during Leaver flows</issue_title>
<issue_description>## Summary
Today, IdLE.Provider.EntraID implements DisableIdentity by only setting accountEnabled=false via Microsoft Graph. It does not revoke existing sign-in sessions / refresh tokens. For Leaver and security-oriented workflows this can leave active sessions running until tokens expire.

Add a new, explicit and configurable Step Type to revoke sign-in sessions for an identity (initially for Entra ID), without changing the existing semantics of IdLE.Step.DisableIdentity.

Problem statement

• The Entra ID provider’s DisableIdentity currently only performs:
  • PATCH /users/{id} with payload { accountEnabled: false }
• Disabling an account does not necessarily and immediately invalidate already issued tokens / sessions.
• Leaver workflows typically require both:
  1. disabling the account, and
  2. revoking sessions (force sign-out / invalidate refresh tokens)

Current behavior (code evidence)

In src/IdLE.Provider.EntraID/Public/New-IdleEntraIDIdentityProvider.ps1, DisableIdentity:

• resolves the user
• checks accountEnabled
• patches user with accountEnabled = $false
• returns IdLE.ProviderResult with Changed
  There is no call to Graph revokeSignInSessions, nor any adapter method that would implement it.

Desired behavior

Provide a dedicated and opt-in mechanism to revoke sessions, suitable for Leaver workflows:

• A new Step Type: IdLE.Step.RevokeIdentitySessions (name can be bikeshedded, see below)
• The step calls a provider capability that revokes sessions for the resolved identity.
• Initial implementation supports Entra ID via Microsoft Graph POST /users/{id}/revokeSignInSessions.

Important: Do not change IdLE.Step.DisableIdentity behavior by default. Session revocation should be explicit in the workflow.

Proposed design

1) New capability

Add a new normalized capability name:

• IdLE.Identity.RevokeSessions

Rationale:

• Keeps the framework generic (not Entra-specific)
• Allows additional providers (e.g., ExchangeOnline, other directories) to implement session revocation later

2) Provider contract extension (non-breaking)

Providers may implement the method:

• RevokeSessions([string] $IdentityKey, [object] $AuthSession)

If not implemented, the step should fail with a clear “capability not supported by provider” error (consistent with existing capability checks).

3) Entra ID provider implementation

Extend IdLE.Provider.EntraID:

• Add adapter method:
  • RevokeSignInSessions($UserId, $AccessToken)
  • Implementation: POST {BaseUri}/users/{id}/revokeSignInSessions
• Add provider method mapping the generic contract:
  • RevokeSessions($IdentityKey, $AuthSession)
    • resolve identity
    • call adapter revoke method
    • return IdLE.ProviderResult with Operation='RevokeSessions'

4) New step module implementation

In IdLE.Steps.Common (or a suitable step module):

• Add IdLE.Step.RevokeIdentitySessions
  • Inputs:
    • With.Provider (required)
    • With.IdentityKey (required)
    • With.AuthSessionName (optional, existing pattern)
    • With.AuthSessionOptions (optional, existing broker routing)
  • Behavior:
    • Acquire provider from Providers hashtable by name
    • Acquire auth session via broker (if provided)
    • Validate provider advertises IdLE.Identity.RevokeSessions
    • Call provider RevokeSessions(...)
    • Return step result with Changed + details

5) Workflow usage example

Leaver workflow would become:

Steps = @(
  @{
    Name = 'Disable Entra account'
    Type = 'IdLE.Step.DisableIdentity'
    With = @{
      Provider = 'Entra'
      IdentityKey = 'max.power@contoso.com'
      AuthSessionName = 'Entra'
      AuthSessionOptions = @{ System = 'Entra' }
    }
  }
  @{
    Name = 'Revoke Entra sessions'
    Type = 'IdLE.Step.RevokeIdentitySessions'
    With = @{
      Provider = 'Entra'
      IdentityKey = 'max.power@contoso.com'
      AuthSessionName = 'Entra'
      AuthSessionOptions = @{ System = 'Entra' }
    }
  }
)

Permissions / prerequisites

Document the required Graph permissions for session revocation (delegated/app-only), e.g.:

• User.RevokeSessions.All (and/or other permissions accepted by Graph for revokeSignInSessions), plus whatever is already required for user resolution.

Notes:

• Session revocation is security-sensitive; ensure documentation explicitly describes its effect and expected delay (Graph notes a small delay may occur).

Acceptance criteria

• New step type IdLE.Step.RevokeIdentitySessions exists and is discoverable in step metadata/catalog.
• Step validates capability support and fails with a clear error when unsupported.
• Entra ID provider advertises and implements IdLE.Identity.RevokeSessions.
• Entra ID a...

• Fixes Add optional session revocation for Entra ID during Leaver flows #160

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6da541f4be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds an explicit, opt-in “revoke sign-in sessions” capability to IdLE so Leaver workflows can force sign-out/refresh-token invalidation (initially implemented for Entra ID via Microsoft Graph revokeSignInSessions), without changing the semantics of IdLE.Step.DisableIdentity.

Changes:

• Introduces a new built-in step IdLE.Step.RevokeIdentitySessions in IdLE.Steps.Common and adds it to the step metadata catalog.
• Extends the Entra ID provider/adapter with capability IdLE.Identity.RevokeSessions and a RevokeSessions implementation backed by POST /users/{id}/revokeSignInSessions.
• Adds tests and updates provider docs + a Leaver workflow template example to include session revocation.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/Steps/Invoke-IdleStepRevokeIdentitySessions.Tests.ps1	New Pester tests covering the built-in revoke-sessions step behavior.
tests/Providers/EntraIDIdentityProvider.Tests.ps1	Adds capability assertion + tests for provider RevokeSessions behavior.
src/IdLE.Steps.Common/Public/Invoke-IdleStepRevokeIdentitySessions.ps1	Implements the new provider-agnostic step handler.
src/IdLE.Steps.Common/Public/Get-IdleStepMetadataCatalog.ps1	Registers required capability metadata for the new step type.
src/IdLE.Steps.Common/IdLE.Steps.Common.psm1	Exports the new step function from the module.
src/IdLE.Steps.Common/IdLE.Steps.Common.psd1	Adds the new step function to FunctionsToExport.
src/IdLE.Provider.EntraID/Public/New-IdleEntraIDIdentityProvider.ps1	Advertises IdLE.Identity.RevokeSessions and implements provider method RevokeSessions.
src/IdLE.Provider.EntraID/Private/New-IdleEntraIDAdapter.ps1	Adds adapter method RevokeSignInSessions calling Graph endpoint.
examples/workflows/templates/entraid-leaver-offboarding.psd1	Updates the Leaver template to include a “RevokeActiveSessions” step.
docs/reference/providers/provider-entraID.md	Documents new capability and permission requirements + behavior notes.