From 13c599d58c59490fbc2c7249307d4d333df3eb8b Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Sun, 15 Feb 2026 20:18:54 +0100 Subject: [PATCH 01/14] improved repo root README.md --- README.md | 61 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index ad6680e1..13c46cbb 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # IdentityLifecycleEngine (IdLE) -![IdLE Logo](/docs/assets/idle_logo_flat_white_text_small.png) +![IdLE Logo](/docs/assets/logos/idle_logo_flat_white_text_small.png) [![CI](https://github.com/blindzero/IdentityLifecycleEngine/actions/workflows/ci.yml/badge.svg)](https://github.com/blindzero/IdentityLifecycleEngine/actions/workflows/ci.yml) [![Latest](https://img.shields.io/github/v/release/blindzero/IdentityLifecycleEngine?sort=semver)](https://github.com/blindzero/IdentityLifecycleEngine/releases?q=prerelease%3Afalse) @@ -10,32 +10,31 @@ [![Pester](https://img.shields.io/badge/Tests-Pester%205-blueviolet)](#testing) [![License](https://img.shields.io/badge/License-See%20LICENSE-lightgrey)](LICENSE.md) -**IdLE** is a **generic, headless, configurable Identity or Account Lifecycle / JML (Joiner–Mover–Leaver) orchestration engine** built for **PowerShell**. +--- + +IdLE is a **generic, headless, configuration-driven** lifecycle orchestration engine +for identity and account processes (Joiner / Mover / Leaver), built for **PowerShell 7+**. -It helps you standardize identity lifecycle processes across environments by separating: +The key idea is to **separate intent from implementation**: -- **what** should happen (workflow definition) -- from **how** it happens (providers) +- **What** should happen is defined in a **workflow** (data-only configuration). +- **How** it happens is implemented by **steps** and **providers** (pluggable modules). + - **steps** define, via StepTypes, which provider-agnostic **capabilities** are required to perform a workflow step + - **providers** register to the core and announce the provided **capabilities** and implement the vendor system specific interface --- ## Why IdLE? -Identity lifecycle automation tends to become: +IdLE is a **generic, headless, configuration-driven** lifecycle orchestration engine +for identity and account processes (Joiner / Mover / Leaver), built for **PowerShell 7+**. -- tightly coupled to one system or one environment -- hard to test -- hard to change (logic baked into scripts) +The key idea is to **separate intent from implementation**: -IdLE aims to be: - -- **portable** (run anywhere PowerShell 7 runs) -- **modular** (steps + providers are swappable) -- **testable** (Pester-friendly; mock providers) -- **configuration-driven** (workflows as data) -- **extensible** (add custom steps and providers) - -For a complete overview of concepts, see **[About > Concepts](docs/about/concepts.md)**. +- **What** should happen is defined in a **workflow** (data-only configuration). +- **How** it happens is implemented by **steps** and **providers** (pluggable modules). + - **steps** define, via StepTypes, which provider-agnostic **capabilities** are required to perform a workflow step + - **providers** register to the core and announce the provided **capabilities** and implement the vendor system specific interface --- @@ -46,6 +45,8 @@ For a complete overview of concepts, see **[About > Concepts](docs/about/concept - **Plugin step model** (idempotent, provider-agnostic) - **Structured events** for audit/progress (CorrelationId, Actor, step results) +For a complete overview of concepts, see **[About > Concepts](docs/about/concepts.md)**. + --- ## Installation @@ -57,16 +58,27 @@ Install-Module -Name IdLE -Scope CurrentUser Import-Module IdLE ``` -For detailed installation instructions, requirements, and import options, see **[Installation Guide](docs/use/installation.md)**. +For further installation instructions, requirements, and options, see **[Installation Guide](docs/use/installation.md)**. --- -## Quickstart +## How to start + +Please refer to the documentation in **["How to use IdLE?"](docs/use/intro-use.md)** for further instructions, on + +1. How to write a workflow +2. Create an identity lifecycle request +3. Plan the IdLE run +4. Invoke & Execute the Plan + +--- + +## IdLE Demo Run the end-to-end demo (Plan → Execute): ```powershell -pwsh -File .\examples\Invoke-IdleDemo.ps1 +pwsh -File .\examples\Invoke-IdleDemo.ps1 -All ``` The demo shows: @@ -75,10 +87,8 @@ The demo shows: - building a deterministic plan from a workflow definition (`.psd1`) - executing the plan using built-in steps and a mock provider -By default, the demo runs **Mock workflows** that work out-of-the-box without external systems. The examples folder also includes **Live workflows** that demonstrate real-world scenarios with Active Directory and Entra ID, but these require the corresponding infrastructure and provider modules. - -The execution result buffers all emitted events in `result.Events`. Hosts can optionally stream events live -by providing `-EventSink` as an object implementing `WriteEvent(event)`. +By default, the demo runs **Mock workflows** that work out-of-the-box without external systems. +The examples folder also includes **Template workflows** that demonstrate real-world scenarios with Active Directory, Entra ID, Exchange Online but these require the corresponding infrastructure and provider modules. --- @@ -88,7 +98,6 @@ The documentation is also available at our project site: [https://blindzero.gith Start here: -- [docs/index.md](docs/index.md) – Documentation map - [docs/about/intro.md](docs/about/intro.md) – About IdLE - [docs/use/intro-use.md](docs/use/intro-use.md) – How to use IdLE - [docs/reference/intro-reference.md](docs/reference/intro-reference.md) - The authoritative IdLE reference From d60f8ed1af49aa2c1cbac247abfb482cd322cd11 Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Sun, 15 Feb 2026 20:19:11 +0100 Subject: [PATCH 02/14] docs: improved wording in about.md --- docs/about/intro.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/about/intro.md b/docs/about/intro.md index 0011ae8c..8c2829fe 100644 --- a/docs/about/intro.md +++ b/docs/about/intro.md @@ -29,7 +29,7 @@ JML (joiner/mover/leavers) processes are - time consuming and therefore - quite annoying for operators -Identity lifecycle automation often turns into long scripts that are: +Self-made identity lifecycle automation often turns into long scripts that are: - tightly coupled to one environment - hard to test @@ -41,7 +41,7 @@ IdLE aims to be: - **portable** run in different environments with PowerShell 7+ without a hard dependency on a specific host or UI - **configuration-driven** workflows are defined as data, not code. -- **modular** a small core and pluggable providers and steps. +- **modular** a small core and pluggable providers and steps that even support **extending** with your own custom add-ons. - **testable** deterministic planning, mockable providers, and strong contracts. --- From e8798894bcc51acf5bebfa66cc9947422c9393ff Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Sun, 15 Feb 2026 20:21:28 +0100 Subject: [PATCH 03/14] docs: info box for link to official site --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 13c46cbb..c6fa5d9f 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,12 @@ For a complete overview of concepts, see **[About > Concepts](docs/about/concept --- +::: info + +For improved documentation experience, please visit [https://idle-engine.io](https://idle-engine.io). + +::: + ## Installation **Quick install:** From 3acd1937b11b712b0734aece1e44ebd29fc46c39 Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Sun, 15 Feb 2026 20:21:28 +0100 Subject: [PATCH 04/14] docs: info box for link to official site --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 13c46cbb..dcf3783e 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,8 @@ For a complete overview of concepts, see **[About > Concepts](docs/about/concept --- +> **For improved documentation experience, please visit [https://idle-engine.io](https://idle-engine.io).** + ## Installation **Quick install:** From a107ab1e846b038c34dbfe8ebabf563d4f223106 Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Sun, 15 Feb 2026 20:24:16 +0100 Subject: [PATCH 05/14] docs: fixed dup header --- docs/about/concepts.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/about/concepts.md b/docs/about/concepts.md index 61c38e0c..c0b36c8b 100644 --- a/docs/about/concepts.md +++ b/docs/about/concepts.md @@ -1,10 +1,8 @@ --- -title: Concepts +title: IdLE Concepts sidebar_label: Concepts --- -# IdLE Concepts - IdLE stays headless and avoids responsibilities that belong to a host application. ## Goals From 1fa8515b682e16e00b048af4c6a574bc442eaee6 Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Sun, 15 Feb 2026 21:10:54 +0100 Subject: [PATCH 06/14] docs: reworked concept page --- docs/about/concepts.md | 137 +++++++++++++++-------------------------- 1 file changed, 50 insertions(+), 87 deletions(-) diff --git a/docs/about/concepts.md b/docs/about/concepts.md index c0b36c8b..c26fe97c 100644 --- a/docs/about/concepts.md +++ b/docs/about/concepts.md @@ -3,7 +3,9 @@ title: IdLE Concepts sidebar_label: Concepts --- -IdLE stays headless and avoids responsibilities that belong to a host application. +IdLE is a generic, headless, configuration-driven engine for identity lifecycle automation (Joiner / Mover / Leaver). It intentionally separates intent from implementation: workflows (data-only PSD1 files) declare what should happen, steps implement provider-agnostic, idempotent convergence logic, and providers adapt to external systems and manage authentication. + +The engine first builds a deterministic, auditable execution plan from a LifecycleRequest and a workflow (Plan → Execute). Planning validates conditions, inputs, and required provider capabilities; execution runs only the produced plan to ensure repeatability, safe approvals, and reliable auditing. This design prioritizes portability, testability (mockable providers), and minimal runtime assumptions by keeping the core headless and side-effect free. ## Goals @@ -23,44 +25,27 @@ IdLE stays headless and avoids responsibilities that belong to a host applicatio --- -## Responsibilities - -### Separation of Responsibility +## Components -Clear separation of responsibility is the essential foundation for maintainability: +IdLE consists of the following elements and components, which have clear and distinct boundaries to separate their responsibilities and make maintainability easier. This separation keeps the core engine free of environmental assumptions. -- **Engine** - - Orchestrates workflow execution - - Invokes steps - - Passes providers to steps - - Never depends on provider internals +### Host -- **Steps** - - Implement domain logic - - Use providers through contracts - - Must not assume a specific provider implementation +The host is technically not really a component of IdLE. It is the environment in which IdLE is running, so your PowerShell console, scripting session or whatever is used to run IdLe. The host -- **Providers** - - Implement infrastructure-specific behavior - - Fulfill contracts expected by steps - - Encapsulate external system details - - Authenticate and manage sessions - - Translate generic operations to system APIs - - Are mockable for tests - - Avoid global state +- Selects and configures providers +- Injects providers into plan execution +- Decides which provider implementations are used -- **Host** - - Selects and configures providers - - Injects providers into plan execution - - Decides which provider implementations are used +### Engine (basically IdLE.Core) -This separation keeps the core engine free of environmental assumptions. +IdLE.Core is the central engine (module) of IdLE and performs the most central tasks -**Important:** Steps should not handle authentication. Authentication is a provider responsibility via AuthSessionBroker. - ---- - -IdLE consists of the following elements and components: +- Orchestrates workflow execution +- Invokes steps +- Passes providers to steps +- Never depends on provider internals +- Authentication session brokerage ## Request @@ -76,12 +61,16 @@ $Request = New-IdleRequest -LifecycleEvent 'Joiner' -IdentityKeys @{ } ``` ---- +### Workflow and Steps -## Workflow +**Workflows** are **data-only configuration files** (PSD1) describing which steps should run for a lifecycle event. Usually workflows are written in `psd1` files, that -Workflows are **data-only configuration files** (PSD1) describing which steps should run for a lifecycle event. -To enable larger flexibility, you can use placeholders instead of literals to be substituted with data from request. +- use Data-only PSD1 configuration (no ScriptBlocks or executable objects) +- declare step sequence by Type string and provide per-step With parameters +- may use placeholders referencing Request data; substitutions occur during planning +- serve as deterministic, reviewable input to the planner (suitable for approvals and audits) +- must not perform authentication, call providers directly, or contain imperative logic +- Validated early and evaluated deterministically by the engine ```powershell @{ @@ -90,15 +79,18 @@ To enable larger flexibility, you can use placeholders instead of literals to be Steps = @( @{ Name = 'Step Name' + # The step type which defines which capabilities a provider has to supply to execute the step Type = 'IdLE.Step.StepType' With = @{ # Passed with values from Request Data IdentityKey = '{{Request.IdentityKeys.key}}' Attributes = @{ + # Fixed string example GivenName = 'Firstname' # Passed with values from Request Data Surname = '{{Request.DesiredState.Lastname}}' } + # Any identifier you choose, which references to the provider used in the plan and invocation Provider = 'IdentityProvider' } } @@ -106,17 +98,14 @@ To enable larger flexibility, you can use placeholders instead of literals to be } ``` -### Workflows and Steps - -**Steps** are reusable plugins used by **workflows** that define convergence logic. They: +**Steps** are **reusable plugins** used by workflows that define convergence logic. They: -- Operate idempotently (converge towards desired state) -- Are provider-agnostic (use contracts, not direct system calls) +- Implement idempotent domain logic (converge towards desired state). +- Declare required capabilities (by name) and consume providers via those capability contracts. +- Step types identify the step implementation, they are not capabilities! Capabilities (namespaced IdLE.* contract names) describe provider functionality that steps require; do not conflate the two. +- Are provide-agnostic via capability contracts, and do not provide any concrete system calls. - Emit structured events for audit and progress -- Define the capabilities a provider has to supply to be eligible to perform a step - -Steps may only write to `State.*` and only to declared output paths. -No deep merge: replace-at-path semantics only. +- **Important:** Steps must not handle authentication — authentication is a provider responsibility (AuthSessionBroker). Learn more: [Workflows](../use/workflows.md) | [Step Catalog](../reference/steps.md) @@ -124,9 +113,11 @@ Learn more: [Workflows](../use/workflows.md) | [Step Catalog](../reference/steps **Providers** are system-specific adapters that connect workflows to external systems. They: +- Translate generic operations to system APIs to implement infrastructure-specific behavior +- Advertise which capabilities they fulfill and map capability operations to system APIs and fulfill contracts expected by steps (as defined by capability names) - Authenticate and manage sessions -- Translate generic operations to system APIs - Are mockable for tests +- Avoid global state Learn more: [Providers](../use/providers.md) | [Providers and Contracts](../extend/providers.md) @@ -144,6 +135,18 @@ Condition = @{ } ``` +### **Capabilities** + +IdLE uses a **capability-based provider model** to validate execution prerequisites during plan build. +Steps may declare required capabilities, while providers explicitly advertise which capabilities they support. The engine matches both sides +and fails fast if required functionality is missing. Capabilities are the "glue" between provider-agnostic Steps and the system-specific providers. They are + +- named, namespaced contracts (e.g., `IdLE.Identity.Read`) that describe the operations/shape a provider must expose +- declared by steps as required capabilities and advertised by providers at registration +- matched during planning: the engine validates required capabilities are available and fails fast if not + +For details on the capability-based model see [Provider Capabilities](../reference/capabilities.md). + --- ## Plan @@ -165,33 +168,6 @@ conditions, and execution prerequisites. - produces data-only actions - captures a **data-only request intent snapshot** (e.g. IdentityKeys / DesiredState / Changes) for auditing and export -### Provider Capabilities (Planning-time Validation) - -IdLE uses a **capability-based provider model** to validate execution -prerequisites during plan build. - -Steps may declare required capabilities, while providers explicitly -advertise which capabilities they support. The engine matches both sides -and fails fast if required functionality is missing. - -For details on the capability-based provider model and the validation flow, -see [Provider Capabilities](../reference/capabilities.md). - -### Plan export - -Hosts may persist or exchange a plan as a **machine-readable JSON artifact**. -The canonical contract format is defined here: - -- [Plan export specification (JSON)](../reference/specs/plan-export.md) - -The exported artifact is intended for **approvals, CI checks, and audits**. -To keep exports deterministic and review-friendly, the contract intentionally omits volatile information -such as engine build versions and timestamps. When required, hosts SHOULD attach build/time metadata -outside the exported plan artifact. - -Because IdLE separates planning from execution, the plan retains a **request intent snapshot** so that -exports can include `request.input` even after the original request object is no longer available. - --- ## Execute @@ -202,17 +178,4 @@ Execution runs **only the plan** (no re-planning). This supports: - repeatability - deterministic audits -### Eventing - -IdLE emits **structured events** during execution. - -- The engine always creates an `EventSink` and exposes it as `Context.EventSink`. -- Steps and the engine use a single contract: `Context.EventSink.WriteEvent(Type, Message, StepName, Data)`. -- All events are buffered in the execution result (`result.Events`). - -Hosts may optionally provide an external sink to stream events live: - -- `Invoke-IdlePlan -EventSink ` -- The sink must implement `WriteEvent(event)` -- ScriptBlock sinks are rejected (secure default) - +IdLE emits **structured events** during execution which allows post-execution check on overall status or per-step results and messages. From 0f5f6a06452466a0a29cd610b336f06fdb41d2ff Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Sun, 15 Feb 2026 21:15:37 +0100 Subject: [PATCH 07/14] docs: updated security page --- docs/about/security.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/about/security.md b/docs/about/security.md index c159614f..5bb8f6af 100644 --- a/docs/about/security.md +++ b/docs/about/security.md @@ -1,10 +1,8 @@ --- -title: Security +title: Security and Trust Boundaries sidebar_labels: Security --- -# Security and Trust Boundaries - IdLE is designed to execute **data-driven** identity lifecycle workflows in a deterministic way. Because IdLE is an orchestration engine, it must be explicit about **what is trusted** and **what is untrusted**. @@ -26,11 +24,13 @@ These inputs may come from users, CI pipelines, or external systems and **must b **Rule:** Untrusted inputs must be *data-only*. They must not contain ScriptBlocks or other executable objects. IdLE enforces this by: + - Rejecting ScriptBlocks when importing workflow definitions -- Validating inputs at runtime using `Assert-IdleNoScriptBlock` +- Validating inputs at runtime using the public `Assert-IdleNoScriptBlock` function (provided by `IdLE.Core`) - Recursively scanning all hashtables, arrays, and PSCustomObjects for ScriptBlocks **Implementation:** + - The `Assert-IdleNoScriptBlock` function is the single, authoritative validator for this boundary - It performs deep recursive validation with no type exemptions - All workflow configuration, lifecycle requests, step parameters, and provider maps are validated @@ -49,7 +49,8 @@ These inputs are provided by the host and are **privileged** because they determ These extension points may contain ScriptMethods (e.g., the `AcquireAuthSession` method on AuthSessionBroker objects) but should not contain ScriptBlock *properties* that could be confused with data. -**AuthSessionBroker Trust Model:** +#### AuthSessionBroker Trust Model + - The broker is a **trusted extension point** provided by the host - It orchestrates authentication without embedding secrets in workflows - Broker objects may contain ScriptMethods (e.g., `AcquireAuthSession`) as part of their interface @@ -82,6 +83,8 @@ Redaction happens for: - `apikey`, `apiKey`, `clientSecret` - `accessToken`, `refreshToken` - `credential`, `privateKey` + - `AccountPassword`, `AccountPasswordAsPlainText`, `GeneratedAccountPasswordPlainText`, `GeneratedAccountPasswordProtected` + - **Sensitive runtime types**, regardless of key name: - `PSCredential` - `SecureString` From 23457a8aa54ef9b9e1081897903bb818d9f0f364 Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Mon, 16 Feb 2026 21:19:40 +0100 Subject: [PATCH 08/14] docs: rewrite about and use area, adding walkthrough --- docs/about/concepts.md | 194 +++++------ docs/about/intro.md | 49 ++- docs/about/security.md | 2 +- docs/develop/releases.md | 6 +- docs/use/installation.md | 170 +++------- docs/use/intro-use.md | 49 ++- docs/use/plan-export.md | 79 ++--- docs/use/providers.md | 302 ++++------------- docs/use/quickstart.md | 225 +++++++------ .../use/walkthrough/01-workflow-definition.md | 83 +++++ docs/use/walkthrough/02-request-creation.md | 73 ++++ docs/use/walkthrough/03-plan-creation.md | 86 +++++ docs/use/walkthrough/04-invoke-results.md | 75 +++++ .../05-providers-authentication.md | 184 +++++++++++ docs/use/workflows.md | 312 +++--------------- website/sidebars.js | 12 + 16 files changed, 961 insertions(+), 940 deletions(-) create mode 100644 docs/use/walkthrough/01-workflow-definition.md create mode 100644 docs/use/walkthrough/02-request-creation.md create mode 100644 docs/use/walkthrough/03-plan-creation.md create mode 100644 docs/use/walkthrough/04-invoke-results.md create mode 100644 docs/use/walkthrough/05-providers-authentication.md diff --git a/docs/about/concepts.md b/docs/about/concepts.md index c26fe97c..801ae117 100644 --- a/docs/about/concepts.md +++ b/docs/about/concepts.md @@ -7,6 +7,18 @@ IdLE is a generic, headless, configuration-driven engine for identity lifecycle The engine first builds a deterministic, auditable execution plan from a LifecycleRequest and a workflow (Plan → Execute). Planning validates conditions, inputs, and required provider capabilities; execution runs only the produced plan to ensure repeatability, safe approvals, and reliable auditing. This design prioritizes portability, testability (mockable providers), and minimal runtime assumptions by keeping the core headless and side-effect free. +This page explains the **big picture**: responsibilities, trust boundaries, and how the core artifacts fit together. + +## Start here + +- If you want to **run IdLE now**: start with [Quick Start](../use/quickstart.md). +- If you want the full end-to-end flow: follow the **Walkthrough**: + 1. [Workflow definition](../use/walkthrough/01-workflow-definition.md) + 2. [Request creation](../use/walkthrough/02-request-creation.md) + 3. [Plan build](../use/walkthrough/03-plan-creation.md) + 4. [Invoke and results](../use/walkthrough/04-invoke-results.md) + 5. [Providers and authentication](../use/walkthrough/05-providers-authentication.md) + ## Goals - Generic, configurable lifecycle orchestration (Joiner / Mover / Leaver) @@ -25,157 +37,105 @@ The engine first builds a deterministic, auditable execution plan from a Lifecyc --- -## Components +## Responsibilities -IdLE consists of the following elements and components, which have clear and distinct boundaries to separate their responsibilities and make maintainability easier. This separation keeps the core engine free of environmental assumptions. +### Separation of Responsibility -### Host +Clear separation of responsibility is the essential foundation for maintainability: -The host is technically not really a component of IdLE. It is the environment in which IdLE is running, so your PowerShell console, scripting session or whatever is used to run IdLe. The host +- **Engine** + - Orchestrates workflow execution + - Invokes steps + - Passes providers to steps + - Never depends on provider internals -- Selects and configures providers -- Injects providers into plan execution -- Decides which provider implementations are used +- **Steps** + - Implement domain logic + - Use providers through contracts + - Must not assume a specific provider implementation -### Engine (basically IdLE.Core) +- **Providers** + - Implement infrastructure-specific behavior + - Fulfill contracts expected by steps + - Encapsulate external system details + - Authenticate and manage sessions -IdLE.Core is the central engine (module) of IdLE and performs the most central tasks +If you want the practical version of this (how to supply providers/auth in a run), see: +[Walkthrough 5: Providers and authentication](../use/walkthrough/05-providers-authentication.md). -- Orchestrates workflow execution -- Invokes steps -- Passes providers to steps -- Never depends on provider internals -- Authentication session brokerage +--- ## Request -A **LifecycleRequest** represents the business intent (for example: Joiner, Mover, Leaver). It is the input to planning. - -```powershell -$Request = New-IdleRequest -LifecycleEvent 'Joiner' -IdentityKeys @{ - key = 'first.last' -} -DesiredState @{ - Firstname = 'First' - Lastname = 'Last' - Mail = 'First.Last@domain.tld' -} -``` - -### Workflow and Steps - -**Workflows** are **data-only configuration files** (PSD1) describing which steps should run for a lifecycle event. Usually workflows are written in `psd1` files, that - -- use Data-only PSD1 configuration (no ScriptBlocks or executable objects) -- declare step sequence by Type string and provide per-step With parameters -- may use placeholders referencing Request data; substitutions occur during planning -- serve as deterministic, reviewable input to the planner (suitable for approvals and audits) -- must not perform authentication, call providers directly, or contain imperative logic -- Validated early and evaluated deterministically by the engine - -```powershell -@{ - Name = 'Joiner - Example Workflow' - LifecycleEvent = 'Joiner' - Steps = @( - @{ - Name = 'Step Name' - # The step type which defines which capabilities a provider has to supply to execute the step - Type = 'IdLE.Step.StepType' - With = @{ - # Passed with values from Request Data - IdentityKey = '{{Request.IdentityKeys.key}}' - Attributes = @{ - # Fixed string example - GivenName = 'Firstname' - # Passed with values from Request Data - Surname = '{{Request.DesiredState.Lastname}}' - } - # Any identifier you choose, which references to the provider used in the plan and invocation - Provider = 'IdentityProvider' - } - } - ) -} -``` - -**Steps** are **reusable plugins** used by workflows that define convergence logic. They: - -- Implement idempotent domain logic (converge towards desired state). -- Declare required capabilities (by name) and consume providers via those capability contracts. -- Step types identify the step implementation, they are not capabilities! Capabilities (namespaced IdLE.* contract names) describe provider functionality that steps require; do not conflate the two. -- Are provide-agnostic via capability contracts, and do not provide any concrete system calls. -- Emit structured events for audit and progress -- **Important:** Steps must not handle authentication — authentication is a provider responsibility (AuthSessionBroker). - -Learn more: [Workflows](../use/workflows.md) | [Step Catalog](../reference/steps.md) +A **request** represents your business intent (Joiner/Mover/Leaver) plus the input data required to build a plan. -### Providers +Typical request content: -**Providers** are system-specific adapters that connect workflows to external systems. They: +- Identity keys (for example: EmployeeId, SamAccountName, UPN) +- Desired state (attributes, entitlements, mailbox settings, …) +- Optional metadata/context -- Translate generic operations to system APIs to implement infrastructure-specific behavior -- Advertise which capabilities they fulfill and map capability operations to system APIs and fulfill contracts expected by steps (as defined by capability names) -- Authenticate and manage sessions -- Are mockable for tests -- Avoid global state +Hands-on: [Walkthrough 2: Request creation](../use/walkthrough/02-request-creation.md). -Learn more: [Providers](../use/providers.md) | [Providers and Contracts](../extend/providers.md) +--- -### Declarative conditions +## Workflow -Steps can contain conditions which are data-only objects. -They are validated early and evaluated deterministically. +A **workflow** is a data-only definition (`.psd1`) that describes **what** should happen, step by step. -```powershell -Condition = @{ - Equals = @{ - Path = 'Plan.LifecycleEvent' - Value = 'Joiner' - } -} -``` +### Workflows and Steps -### **Capabilities** +A workflow consists of ordered steps. Each step references a **StepType** by name and provides configuration under `With`. -IdLE uses a **capability-based provider model** to validate execution prerequisites during plan build. -Steps may declare required capabilities, while providers explicitly advertise which capabilities they support. The engine matches both sides -and fails fast if required functionality is missing. Capabilities are the "glue" between provider-agnostic Steps and the system-specific providers. They are +Hands-on: [Walkthrough 1: Workflow definition](../use/walkthrough/01-workflow-definition.md). +Specification: [Use → Workflows](../use/workflows.md) and the [Reference section](../reference/steps.md). -- named, namespaced contracts (e.g., `IdLE.Identity.Read`) that describe the operations/shape a provider must expose -- declared by steps as required capabilities and advertised by providers at registration -- matched during planning: the engine validates required capabilities are available and fails fast if not +### Providers -For details on the capability-based model see [Provider Capabilities](../reference/capabilities.md). +Workflows may reference providers by alias (for example: `With.Provider = 'Identity'`), but the actual provider instances are supplied by the host. + +Hands-on: [Walkthrough 5: Providers and authentication](../use/walkthrough/05-providers-authentication.md). + +### Declarative conditions + +Workflows can include declarative conditions (data-only) to decide whether steps should run. +For details, use the Reference workflow documentation. --- ## Plan -IdLE builds a **deterministic execution plan** before any step is executed. +A **plan** is the validated, resolved execution contract produced from a workflow and a request. + +Hands-on: [Walkthrough 3: Plan build](../use/walkthrough/03-plan-creation.md). -The plan is created deterministically from: +### Provider Capabilities (Planning-time Validation) -- request data -- workflow definition -- step catalog / step registry -- authentication session informations +IdLE can validate required capabilities at plan-build time (fail-fast), if providers are supplied. +This prevents discovering missing requirements only at execution time. -During this planning phase, the engine validates structural correctness, -conditions, and execution prerequisites. +### Plan export -- evaluates declarative conditions -- validates inputs and references -- produces data-only actions -- captures a **data-only request intent snapshot** (e.g. IdentityKeys / DesiredState / Changes) for auditing and export +Plans can be exported for review, approval, CI artifacts, and audit trails. + +Hands-on: [Use → Plan Export](../use/plan-export.md). --- ## Execute -Execution runs **only the plan** (no re-planning). This supports: +Executing a plan runs the steps in order and produces a structured result. + +Hands-on: [Walkthrough 4: Invoke and results](../use/walkthrough/04-invoke-results.md). + +### Eventing + +IdLE emits structured events during execution. +Your host can log them, forward them, or store them for audit and diagnostics. + +--- -- approvals -- repeatability -- deterministic audits +## Next -IdLE emits **structured events** during execution which allows post-execution check on overall status or per-step results and messages. +- Run the minimal end-to-end example: [Quick Start](../use/quickstart.md) +- Continue with deep details: [Reference](../reference/intro-reference.md) diff --git a/docs/about/intro.md b/docs/about/intro.md index 8c2829fe..410db182 100644 --- a/docs/about/intro.md +++ b/docs/about/intro.md @@ -9,15 +9,8 @@ sidebar_label: Introduction ## Introduction -IdLE is a **generic, headless, configuration-driven** lifecycle orchestration engine -for identity and account processes (Joiner / Mover / Leaver), built for **PowerShell 7+**. - -The key idea is to **separate intent from implementation**: - -- **What** should happen is defined in a **workflow** (data-only configuration). -- **How** it happens is implemented by **steps** and **providers** (pluggable modules). - - **steps** define, via StepTypes, which provider-agnostic **capabilities** are required to perform a workflow step - - **providers** register to the core and announce the provided **capabilities** and implement the vendor system specific interface +IdLE (Identity Lifecycle Engine) is a **generic, configurable orchestration framework** for identity lifecycle processes +(Joiner / Mover / Leaver and similar cases), built for **PowerShell 7+**. --- @@ -37,20 +30,42 @@ Self-made identity lifecycle automation often turns into long scripts that are: Identity Management Systems (IdMS) on the other side are either complex or expensive (or both of it) and then often do not care about supplementary systems that also need to be covered within the workflows. -IdLE aims to be: +--- + +## Start using IdLE + +- If you want to run IdLE now: start with [Quick Start](../use/quickstart). +- If you want a guided path: follow the [Walkthrough](../use/walkthrough/01-workflow-definition). +- If you want the architecture and responsibility model: read [Concepts](./concepts). + +--- + +## Key ideas + +- **Workflows** are data-only `.psd1` files describing what to do. +- A **Request** captures intent + input data. +- A **Plan** is the validated, resolved execution contract. +- **Invoke** executes the plan and emits structured events. +- **Providers** implement system-specific behavior and authentication. + +IdLE is designed to be: - **portable** run in different environments with PowerShell 7+ without a hard dependency on a specific host or UI - **configuration-driven** workflows are defined as data, not code. - **modular** a small core and pluggable providers and steps that even support **extending** with your own custom add-ons. - **testable** deterministic planning, mockable providers, and strong contracts. +:::info +IdLE is **headless**. Your host (script, CI job, service) provides providers and authentication. +Workflows and requests remain data-only. +::: + --- -## Key Features +## Next -- **Joiner / Mover / Leaver** orchestration (and custom lifecycle events) -- **Plan → Execute** flow (preview actions before applying them) -- **Plugin step model** (`Test` / `Invoke`, optional `Rollback` later) -- **Provider/Adapter pattern** (directory, SaaS, REST, file/mock…) -- **Structured events** for audit/progress (CorrelationId, Actor, step results) -- **Idempotent execution** (steps can be written to converge state) +- [How to use IdLE?](../use/intro-use.md) + - [Installation](../use/installation.md) + - [QuickStart](../use/quickstart.md) + - [Walkthrough - Step 1: Workflow Definition](../use/walkthrough/01-workflow-definition.md) +- [Reference](../reference/intro-reference.md) diff --git a/docs/about/security.md b/docs/about/security.md index 5bb8f6af..478ba42a 100644 --- a/docs/about/security.md +++ b/docs/about/security.md @@ -1,6 +1,6 @@ --- title: Security and Trust Boundaries -sidebar_labels: Security +sidebar_label: Security --- IdLE is designed to execute **data-driven** identity lifecycle workflows in a deterministic way. diff --git a/docs/develop/releases.md b/docs/develop/releases.md index 356bb272..c513215f 100644 --- a/docs/develop/releases.md +++ b/docs/develop/releases.md @@ -1,10 +1,8 @@ --- -title: Releases -sidebar_labels: Releases +title: Releasing IdLE +sidebar_label: Releases --- -# Releasing IdLE - This document describes the **maintainer** release process for IdLE. IdLE currently ships release artifacts in two channels: diff --git a/docs/use/installation.md b/docs/use/installation.md index 3de95cc1..928dffe9 100644 --- a/docs/use/installation.md +++ b/docs/use/installation.md @@ -3,10 +3,7 @@ title: Installation sidebar_label: Installation --- -# Installation - -IdLE can be consumed either from the **PowerShell Gallery** (recommended for most users) or directly from the -**Github repository source** (useful for contributors and development scenarios). +IdLE can be installed either from the **PowerShell Gallery** (recommended) or directly from the [**GitHub repository source**](https://github.com/blindzero/IdentityLifecycleEngine) (useful for contributors and development scenarios). --- @@ -16,172 +13,93 @@ IdLE can be consumed either from the **PowerShell Gallery** (recommended for mos --- -## Install IdLE - -### Install from PowerShell Gallery (recommended) +## Install from PowerShell Gallery (recommended) From a PowerShell 7 prompt: ```powershell -# Install the IdLE meta-module (automatically installs Core and Steps.Common dependencies) -Install-Module -Name IdLE +# Install the IdLE meta-module (pulls IdLE.Core and IdLE.Steps.Common as dependencies) +Install-Module -Name IdLE -Scope CurrentUser -# Import the module +# Import the baseline modules Import-Module -Name IdLE ``` :::info Command collision during install? -If PowerShellGet reports that a command is already available (for example `New-IdleAuthSessionBroker`), -prefer a clean reinstall instead of `-AllowClobber`: +If PowerShellGet reports that a command is already available, prefer a clean reinstall instead of `-AllowClobber`. ```powershell -Get-InstalledModule IdLE, IdLE.Core, IdLE.Steps.Common -ErrorAction SilentlyContinue | Uninstall-Module -AllVersions -Force +Get-InstalledModule IdLE, IdLE.Core, IdLE.Steps.Common -ErrorAction SilentlyContinue | + Uninstall-Module -AllVersions -Force + Install-Module -Name IdLE -Scope CurrentUser -Force +Import-Module -Name IdLE ``` ::: -The `IdLE` module declares `IdLE.Core` and `IdLE.Steps.Common` as dependencies (`RequiredModules`), so PowerShell automatically installs and imports them when you install `IdLE`. +--- -**Installing optional modules:** +## Install optional modules -Provider and additional step modules are published as separate modules and can be installed independently: +Providers and additional step modules are published as separate modules and can be installed independently. ```powershell -# Install specific provider modules as needed -Install-Module -Name IdLE.Provider.EntraID -Install-Module -Name IdLE.Provider.AD +# Provider modules (examples) +Install-Module -Name IdLE.Provider.AD -Scope CurrentUser +Install-Module -Name IdLE.Provider.EntraID -Scope CurrentUser +Install-Module -Name IdLE.Provider.ExchangeOnline -Scope CurrentUser + +# Optional step modules (examples) +Install-Module -Name IdLE.Steps.Mailbox -Scope CurrentUser -# Install optional step modules -Install-Module -Name IdLE.Steps.Mailbox +# Mock provider (safe, used for tests and walkthroughs) +Install-Module -Name IdLE.Provider.Mock -Scope CurrentUser ``` -Each provider and step module declares its own dependencies, so PowerShell will automatically install required modules (typically `IdLE.Core`). +Import only what you need: -### Install from repository source +```powershell +Import-Module -Name IdLE.Provider.Mock +Import-Module -Name IdLE.Provider.AD +``` + +:::tip +If a workflow references a StepType from an optional steps module, that steps module must be installed and imported in the host session. +::: -This path is primarily intended for contributors and development scenarios. +--- -From a PowerShell 7 prompt: +## Install from repository source (contributors) + +This path is intended for development and contribution scenarios. ```powershell git clone https://github.com/blindzero/IdentityLifecycleEngine cd IdentityLifecycleEngine -# Import meta module (automatically bootstraps module discovery for repo layout) +# Import meta module (bootstraps module discovery for repo layout) Import-Module ./src/IdLE/IdLE.psd1 -Force ``` -**Repository bootstrap behavior:** - -When importing `IdLE` from a repository/zip layout, the module automatically adds the `src/` directory to `$env:PSModulePath` (process-scoped only). This enables subsequent name-based imports: +After importing from source, you can import additional modules by name: ```powershell -# After importing IdLE from source, you can import other modules by name -Import-Module IdLE.Provider.EntraID -Force +Import-Module IdLE.Provider.Mock -Force Import-Module IdLE.Steps.Mailbox -Force ``` -The bootstrap is: -- **Idempotent**: Safe to import multiple times -- **Process-scoped**: No persistent system changes -- **Automatic**: No manual `$env:PSModulePath` configuration required - -### Verify installation - -```powershell -Get-Module IdLE -ListAvailable | Select-Object Name, Version, Path -Get-Command -Module IdLE -``` - --- -## What gets imported - -### `IdLE` meta-module (baseline) - -`IdLE` is the **baseline** entrypoint. It declares `IdLE.Core` and `IdLE.Steps.Common` as dependencies: - -- **IdLE.Core** — the workflow engine (step-agnostic) -- **IdLE.Steps.Common** — first-party built-in steps (e.g. `IdLE.Step.EmitEvent`, `IdLE.Step.EnsureAttributes`) - -**PowerShell Gallery installation:** -PowerShell automatically installs and imports these dependencies when you `Install-Module IdLE` and `Import-Module IdLE`. - -**Repository/zip installation:** -The `IdLE` module automatically loads `IdLE.Core` and `IdLE.Steps.Common` as nested modules and bootstraps `$env:PSModulePath` to enable name-based imports of other modules. - -Built-in steps are **available to the engine by default**, but for **PowerShell Gallery installations** step functions are intentionally **not exported into the global session state**. This keeps your PowerShell session clean while still allowing workflows to reference built-in steps by `Step.Type`. For **repository/zip installations**, adding `src/` to `$env:PSModulePath` means PowerShell may surface nested module commands in the session; these commands are not considered part of IdLE’s stable public API surface and are primarily intended for use by workflows, not direct interactive invocation. - -**Non-blocking guarantee:** `Import-Module IdLE` always succeeds on a clean PowerShell 7 environment without any external dependencies (RSAT, AD tools, third-party modules, etc.). - -### Optional modules - -Provider and additional step modules are **published separately** and can be installed/imported as needed. These modules may have system-specific or tool-specific dependencies: - -- **Provider modules**: `IdLE.Provider.AD`, `IdLE.Provider.EntraID`, `IdLE.Provider.ExchangeOnline`, etc. (see [Provider Reference](providers.md)) -- **Optional step modules:** `IdLE.Steps.DirectorySync`, `IdLE.Steps.Mailbox` -- **Development/testing modules:** `IdLE.Provider.Mock` - -**From PowerShell Gallery:** - -```powershell -# Install and import baseline -Install-Module IdLE -Import-Module IdLE - -# Install and import optional provider as needed -Install-Module IdLE.Provider.AD -Import-Module IdLE.Provider.AD -``` - -**From source:** +## Verify installation ```powershell -# Import baseline (automatically bootstraps module discovery) -Import-Module ./src/IdLE/IdLE.psd1 -Force - -# Import optional provider by name (works because of bootstrap) -Import-Module IdLE.Provider.AD -Force +Get-Module IdLE -ListAvailable | Select-Object Name, Version, Path +Get-Command -Module IdLE | Sort-Object Name ``` -For usage details, see [Use > Provider](../use/providers.md). - --- -## Multi-Module Architecture - -Starting with version 1.0, IdLE uses a **multi-module distribution model** where each module is published separately to the PowerShell Gallery: - -- **IdLE.Core** — Workflow engine (published separately) -- **IdLE.Steps.Common** — Built-in steps (published separately) -- **IdLE** (meta-module) — Declares `RequiredModules` dependency on Core and Steps.Common -- **IdLE.Provider.\*** — Provider modules (each published separately) -- **IdLE.Steps.\*** — Optional step modules (each published separately) - -When you `Install-Module IdLE`, PowerShell automatically installs IdLE.Core and IdLE.Steps.Common as dependencies. - -This architecture provides: -- ✅ **Standard PowerShell dependency resolution** via `RequiredModules` -- ✅ **Granular installation** — Install only the modules you need (e.g., `Install-Module IdLE.Provider.EntraID`) -- ✅ **Clear dependency chains** — PowerShell automatically resolves and installs dependencies -- ✅ **Third-party extensibility** — Other modules can declare IdLE modules as dependencies - -### Source vs Published Manifests - -The repository uses a **dual-manifest strategy** to support both repo/zip and PowerShell Gallery scenarios: - -**Repository/Zip Layout:** -- `IdLE` manifest uses `NestedModules` with relative paths -- Includes `ScriptsToProcess` to bootstrap `$env:PSModulePath` -- Enables direct import: `Import-Module ./src/IdLE/IdLE.psd1` - -**PowerShell Gallery Published Packages:** -- Packaging tool transforms manifests for publication -- `IdLE` manifest uses name-based `RequiredModules` (no `NestedModules`) -- No `ScriptsToProcess` (not needed in standard module paths) -- Standard PowerShell dependency resolution +## Next -This approach ensures: -- ✅ Contributors can work directly from repository source -- ✅ Published modules follow PowerShell best practices -- ✅ No manual `$env:PSModulePath` configuration required for either scenario +- Run your first end-to-end example: [Quick Start](quickstart.md) +- Follow the guided path: [Walkthrough: 1. Workflow Definition](walkthrough/01-workflow-definition.md) diff --git a/docs/use/intro-use.md b/docs/use/intro-use.md index 4b25fb08..f2497f8c 100644 --- a/docs/use/intro-use.md +++ b/docs/use/intro-use.md @@ -3,19 +3,44 @@ title: Use IdLE sidebar_label: Use IdLE --- -This section explains how to **use IdLE** in day-to-day operations. +This section is the **hands-on guide** for running IdLE in real environments: -It is written for people who **define and run workflows**, **validate plans**, and **operate IdLE** in environments -with one or more providers. +- define **workflows** (data-only) +- create **requests** +- build **plans** (validation + template resolution) +- **invoke** plans (execution + events) +- provide **providers** and (if required) **authentication** from your host -## What you will find here +:::info +IdLE is not a “click tool”. The primary interfaces are workflow files plus a small set of public cmdlets. +Reference pages are the single source of truth for schemas and cmdlet details. +::: -- Installing and updating IdLE -- Define workflows -- Planning versus execution -- Running workflows -- Exporting plans for review and audit -- Executing workflow plans -- Troubleshooting common issues +--- + +## Start here + +1. [Installation](installation.md) +2. [Quick Start](quickstart.md) — first successful run (mock provider, safe) +3. **Walkthrough** — the full lifecycle, step by step: + - [Workflow definition](walkthrough/01-workflow-definition.md) + - [Request creation](walkthrough/02-request-creation.md) + - [Create Plan](walkthrough/03-plan-creation.md) + - [Invoke & interpret results](walkthrough/04-invoke-results.md) + - [Providers & authentication](walkthrough/05-providers-authentication.md) (host responsibility) + +--- + +## Use topics + +- [Workflows](workflows.md) — how workflow files are structured and validated +- [Providers](providers.md) — provider mapping and authentication patterns +- [Plan Export](plan-export.md) — export plans for review, CI artifacts, and audit + +--- + +## When to use other sections -If you want to extend IdLE and implement providers or steps, go to [Extend](../extend/intro-extend.md) instead. +- If you want the **big picture** (responsibilities, trust boundaries, architecture): see [Concepts](../about/concepts.md) +- If you want to **extend IdLE** (write steps, providers, host integrations): see [Extend](../extend/intro-extend.md) +- If you need **specification-level details**: see [Reference](../reference/intro-reference.md) diff --git a/docs/use/plan-export.md b/docs/use/plan-export.md index 5e5d5986..77aedb81 100644 --- a/docs/use/plan-export.md +++ b/docs/use/plan-export.md @@ -3,73 +3,42 @@ title: Plan Export sidebar_label: Plan Export --- -# Plan Export +Plan export provides a **reproducible, machine-readable representation** of what IdLE intends to execute. + +--- ## Why export a plan? -Plan export provides a reproducible, machine-readable representation of the planned actions IdLE intends to run. -This is useful to: +Plan export is useful to: -- Review and approve a plan before execution (four-eyes principle). -- Persist evidence for audit and incident investigations. -- Compare changes over time (for example, when templates or defaults change). -- Integrate IdLE planning into CI pipelines (validate workflows without executing them). +- review and approve a plan before execution (four-eyes principle) +- persist evidence for audit and incident investigations +- compare planned actions over time (for example: template/default changes) +- integrate IdLE planning into CI pipelines (validate workflows without executing them) + +--- ## What a plan export contains A plan export typically includes: -- Metadata about the exported plan (name, workflow, timestamps). -- The planned step list in the order IdLE intends to execute it. -- Per-step resolved providers and parameters (as applicable). -- Capability information (if exported) to help with validation and portability. - -For the exact format and normative rules, see [Plan Export Specification](../reference/specs/plan-export.md). - -## Typical use of plan export - -1. Plan - - Load workflow definition(s) - - Resolve templates and inputs - - Evaluate conditions (steps may become NotApplicable) - -2. Export - - Serialize the planned steps into a JSON export - -3. Review - - Human review (pull request, change record) or automated checks (linting) - -4. Execute - - Run IdLE against the reviewed plan export (where supported) - -## Example: export for review - -```powershell -# Example only. Adjust parameters to your environment. -$request = New-IdleRequest -LifecycleEvent 'Joiner' -IdentityKeys @{ EmployeeId = 'jdoe' } -$providers = @{ Identity = New-IdleMockIdentityProvider } -$plan = New-IdlePlan -WorkflowPath './workflows/joiner.psd1' -Request $request -Providers $providers -Export-IdlePlan -Plan $plan -Path './artifacts/joiner.plan.json' -``` - -:::note - -Exported plans typically do not include provider objects. When executing an exported plan, -you must supply providers at execution time. +- metadata about the exported plan (name, workflow, timestamps) +- the planned step list in execution order +- step configuration after template resolution (as applicable) +- provider alias references (but **not** live provider objects) +- capability information (if available) +:::info +A plan export is an **execution contract**. It is designed to be reviewed and approved before it runs. +Providers and authentication are always supplied by the host at execution time. ::: -### Review tips - -- Verify provider selection matches your intent (especially in multi-provider environments). -- Ensure sensitive values are not embedded in exported parameters. -- Confirm step ordering and prerequisite behavior. - -## CI usage +--- -Plan export can be used as a build artifact: +## Typical flow (review gate) -- Generate a plan export from a known input set. -- Validate the export with schema checks (if available). -- Compare against a known-good baseline (golden file) to detect unexpected drift. +1. Build a plan in a controlled environment (CI / staging). +2. Export the plan as an artifact for review/approval. +3. Execute the approved plan in the target environment (prod), supplying providers and auth. +This matches the IdLE separation of concerns: workflows/requests are data-only; providers/auth are host responsibilities. diff --git a/docs/use/providers.md b/docs/use/providers.md index 0479f557..eed03ca5 100644 --- a/docs/use/providers.md +++ b/docs/use/providers.md @@ -3,296 +3,114 @@ title: Providers sidebar_label: Providers --- -# Providers +Providers are **system-specific adapters** (for example: Active Directory, Entra ID, Exchange Online) that connect IdLE steps to external systems. -Providers are the system-specific adapters (for example: Active Directory, Entra ID, Exchange Online) that connect -IdLE workflows to external systems. - -For advanced provider documentation, including concepts, contracts, authentication, usage patterns, and examples, see: [Extend > Providers](../extend/providers.md) - ---- - -## What are providers? - -Providers: - -- adapt IdLE workflows to external systems -- handle authentication via AuthSessionBroker -- translate generic operations to system APIs -- are mockable for tests -- provide capabilities, required by step types - -See: [Provider responsibilities](../about/concepts.md#responsibilities) - -## How to use providers? - -Providers are supplied to plan execution as a hashtable with alias names. +In IdLE, providers are **supplied by your host** (script, CI job, service). Workflows and requests remain **data-only**. :::info - -As providers may require additional tools and configuration, they are not imported automatically and must be imported manually by the host. - +**Reference-first:** Provider contracts, authentication models, and provider-specific details live in the Reference section. +This page explains how providers are used in the **lifecycle flow** (plan build and execution) without duplicating reference content. ::: -### Provider Resolution - -When executing a plan, providers can be supplied in two ways: +--- -1. **During planning** (recommended for most scenarios): +## What providers do -```powershell -Import-Module -Name IdLE.Provider.Mock +A provider typically: -$providers = @{ - Identity = New-IdleMockIdentityProvider -} +- translates generic IdLE **operations to a system API** +- **exposes capabilities** used during plan validation +- **uses an AuthSessionBroker** (or equivalent host-provided authentication) to access systems +- supports mocking for tests -# Build plan with providers -$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request -Providers $providers +See the big-picture responsibility model in [Concepts](../about/concepts.md#responsibilities). -# Execute without re-supplying providers (uses Plan.Providers) -$result = Invoke-IdlePlan -Plan $plan -``` - -2. **At execution time** (for provider override or exported plans): - -```powershell -# Override providers at execution time -$otherProviders = @{ - Identity = New-IdleMockIdentityProvider -Config $differentConfig -} - -$result = Invoke-IdlePlan -Plan $plan -Providers $otherProviders -``` - -#### Resolution Rules +--- -- If `-Providers` is supplied to `Invoke-IdlePlan`, it **takes precedence** over `Plan.Providers`. -- If `-Providers` is **not** supplied, `Invoke-IdlePlan` uses `Plan.Providers` (if available). -- If neither is present, execution fails early with: `Providers are required. Provide -Providers to Invoke-IdlePlan or build the plan with Providers.` +## Provider mapping (alias → provider instance) -#### Exported Plans +IdLE expects a hashtable of providers keyed by **alias**. -When a plan is exported without provider objects (for review or audit), providers must be supplied at execution time: +The alias is what workflow steps reference via `With.Provider`. ```powershell -# Export plan (without providers) -Export-IdlePlan -Plan $plan -Path ./plan.json - -# Later: execute with providers (plan import functionality is planned for future release) -$result = Invoke-IdlePlan -Plan $plan -Providers $providers -``` - -### Provider Aliases - -When you supply providers to IdLE, you use a **hashtable** that maps **alias names** to **provider instances**, e.g. `MockIdentity` +Import-Module -Name IdLE.Provider.Mock -```powershell $providers = @{ - MockIdentity = New-IdleMockIdentityProvider + Identity = New-IdleMockIdentityProvider } ``` -#### Alias Naming - -The alias name (hashtable key) is **completely flexible** and chosen by you (the host): - -- It can be any valid PowerShell hashtable key -- Common patterns: - - **Role-based**: `Identity`, `Entitlement`, `Messaging` (when you have one provider per role) - - **Instance-based**: `SourceAD`, `TargetEntra`, `ProdForest`, `DevSystem` (when you have multiple providers) -- The built-in steps default to `'Identity'` if no `Provider` is specified in the step's `With` block - -#### How Workflows Reference Providers +:::tip +You can use any provider alias, it is just a string used as a reference. +::: -Workflow steps can specify which provider to use via the `Provider` key in the `With` block: +In your workflow, a step references that alias: ```powershell @{ - Name = 'Create user' - Type = 'IdLE.Step.CreateIdentity' - With = @{ - IdentityKey = 'newuser' - Attributes = @{ ... } - Provider = 'MockIdentity' # References the alias from the provider hashtable - } -} -``` - -If `Provider` is not specified, it defaults to `'Identity'`: - -```powershell -# These are equivalent when Provider is not specified: -With = @{ IdentityKey = 'user1'; Name = 'Department'; Value = 'IT' } -With = @{ IdentityKey = 'user1'; Name = 'Department'; Value = 'IT'; Provider = 'Identity' } -``` - -### Multiple Provider Example - -```powershell -# Create provider instances -$sourceAD = New-IdleADIdentityProvider -Credential $sourceCred -$targetEntra = New-IdleEntraIDIdentityProvider -Credential $targetCred - -# Map to custom aliases -$providers = @{ - SourceAD = $sourceAD - TargetEntra = $targetEntra + Name = 'Ensure demo attributes' + Type = 'IdLE.Step.EnsureAttributes' + With = @{ + Provider = 'Identity' + # ... + } } - -# Workflow steps reference the aliases -# Step 1: With = @{ Provider = 'SourceAD'; ... } -# Step 2: With = @{ Provider = 'TargetEntra'; ... } ``` -## Authentication for Providers (AuthSessionBroker) - -Many providers require authenticated connections (tokens, API clients, remote sessions). -IdLE keeps authentication out of the engine and out of individual providers by using a -host-supplied broker. Using the **AuthSessionBroker** is in particular helpful for scenarios that use different providers or different authentications for one provider in one workflow. - -### AuthSessionType - -AuthSessionBroker session values must specify an `AuthSessionType` that determines validation rules, lifecycle management, and telemetry behavior: +--- -- **`OAuth`** - Token-based authentication (e.g., Microsoft Graph, Exchange Online) -- **`PSRemoting`** - PowerShell remoting execution context (e.g., Entra Connect) -- **`Credential`** - Credential-based authentication (e.g., Active Directory, mock providers) +## When providers are supplied -Each provider documents its required `AuthSessionType` in its reference documentation. +There are two supported patterns: -### Example: Simple Single Credential +### 1) Supply providers during plan build (recommended) -For the simplest case with just one credential: +This enables **fail-fast** validation (capabilities, required provider presence) at plan-build time. ```powershell -# Obtain credential (e.g., from a secure vault or credential manager) -$credential = Get-Credential -Message "Enter admin credentials" - -# Create provider -$provider = New-IdleADIdentityProvider - -# Create broker with single credential -$broker = New-IdleAuthSession -DefaultAuthSession $credential -AuthSessionType 'Credential' - -# Use in plan -$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{ - Identity = $provider - AuthSessionBroker = $broker -} +$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request -Providers $providers +$result = Invoke-IdlePlan -Plan $plan ``` -### Example: Role-Based Credentials +### 2) Supply providers at execution time (overrides / exported plans) -For scenarios with multiple credentials for different roles, use `AuthSessionOptions` in workflows to select the appropriate credential: +This is useful when: -```powershell -# Obtain credentials (e.g., from a secure vault or credential manager) -$tier0Credential = Get-Credential -Message "Enter Tier0 admin credentials" -$adminCredential = Get-Credential -Message "Enter regular admin credentials" - -# Create provider -$provider = New-IdleADIdentityProvider - -# Create broker with role-based credential mapping -$broker = New-IdleAuthSession -SessionMap @{ - @{ Role = 'Tier0' } = $tier0Credential - @{ Role = 'Admin' } = $adminCredential -} -DefaultAuthSession $adminCredential -AuthSessionType 'Credential' - -# Use in plan -$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{ - Identity = $provider - AuthSessionBroker = $broker -} -``` - -In the workflow definition, steps specify which role to use via `AuthSessionOptions`: +- you execute a plan that was exported and approved elsewhere +- you need environment-specific provider instances (dev/test/prod) +- you want to override a provider mapping for one run ```powershell -With = @{ - ... - AuthSessionOptions = @{ Role = 'Tier0' } -} -``` - -### Example: Entra ID with OAuth +$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request -```powershell -# Host obtains token (example using Azure PowerShell) -Connect-AzAccount -$token = (Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com").Token - -# Create provider -$provider = New-IdleEntraIDIdentityProvider - -# Create broker with OAuth session type -$broker = New-IdleAuthSession -DefaultAuthSession $token -AuthSessionType 'OAuth' - -# Use in plan -$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{ - Identity = $provider - AuthSessionBroker = $broker -} +$result = Invoke-IdlePlan -Plan $plan -Providers $providers ``` -### Example: Mixed Authentication Types (AD + EXO) +For exported plans, see [Plan Export](./plan-export). -For workflows that need multiple providers with different authentication types: +--- -```powershell -# Obtain credentials and tokens -$adCredential = Get-Credential -Message "Enter AD admin credentials" -Connect-AzAccount -$exoToken = (Get-AzAccessToken -ResourceUrl "https://outlook.office365.com").Token - -# Create providers -$adProvider = New-IdleADIdentityProvider -$exoProvider = New-IdleExchangeOnlineProvider - -# Create broker with mixed authentication types -$broker = New-IdleAuthSession -SessionMap @{ - # Active Directory uses Credential type - @{ AuthSessionName = 'AD' } = @{ AuthSessionType = 'Credential'; Credential = $adCredential } - - # Exchange Online uses OAuth type - @{ AuthSessionName = 'EXO' } = @{ AuthSessionType = 'OAuth'; Credential = $exoToken } -} +## Authentication (host responsibility) -# Use in plan -$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{ - AD = $adProvider - EXO = $exoProvider - AuthSessionBroker = $broker -} -``` +IdLE workflows **shall not** contain secrets. -In the workflow, steps specify which authentication session to use via `AuthSessionName`: +Authentication is provided by your host, typically via an **AuthSessionBroker** (or another host-managed mechanism), and then used by providers and/or steps. -```powershell -# Step using AD (Credential) -@{ - Name = 'Create AD User' - Type = 'IdLE.Step.CreateIdentity' - With = @{ - AuthSessionName = 'AD' - # ... - } -} +:::warning +Do not store credentials, tokens, or executable ScriptBlocks in workflow files. +Keep workflows and requests **data-only**. +::: -# Step using EXO (OAuth) -@{ - Name = 'Create Mailbox' - Type = 'IdLE.Step.CreateMailbox' - With = @{ - AuthSessionName = 'EXO' - # ... - } -} -``` +For authentication patterns and provider contracts, see: -:::info +- [Reference: Providers](../reference/providers.md) -Please see the detailed [Provider Reference](../reference/providers.md) documentation for authentication help. +--- -::: +## Next steps + +- If you have not done so yet, start with the [Quick Start](quickstart.md). +- For the full end-to-end flow, follow the [Walkthrough](walkthrough/01-workflow-definition.md): + - workflow definition → request → plan → invoke → providers & auth +- For full specifications and examples, use the [Reference](../reference/intro-reference.md) section. diff --git a/docs/use/quickstart.md b/docs/use/quickstart.md index df75e471..2db77173 100644 --- a/docs/use/quickstart.md +++ b/docs/use/quickstart.md @@ -5,164 +5,195 @@ sidebar_label: Quick Start # Quick Start -The repository contains a demo runner that showcases the full **Plan → Execute** flow using predefined example workflows.
-Each example workflow is a single workflow definition `psd1`-file in `/examples/workflows/...` directories. +This Quick Start gets you from **zero** to a first successful run of the IdLE lifecycle: -## Get Repository Demo +1. Define a **workflow** (data-only `.psd1`) +2. Create a **request** (business intent) +3. Build a **plan** (validation + template resolution) +4. **Invoke** the plan (execution + events) -Clone the repository (or download the source archive from a GitHub release). - -```powershell -git clone https://github.com/blindzero/IdentityLifecycleEngine -cd IdentityLifecycleEngine -``` +:::info +IdLE does not ship a “live system host”. +Your **host** (script, CI job, service) supplies provider instances and (if needed) authentication. +::: -## Run Demo +--- -Our **Repository demo** provides sample workflows which are not provided by the module install from PowerShell Gallery package. +## Prerequisites -### 1. Show Demo Workflows +- PowerShell **7.x** or later (`pwsh`) +- The IdLE modules installed (for further details see [Installation](installation.md)) -By default the **IdLE Demo** script uses only examples workflow definition from the `examples/workflows/mock` folder category to avoid dependency to real-life systems. +--- -List available mock category examples: +## 1) Install and import modules ```powershell -.\examples\Invoke-IdleDemo.ps1 -List -``` - -### 2. Run Demo Workflow +# IdLE meta module (Core + Steps) +Install-Module -Name IdLE -Scope CurrentUser +Import-Module -Name IdLE -```powershell -.\examples\Invoke-IdleDemo.ps1 +# Mock provider (safe, no real systems touched) +Install-Module -Name IdLE.Provider.Mock -Scope CurrentUser +Import-Module -Name IdLE.Provider.Mock ``` -Select one of the workflow examples available, that does _not_ use real provider interactions and only use the mock provider interface. - -Alternatively, select an example workflow with `-Example` parameter: +:::tip +If you are running in CI, consider `-Scope AllUsers` or a dedicated PowerShellGet cache, depending on your environment. +::: -```powershell -.\examples\Invoke-IdleDemo.ps1 -Example -``` +--- -Or run all mock workflows: +## 2) Create a minimal workflow file -```powershell -.\examples\Invoke-IdleDemo.ps1 -All -``` +Workflows are **data-only** PowerShell hashtables stored as `.psd1` files. -What you should see: +Create a temporary workflow file with two steps: -- a lifecycle request is created -- a plan is built from a workflow definition (`.psd1`) -- the plan is executed with demo/mock providers -- the result contains step results and buffered events +- `IdLE.Step.EmitEvent` (no external side effects) +- `IdLE.Step.EnsureAttributes` (runs against the mock provider) -### 3. Check other examples +```powershell +$workflowPath = Join-Path $env:TEMP 'idle-quickstart-joiner.psd1' + +$workflowContent = @' +@{ + Name = 'QuickStart - Joiner (Mock)' + LifecycleEvent = 'Joiner' + + Steps = @( + @{ + Name = 'Emit start' + Type = 'IdLE.Step.EmitEvent' + With = @{ + Message = 'Starting Joiner workflow (QuickStart)' + } + } + + @{ + Name = 'Ensure demo attributes' + Type = 'IdLE.Step.EnsureAttributes' + With = @{ + Provider = 'Identity' + IdentityKey = '{{Request.IdentityKeys.EmployeeId}}' + Attributes = @{ + GivenName = '{{Request.DesiredState.GivenName}}' + Surname = '{{Request.DesiredState.Surname}}' + } + } + } + ) +} +'@ -We also provide additional "template" examples, which could be used with live systems. +Set-Content -Path $workflowPath -Value $workflowContent -Encoding UTF8 -Force -```powershell -.\examples\Invoke-IdleDemo.ps1 -List -Category All +$workflowPath ``` :::warning - -Use template examples with care as they connect and may cause harm to your live environments. - +Workflow definitions are **data-only**. Do not embed executable code (ScriptBlocks). +This is a core security boundary in IdLE. ::: --- -## Run your first workflow - -IdLE does not ship a “live system host”. A host (your script, CI job, or service) must provide provider instances -for execution. For a safe first run, IdLE ships mock providers that are sufficient to execute example workflows. - -This is the smallest runnable program that demonstrates the full flow: - -1. Create a request -2. Build a plan from a workflow -3. Execute with providers (mock) -4. Inspect result + events +## 3) Create a request -### 1. Import Mock Provider +A request represents business intent (Joiner/Mover/Leaver) plus input data. ```powershell -Import-Module .\src\IdLE.Provider.Mock\IdLE.Provider.Mock.psd1 -Force +$request = New-IdleRequest -LifecycleEvent 'Joiner' -IdentityKeys @{ + EmployeeId = '12345' +} -DesiredState @{ + GivenName = 'Max' + Surname = 'Power' +} ``` -### 2. Select Workflow +--- -Workflows are data files (`.psd1`). The quickest path is to reuse one of the repository examples, +## 4) Provide providers (host responsibility) -- reference a workflow file from `examples/workflows` -- or copy and adapt a single example workflow file into your working directory +Providers are supplied by your host. For this Quick Start we use the in-memory mock provider. -:::note +```powershell +$providers = @{ + Identity = New-IdleMockIdentityProvider +} +``` -The mock provider below can be used with workflows that use following Step Types: +--- -- IdLE.Step.EmitEvent -- IdLE.Step.ReadIdentity -- IdLE.Step.EnsureAttributes -- IdLE.Step.DisableIdentity -- IdLE.Step.EnableIdentity -- IdLE.Step.EnsureEntitlement +## 5) Build the plan (validation + template resolution) -::: +Plan building is a **fail-fast** step. IdLE validates the workflow and resolves templates like +`{{Request.DesiredState.GivenName}}`. ```powershell -$workflow = Join-Path 'C:\path\to\IdentityLifecycleEngine' 'examples\workflows\.psd1' +$plan = New-IdlePlan -WorkflowPath $workflowPath -Request $request -Providers $providers ``` -### 3. Create Request Object +--- -With the following command we create a simple 'Joiner' request. +## 6) Invoke the plan ```powershell -$request = New-IdleRequest -LifecycleEvent 'Joiner' +$result = Invoke-IdlePlan -Plan $plan ``` -### 4. Select providers +--- -For first run, we just use our internal mock provider. +## 7) Inspect the result and events ```powershell -$providers = @{ - Identity = New-IdleMockIdentityProvider -} +$result.Status + +# Step results (name, status, timings, messages) +$result.Steps | Select-Object Name, Status, Type + +# Buffered events +$result.Events | Select-Object StepName, Message, Type, TimestampUtc ``` -### 5. Build the plan with providers +--- -The plan evaluates validity of the request in combination with the workflow definition. +## What to do next -```powershell -$plan = New-IdlePlan -WorkflowPath $workflow -Request $request -Providers $providers -``` +- Learn workflow structure, templates, and conditions: [Workflows & Steps](workflows.md) +- Understand provider mapping and authentication patterns: [Providers](providers.md) +- Export a plan for review / CI artifacts: [Plan Export](plan-export.md) -### 6. Execute the plan +If you want to look up details in the reference: -```powershell -# Execute without re-supplying providers (uses Plan.Providers automatically) -$result = Invoke-IdlePlan -Plan $plan -``` +- [Cmdlets](../reference/cmdlets.md) +- [Steps](../reference/steps.md) +- [Providers](../reference/providers.md) + +--- + +## Explore repository examples (optional) -### 7. Inspect result + events +The IdLE repository contains an example runner and additional workflow samples. +This is useful to browse patterns and larger examples, but it is **not required** for normal IdLE usage. ```powershell -$result.Status -$result.Steps -$result.Events | Select-Object Type, StepName, Message -``` +git clone https://github.com/blindzero/IdentityLifecycleEngine +cd IdentityLifecycleEngine -:::tip +# List demo workflows (mock category by default) +.\examples\Invoke-IdleDemo.ps1 -List -- If your workflow contains steps that require additional provider roles (e.g. `Messaging`, `Entitlement`), - you must add them to `$providers`. -- Many steps default to the provider alias `'Identity'` unless a step explicitly sets `With.Provider`. -- You can override providers at execution time by passing `-Providers` to `Invoke-IdlePlan`. +# Run one demo workflow (interactive selection) +.\examples\Invoke-IdleDemo.ps1 +``` +:::warning +Some example categories may connect to real systems and can cause changes. +Only run examples you fully understand and only in safe environments. ::: +```powershell +# List all demos - also run templates +.\examples\Invoke-IdleDemo.ps1 -List -Category All +``` diff --git a/docs/use/walkthrough/01-workflow-definition.md b/docs/use/walkthrough/01-workflow-definition.md new file mode 100644 index 00000000..ac18c365 --- /dev/null +++ b/docs/use/walkthrough/01-workflow-definition.md @@ -0,0 +1,83 @@ +--- +title: Walkthrough 1 - Workflow definition +sidebar_label: "1. Workflow definition" +--- + +In this walkthrough series, you build a complete IdLE run step by step: + +**Workflow → Request → Plan → Invoke → Providers/Auth** + +This page focuses on the first artifact: the **workflow definition**. + +:::info +Workflows are **data-only** (`.psd1`). They describe *what* to do, not *how* to authenticate or connect. +Providers and authentication are supplied by your host. +::: + +--- + +## Goal + +Create a minimal workflow file that IdLE can validate and turn into a plan. + +## You will have + +- A workflow file on disk: `joiner.psd1` +- A workflow with one safe step (`IdLE.Step.EmitEvent`) and one provider-backed step (`IdLE.Step.EnsureAttributes`) + +--- + +## 1) Create a minimal workflow file + +Create a file `joiner.psd1` with this content: + +```powershell +@{ + Name = 'Walkthrough - Joiner (Minimal)' + LifecycleEvent = 'Joiner' + + Steps = @( + @{ + Name = 'Emit start' + Type = 'IdLE.Step.EmitEvent' + With = @{ + Message = 'Starting Joiner workflow (Walkthrough)' + } + } + + @{ + Name = 'Ensure demo attributes' + Type = 'IdLE.Step.EnsureAttributes' + With = @{ + Provider = 'Identity' + IdentityKey = '{{Request.IdentityKeys.EmployeeId}}' + Attributes = @{ + GivenName = '{{Request.DesiredState.GivenName}}' + Surname = '{{Request.DesiredState.Surname}}' + } + } + } + ) +} +``` + +:::warning +Do not embed executable code (ScriptBlocks) and do not store secrets in workflow files. +Workflows are treated as **untrusted input** and must remain **data-only**. +::: + +--- + +## 2) What the workflow describes + +- `LifecycleEvent` ties the workflow to a request intent (Joiner/Mover/Leaver). +- `Steps` is an ordered list. +- Each step references a **StepType** by name (`Type`). +- Step configuration lives under `With`. +- Template expressions like `{{Request.DesiredState.GivenName}}` are resolved when building the plan. + +--- + +## Next + +Continue with [**Walkthrough 2: Request creation**](02-request-creation.md). diff --git a/docs/use/walkthrough/02-request-creation.md b/docs/use/walkthrough/02-request-creation.md new file mode 100644 index 00000000..a73349a9 --- /dev/null +++ b/docs/use/walkthrough/02-request-creation.md @@ -0,0 +1,73 @@ +--- +title: Walkthrough 2 - Request creation +sidebar_label: "2. Request creation" +--- + +This page covers the second artifact in the IdLE lifecycle: + +**Workflow → Request → Plan → Invoke → Providers/Auth** + +A **request** represents business intent (Joiner/Mover/Leaver) plus the input data used by workflows (identity keys, desired state, and optional context). + +--- + +## Goal + +Create a minimal request that matches the workflow from [Walkthrough 1](01-workflow-definition.md). + +## You will have + +- A request object that contains: + - `LifecycleEvent` + - `IdentityKeys.EmployeeId` + - `DesiredState.GivenName` and `DesiredState.Surname` + +--- + +## 1) Create the request + +In PowerShell, create the request like this: + +```powershell +$request = New-IdleRequest -LifecycleEvent 'Joiner' -IdentityKeys @{ + EmployeeId = '12345' +} -DesiredState @{ + GivenName = 'Max' + Surname = 'Power' +} +``` + +This request provides the values referenced in the workflow templates: + +- `{{Request.IdentityKeys.EmployeeId}}` +- `{{Request.DesiredState.GivenName}}` +- `{{Request.DesiredState.Surname}}` + +--- + +## 2) What belongs into a request + +### IdentityKeys +Identity keys uniquely identify the identity you are acting on (for example: EmployeeId, SamAccountName, UPN). + +Identity keys are typically: + +- stable +- unique +- provided by the upstream system (HR, IAM, ticket) + +### DesiredState +Desired state contains the data you want IdLE to enforce (attributes, entitlements, mailbox settings, …). + +For this walkthrough we keep it minimal and only set two attributes. + +:::info +Requests are **data-only**. +Do not embed executable code (ScriptBlocks) and do not store secrets in requests. +::: + +--- + +## Next + +Continue with [**Walkthrough 3: Plan build**](03-plan-creation.md). diff --git a/docs/use/walkthrough/03-plan-creation.md b/docs/use/walkthrough/03-plan-creation.md new file mode 100644 index 00000000..8953dd15 --- /dev/null +++ b/docs/use/walkthrough/03-plan-creation.md @@ -0,0 +1,86 @@ +--- +title: Walkthrough 3 - Plan build +sidebar_label: "3. Plan build" +--- + +This page covers the third artifact in the IdLE lifecycle: + +**Workflow → Request → Plan → Invoke → Providers/Auth** + +A **plan** is the validated, resolved execution contract created from a workflow and a request. +Plan building is designed to be **fail-fast**. + +--- + +## Goal + +Build a plan from your workflow and request, while supplying providers (recommended). + +## You will have + +- A plan object that is safe to review and execute +- Templates resolved (for example `{{Request.DesiredState.GivenName}}`) +- Validation errors surfaced early (before execution) + +--- + +## Prerequisites + +- A workflow file `joiner.psd1` from Walkthrough 1 +- A request object from Walkthrough 2 +- Providers supplied by your host (Walkthrough 5 explains the patterns in detail) + +For this walkthrough we use the mock provider: + +```powershell +Import-Module -Name IdLE +Import-Module -Name IdLE.Provider.Mock + +$providers = @{ + Identity = New-IdleMockIdentityProvider +} +``` + +--- + +## 1) Build the plan + +```powershell +$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request -Providers $providers +``` + +--- + +## 2) What happens during plan build + +During plan build IdLE typically: + +- loads the workflow definition +- validates the workflow structure and step types +- validates that referenced providers exist (when supplied) +- checks required capabilities (provider/step contracts) +- resolves template expressions (for example `{{Request.DesiredState.GivenName}}`) +- produces a deterministic execution plan + +:::info +Supplying providers during plan build is recommended because it enables **fail-fast** validation. +If you plan to export and execute in another environment, you may supply providers at execution time. +::: + +--- + +## 3) Optional: Export the plan for review + +Plan export is useful when you want to: + +- review or approve a plan before execution +- publish the plan as a CI artifact +- retain an audit-friendly contract + +See [Plan Export](../plan-export.md). + +--- + +## Next + +Continue with [**Walkthrough 4: Invoke and results**](04-invoke-results.md). diff --git a/docs/use/walkthrough/04-invoke-results.md b/docs/use/walkthrough/04-invoke-results.md new file mode 100644 index 00000000..7cc8ca66 --- /dev/null +++ b/docs/use/walkthrough/04-invoke-results.md @@ -0,0 +1,75 @@ +--- +title: Walkthrough 4 - Invoke and results +sidebar_label: "4. Invoke and results" +--- + +This page covers the fourth stage in the IdLE lifecycle: + +**Workflow → Request → Plan → Invoke → Providers/Auth** + +When you invoke a plan, IdLE executes the steps in order and emits structured events. + +--- + +## Goal + +Execute the plan and inspect result data (status, step outcomes, events). + +## You will have + +- An invocation result object +- A basic understanding of where to look for success/failure and messages + +--- + +## 1) Invoke the plan + +If you supplied providers during plan build, invocation is simple: + +```powershell +$result = Invoke-IdlePlan -Plan $plan +``` + +If you did **not** supply providers during plan build, you can supply them at execution time: + +```powershell +$result = Invoke-IdlePlan -Plan $plan -Providers $providers +``` + +--- + +## 2) Inspect status and step outcomes + +```powershell +$result.Status + +$result.Steps | Select-Object Name, Status, StartedUtc, FinishedUtc +``` + +--- + +## 3) Inspect events + +IdLE produces structured events that you can log, forward, or store. + +```powershell +$result.Events | Select-Object Type, StepName, Message +``` + +--- + +## 4) If something fails + +Typical first-time failure causes: + +- StepType not imported / wrong `Type` name in the workflow +- Provider alias referenced by a step is missing in `$providers` +- Template paths resolve to null (missing request data) + +Use the step results and event messages to locate the failing step quickly. + +--- + +## Next + +Continue with [**Walkthrough 5: Providers and authentication**](05-providers-authentication.md). diff --git a/docs/use/walkthrough/05-providers-authentication.md b/docs/use/walkthrough/05-providers-authentication.md new file mode 100644 index 00000000..60fbc6f4 --- /dev/null +++ b/docs/use/walkthrough/05-providers-authentication.md @@ -0,0 +1,184 @@ +--- +title: Walkthrough 5 - Providers and authentication +sidebar_label: "5. Providers and authentication" +--- + +# Walkthrough 5: Providers and authentication + +This page completes the end-to-end IdLE lifecycle walkthrough: + +**Workflow → Request → Plan → Invoke → Providers/Auth** + +Providers and authentication are **host responsibilities**. Workflows and requests remain **data-only**. + +--- + +## Goal + +- Understand how workflow steps reference providers by alias (`With.Provider`) +- Understand how steps acquire authentication sessions at runtime (optional) +- Build a provider registry that works for both plan build and execution + +## You will have + +- A provider registry hashtable that contains: + - at least one system provider (for example: `Identity`) + - optionally an `AuthSessionBroker` for runtime credential selection + +--- + +## 1) Provider mapping (alias → provider instance) + +IdLE expects a hashtable of providers keyed by **alias**. Steps reference the alias via `With.Provider`. + +Example host mapping (mock provider): + +```powershell +Import-Module -Name IdLE.Provider.Mock + +$providers = @{ + Identity = New-IdleMockIdentityProvider +} +``` + +Example workflow usage: + +```powershell +@{ + Name = 'Ensure demo attributes' + Type = 'IdLE.Step.EnsureAttributes' + With = @{ + Provider = 'Identity' + IdentityKey = '{{Request.IdentityKeys.EmployeeId}}' + Attributes = @{ + GivenName = '{{Request.DesiredState.GivenName}}' + Surname = '{{Request.DesiredState.Surname}}' + } + } +} +``` + +:::info +If `With.Provider` is omitted, many provider-agnostic steps default to the alias `'Identity'`. +::: +::: + +--- + +## 2) When to supply providers + +### Recommended: supply providers during plan build + +This enables **fail-fast** validation (missing provider aliases, missing capabilities). + +```powershell +$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request -Providers $providers +$result = Invoke-IdlePlan -Plan $plan +``` + +### Alternative: supply providers at invoke time + +This is useful for exported plans or environment-specific overrides. + +```powershell +$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request +$result = Invoke-IdlePlan -Plan $plan -Providers $providers +``` + +--- + +## 3) Authentication is optional, but always host-owned + +IdLE workflows **must not** contain secrets. + +If a step needs credentials at runtime, it can request an auth session via: + +- `With.AuthSessionName` (string) +- `With.AuthSessionOptions` (optional hashtable) + +Example (step requests a named session): + +```powershell +@{ + Name = 'Ensure AD attributes (example)' + Type = 'IdLE.Step.EnsureAttributes' + With = @{ + Provider = 'Identity' + AuthSessionName = 'AD' + AuthSessionOptions = @{ Role = 'Tier0' } + + IdentityKey = '{{Request.IdentityKeys.EmployeeId}}' + Attributes = @{ + Department = '{{Request.DesiredState.Department}}' + } + } +} +``` + +During execution, the step will call `Context.AcquireAuthSession(AuthSessionName, AuthSessionOptions)` and pass the returned session to the provider method (if the provider supports an `AuthSession` parameter). + +:::warning +ScriptBlocks in `AuthSessionOptions` are rejected. Keep auth options **data-only**. +::: + +--- + +## 4) Configure an AuthSessionBroker (simple pattern) + +IdLE supports a simple, host-owned broker that routes sessions based on options. + +A minimal broker for a single credential: + +```powershell +$cred = Get-Credential + +$broker = New-IdleAuthSession -DefaultAuthSession $cred -AuthSessionType 'Credential' +``` + +A broker that supports named routing (example: `AD` and `EXO`): + +```powershell +$adCred = Get-Credential +$exoToken = '' + +$broker = New-IdleAuthSession -SessionMap @{ + @{ AuthSessionName = 'AD' } = @{ AuthSessionType = 'Credential'; Credential = $adCred } + @{ AuthSessionName = 'EXO' } = @{ AuthSessionType = 'OAuth'; Credential = $exoToken } +} +``` + +To make the broker available at runtime, add it to the provider registry under the key `AuthSessionBroker`: + +```powershell +$providers = @{ + Identity = New-IdleMockIdentityProvider + AuthSessionBroker = $broker +} +``` + +:::info +Providers can also work without a broker (for example: integrated authentication / run-as credentials). +The broker is the recommended mechanism when you need runtime selection without embedding secrets. +::: +::: + +--- + +## Reference + +- Provider contracts, capability model, and provider-specific authentication: [Reference: Providers](../../reference/providers.md) +- Workflow field details, templates, conditions: [Reference: Steps](../../reference/steps.md) + +--- + +## You are done (walkthrough) + +You now have the full end-to-end flow: + +1. Workflow definition (`.psd1`) +2. Request object +3. Plan build (fail-fast) +4. Invoke and inspect results/events +5. Providers & (optional) authentication + +Next, consider using **[Plan Export](../plan-export.md)** for review/approval and CI artifacts. diff --git a/docs/use/workflows.md b/docs/use/workflows.md index f29f0096..e53ef74a 100644 --- a/docs/use/workflows.md +++ b/docs/use/workflows.md @@ -3,307 +3,81 @@ title: Workflows & Steps sidebar_label: Workflows / Steps --- -# Workflows & Steps +Workflows define **what** IdLE should do for a lifecycle event (Joiner/Mover/Leaver). -Workflows are **data-only** configuration files (PSD1) describing which steps should run for a lifecycle event. +A workflow is a **data-only** PowerShell hashtable stored in a `.psd1` file. It describes the ordered steps to execute, plus optional conditions and error handling. -A step is a self-contained unit of work executed as part of a plan.
-A step: +:::info +For specification-level details (schema, templates, conditions, and validation rules), use the [Reference](../reference/intro-reference.md) section. +::: + +--- -- performs a single, well-defined responsibility -- operates on the execution context provided by the engine -- may interact with external systems through providers -- reports its outcome through status and events -- does _not_ orchestrate other steps and does _not_ control execution flow beyond their own outcome. +## What a workflow contains -## Workflow File Format +At a high level, a workflow contains: -A workflow is a PowerShell hashtable stored as `.psd1`. +- metadata (name, lifecycle event) +- a list of steps (ordered) +- per-step configuration (`With`) +- optional execution logic (conditions, `OnFailureSteps`, etc.) -Workflow definitions are **data-only**. Do not embed executable code. +The Big Picture is described in [Concepts](../about/concepts.md). -Example: +--- + +## Minimal workflow example ```powershell @{ - Name = 'Joiner - Standard' + Name = 'Joiner - Minimal' LifecycleEvent = 'Joiner' Steps = @( @{ Name = 'Emit start' Type = 'IdLE.Step.EmitEvent' - With = @{ Message = 'Starting Joiner' } + With = @{ + Message = 'Starting Joiner workflow' + } } ) } ``` -#### Name - -The identifying name of your workflow - -```yaml -Type: String -Required: True -``` - -#### LifecycleEvent - -The type of the lifecycle event described by your workflow. - -```yaml -Type: String -Required: True -Options: Joiner, Mover, Leaver -``` - -#### Steps - -An Array of step objects, each a Hashtable. - -```yaml -Type: Array -Required: True -``` - -## Steps - -Each step represents a distinct action that is performed based on data defined in the workflow parameters or passed in the host's request object; the engine merges with the workflow definition on the plan. - -Steps are represented by PowerShell Hashtable objects. - -### Step Types - -Step types are treated as **contracts**. Prefer fully-qualified ids (module + step name), for example: `IdLE.Step.EmitEvent`. -Each step type's implementation is made available via a step registry. -Additionally, each step type's implementation defines required capabilities for this step. -Later, provider implementations are providing these capabilities for the steps. -If a provider selected for a step does not have the capabilities required by the step type, the workflow plan with fail. - -For a list of available Step Types please see the [Step Type Catalog](../reference/steps.md). - -Additionally, you can extend IdLE with your own custom steps; see [Extending steps](../extend/steps.md). - -### Conditional steps - -Steps can be skipped using declarative `Condition` key. - -Example: - -```powershell -@{ - Name = 'Joiner - Condition Demo' - LifecycleEvent = 'Joiner' - Steps = @( - @{ - Name = 'EmitOnlyForJoiner' - Type = 'IdLE.Step.EmitEvent' - Condition = @{ - Equals = @{ - Path = 'Plan.LifecycleEvent' - Value = 'Joiner' - } - } - With = @{ - Message = 'This step runs only if Plan.LifecycleEvent == Joiner.' - } - } - ) -} -``` - -If the condition is not met, the step is marked as `Skipped` and a skip event is emitted. - -### OnFailureSteps (optional) - -Workflows can define cleanup or rollback steps that run when primary steps fail. -OnFailureSteps are executed in **best-effort mode**: - -- They run only if at least one primary step fails -- Each OnFailure step is attempted regardless of previous OnFailure step failures -- OnFailure step failures do not stop execution of remaining OnFailure steps -- The overall execution status remains 'Failed' even if all OnFailure steps succeed - -Example: - -```powershell -@{ - Name = 'Joiner - With Cleanup' - LifecycleEvent = 'Joiner' - - Steps = @( - @{ - Name = 'CreateAccount'; - Type = 'IdLE.Step.CreateAccount' - } - @{ - Name = 'EnsureEntitlement'; - Type = 'IdLE.Step.EnsureEntitlement' - } - ) - - OnFailureSteps = @( - @{ - Name = 'RollbackAccount'; - Type = 'IdLE.Step.DeleteAccount' - } - @{ - Name = 'LogFailure'; - Type = 'IdLE.Step.EmitEvent'; - With = @{ - Message = 'Joiner Failed - Rollback performed' - } - } - ) -} -``` - -**Best practices:** - -- Use OnFailureSteps for notifications, logging, or rollback operations -- Keep OnFailure steps simple and resilient -- Avoid dependencies between OnFailure steps -- Don't assume OnFailure steps will always succeed - -**Execution result:** - -The execution result includes a separate `OnFailure` section: - -```powershell -$result.OnFailure.Status # 'NotRun', 'Completed', or 'PartiallyFailed' -$result.OnFailure.Steps # Array of OnFailure step results -``` - -## References and inputs - -### Template substitution (double curly braces) - -IdLE supports **template substitution** for embedding request values into workflow step configurations using `{{...}}` placeholders. Templates are resolved during planning (plan build), producing a plan with resolved values. - -**How it works:** - -When you create a lifecycle request, you provide data in the request object (via `DesiredState`, `IdentityKeys`, etc.). Templates in workflow configurations reference these values using dot-notation paths. During plan building, IdLE resolves the templates by looking up the paths in the request object and substituting the actual values. - -**Creating a request with values:** - -```powershell -$req = New-IdleRequest -LifecycleEvent 'Joiner' -DesiredState @{ - UserPrincipalName = 'jdoe@example.com' - DisplayName = 'John Doe' - GivenName = 'John' - Surname = 'Doe' - Department = 'Engineering' -} -``` - -The values in `DesiredState` are accessible via `Request.Input.*` (or `Request.DesiredState.*`) in templates. - -**Using templates in workflows:** - -```powershell -@{ - Name = 'CreateUser' - Type = 'IdLE.Step.CreateIdentity' - With = @{ - Attributes = @{ - UserPrincipalName = '{{Request.Input.UserPrincipalName}}' - DisplayName = '{{Request.Input.DisplayName}}' - } - } -} -@{ - Name = 'EmitEvent' - Type = 'IdLE.Step.EmitEvent' - With = @{ - Message = 'Creating user {{Request.Input.DisplayName}} ({{Request.Input.UserPrincipalName}})' - } -} -``` - -When the plan is built, templates are resolved to the actual values from the request: -- `{{Request.Input.UserPrincipalName}}` → `'jdoe@example.com'` -- `{{Request.Input.DisplayName}}` → `'John Doe'` - -**Key features:** - -- **Concise syntax**: Use `{{Path}}` instead of verbose `@{ ValueFrom = 'Path' }` objects -- **Multiple placeholders**: Place multiple templates in one string -- **Nested structures**: Templates work in nested hashtables and arrays -- **Planning-time resolution**: Templates are resolved during plan build, not execution -- **Security boundary**: Only allowlisted request roots are accessible - -**Allowed references:** - -For security, template resolution only allows accessing these request properties: - -- `Request.Input.*` (aliased to `Request.DesiredState.*` if Input does not exist) -- `Request.DesiredState.*` -- `Request.IdentityKeys.*` -- `Request.Changes.*` -- `Request.LifecycleEvent` -- `Request.CorrelationId` -- `Request.Actor` - -Attempting to access other roots (like `Plan.*`, `Providers.*`, or `Workflow.*`) will fail during planning with an actionable error. - -**Type handling:** - -Templates resolve scalar values (string, numeric, bool, datetime, guid) to strings. Non-scalar values (hashtables, arrays, objects) are rejected with an error. If you need to map complex objects, use explicit mapping steps or host-side pre-flattening. - -**Error handling:** - -Template resolution fails fast during planning if: - -- Path does not exist or resolves to `$null` -- Path uses invalid characters or patterns -- Braces are unbalanced (typo safety) -- Root is not in the allowlist -- Value is non-scalar - -These deterministic errors prevent silent substitution bugs (like empty UPNs). - -**Escaping:** - -Use `\{{` to include literal `{{` in a string: +--- -```powershell -With = @{ - Message = 'Literal \{{ braces here and template {{Request.Input.Name}}' -} -# Resolves to: 'Literal `{{ braces here and template ' -``` +## How workflows are used in the lifecycle -**Request.Input alias:** +1. You write the workflow definition (`.psd1`). +2. You create a request (intent + inputs). +3. You build a plan (IdLE validates and resolves templates). +4. You invoke the plan. -Workflow authors can use `Request.Input.*` for consistency, even if the request object only provides `DesiredState`. IdLE automatically aliases `Request.Input.*` to `Request.DesiredState.*` when the `Input` property does not exist. +Start with [Quick Start](quickstart.md). -### Legacy reference syntax (ValueFrom) +--- -Prefer explicit reference fields over implicit parsing: +## Common pitfalls -- `Value` for literals -- `ValueFrom` for references (for example: `Request.EmployeeId`) -- `ValueDefault` for fallback literals +- **Not data-only:** embedding ScriptBlocks or secrets in workflow files (not allowed). +- **Wrong StepType name:** the step module is not imported or the type name is wrong. +- **Missing provider alias:** `With.Provider = 'Identity'` but the host did not supply that alias. +- **Template paths resolve to null:** the referenced request/identity data is missing. -This makes configurations safe and statically validatable. +--- -:::note +## Reference -Template substitution (`{{...}}`) is preferred for string fields. Use `ValueFrom` objects when you need non-string references or conditional defaults. +For full definitions and reference, see: -::: +- [Reference](../reference/intro-reference.md) +- [Reference: Step Types](../reference/steps.md) +- [Reference: Providers](../reference/providers.md) --- -## Workflow validation - -Workflows are validated during planning. - -Typical validation rules: - -- unknown keys are errors -- required keys must exist -- condition schemas must be valid -- `*From` paths must reference allowed roots +## Next steps +- Map external systems: [Providers](providers.md) +- Review and export plans: [Plan Export](plan-export.md) (e.g. for CI systems) diff --git a/website/sidebars.js b/website/sidebars.js index 0bb0ed3e..23ae81ac 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -34,6 +34,18 @@ const sidebars = { 'use/intro-use', 'use/installation', 'use/quickstart', + { + type: 'category', + label: 'Walkthrough', + collapsed: true, + items: [ + 'use/walkthrough/01-workflow-definition', + 'use/walkthrough/02-request-creation', + 'use/walkthrough/03-plan-creation', + 'use/walkthrough/04-invoke-results', + 'use/walkthrough/05-providers-authentication' + ], + }, 'use/workflows', 'use/providers', 'use/plan-export', From b6e3a618921363d7ea98223f55117c67fc08db6c Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Mon, 16 Feb 2026 21:26:21 +0100 Subject: [PATCH 09/14] website: fix walkthrough links in sidebar --- website/sidebars.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index 23ae81ac..dda30f0d 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -39,11 +39,11 @@ const sidebars = { label: 'Walkthrough', collapsed: true, items: [ - 'use/walkthrough/01-workflow-definition', - 'use/walkthrough/02-request-creation', - 'use/walkthrough/03-plan-creation', - 'use/walkthrough/04-invoke-results', - 'use/walkthrough/05-providers-authentication' + 'use/walkthrough/workflow-definition', + 'use/walkthrough/request-creation', + 'use/walkthrough/plan-creation', + 'use/walkthrough/invoke-results', + 'use/walkthrough/providers-authentication', ], }, 'use/workflows', From fb1921db8c5c7818b9ecd82b7aed6f176afb49b1 Mon Sep 17 00:00:00 2001 From: Matthias <13959569+blindzero@users.noreply.github.com> Date: Mon, 16 Feb 2026 21:26:58 +0100 Subject: [PATCH 10/14] Update docs/use/walkthrough/05-providers-authentication.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/use/walkthrough/05-providers-authentication.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/use/walkthrough/05-providers-authentication.md b/docs/use/walkthrough/05-providers-authentication.md index 60fbc6f4..e668e52e 100644 --- a/docs/use/walkthrough/05-providers-authentication.md +++ b/docs/use/walkthrough/05-providers-authentication.md @@ -61,7 +61,6 @@ Example workflow usage: :::info If `With.Provider` is omitted, many provider-agnostic steps default to the alias `'Identity'`. ::: -::: --- From 1acbf2998a57f7a75d1e3ac24ca1c294cf66934e Mon Sep 17 00:00:00 2001 From: Matthias <13959569+blindzero@users.noreply.github.com> Date: Mon, 16 Feb 2026 21:27:15 +0100 Subject: [PATCH 11/14] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ec8066f3..bd5cf8ee 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ For further installation instructions, requirements, and options, see **[Install ## How to start -Please refer to the documentation in **["How to use IdLE?"](docs/use/intro-use.md)** for further instructions, on +Please refer to the documentation in **["How to use IdLE?"](docs/use/intro-use.md)** for further instructions on the following topics: 1. How to write a workflow 2. Create an identity lifecycle request From 4ec9c8103313cbe1776b9dfd817acdfa28032a07 Mon Sep 17 00:00:00 2001 From: Matthias <13959569+blindzero@users.noreply.github.com> Date: Mon, 16 Feb 2026 21:28:31 +0100 Subject: [PATCH 12/14] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- docs/use/walkthrough/05-providers-authentication.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bd5cf8ee..bf7f03c9 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ The demo shows: - executing the plan using built-in steps and a mock provider By default, the demo runs **Mock workflows** that work out-of-the-box without external systems. -The examples folder also includes **Template workflows** that demonstrate real-world scenarios with Active Directory, Entra ID, Exchange Online but these require the corresponding infrastructure and provider modules. +The examples folder also includes **Template workflows** that demonstrate real-world scenarios with Active Directory, Entra ID, Exchange Online, but these require the corresponding infrastructure and provider modules. --- diff --git a/docs/use/walkthrough/05-providers-authentication.md b/docs/use/walkthrough/05-providers-authentication.md index e668e52e..97e96ae8 100644 --- a/docs/use/walkthrough/05-providers-authentication.md +++ b/docs/use/walkthrough/05-providers-authentication.md @@ -159,7 +159,7 @@ $providers = @{ Providers can also work without a broker (for example: integrated authentication / run-as credentials). The broker is the recommended mechanism when you need runtime selection without embedding secrets. ::: -::: + --- From 8b38b7c7dd3b563dcf3f64b1369a3d72ab64958c Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Mon, 16 Feb 2026 21:31:09 +0100 Subject: [PATCH 13/14] remove dup --- README.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index bf7f03c9..e800793c 100644 --- a/README.md +++ b/README.md @@ -26,15 +26,19 @@ The key idea is to **separate intent from implementation**: ## Why IdLE? -IdLE is a **generic, headless, configuration-driven** lifecycle orchestration engine -for identity and account processes (Joiner / Mover / Leaver), built for **PowerShell 7+**. +JML (joiner/mover/leavers) processes are -The key idea is to **separate intent from implementation**: +- error prone, especially if performed manually +- time consuming and therefore +- quite annoying for operators -- **What** should happen is defined in a **workflow** (data-only configuration). -- **How** it happens is implemented by **steps** and **providers** (pluggable modules). - - **steps** define, via StepTypes, which provider-agnostic **capabilities** are required to perform a workflow step - - **providers** register to the core and announce the provided **capabilities** and implement the vendor system specific interface +Self-made identity lifecycle automation often turns into long scripts that are: + +- tightly coupled to one environment +- hard to test +- hard to change safely + +Identity Management Systems (IdMS) on the other side are either complex or expensive (or both of it) and then often do not care about supplementary systems that also need to be covered within the workflows. --- From a504467b23db05494f247dc12ddc71cb2a89ad79 Mon Sep 17 00:00:00 2001 From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com> Date: Mon, 16 Feb 2026 21:38:30 +0100 Subject: [PATCH 14/14] website: disable number prefix suppressing in docusaurus for orphan checks collission --- website/docusaurus.config.js | 1 + website/sidebars.js | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 68b5e9b6..e2ab6c27 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -73,6 +73,7 @@ const config = { path: '../docs', routeBasePath: 'docs', // docs at /docs/... sidebarPath: require.resolve('./sidebars.js'), + numberPrefixParser: false, // <— keeps "01-" in ids/labels/urls // Edit links point to repo root, not /website editUrl: `https://github.com/${repoOwner}/${repoName}/edit/main/`, diff --git a/website/sidebars.js b/website/sidebars.js index dda30f0d..2ac97e77 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -39,11 +39,11 @@ const sidebars = { label: 'Walkthrough', collapsed: true, items: [ - 'use/walkthrough/workflow-definition', - 'use/walkthrough/request-creation', - 'use/walkthrough/plan-creation', - 'use/walkthrough/invoke-results', - 'use/walkthrough/providers-authentication', + 'use/walkthrough/01-workflow-definition', + 'use/walkthrough/02-request-creation', + 'use/walkthrough/03-plan-creation', + 'use/walkthrough/04-invoke-results', + 'use/walkthrough/05-providers-authentication', ], }, 'use/workflows',