Skip to content

providers.md

Latest commit

 

History

History
160 lines (111 loc) · 4.99 KB

providers.md

File metadata and controls

160 lines (111 loc) · 4.99 KB
title Providers
sidebar_label Providers

Providers are system-specific adapters (for example: Active Directory, Entra ID, Exchange Online) that connect IdLE steps to external systems.

In IdLE, providers are supplied by your host (script, CI job, service). Workflows and requests remain data-only.

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

What providers do

A provider typically:

  • 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

See the big-picture responsibility model in Concepts.

Provider mapping (alias → provider instance)

IdLE expects a hashtable of providers keyed by alias.

The alias is what workflow steps reference via With.Provider.

Import-Module -Name IdLE.Provider.Mock

$providers = @{
  Identity = New-IdleMockIdentityProvider
}

:::tip You can use any provider alias, it is just a string used as a reference. :::

In your workflow, a step references that alias:

@{
  Name = 'Ensure demo attributes'
  Type = 'IdLE.Step.EnsureAttributes'
  With = @{
    Provider = 'Identity'
    # ...
  }
}

When providers are supplied

There are two supported patterns:

1) Supply providers during plan build (recommended)

This enables fail-fast validation (capabilities, required provider presence) at plan-build time.

$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request -Providers $providers
$result = Invoke-IdlePlan -Plan $plan

2) Supply providers at execution time (overrides / exported plans)

This is useful when:

  • 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
$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request

$result = Invoke-IdlePlan -Plan $plan -Providers $providers

For exported plans, see Plan Export.

Authentication (host responsibility)

IdLE workflows shall not contain secrets.

Authentication is provided by your host, typically via an AuthSessionBroker (or another host-managed mechanism), and then used by providers and/or steps.

At a high level, the host is responsible for:

  • choosing the auth mechanism (token, certificate, managed identity, workload identity, etc.)
  • acquiring and caching sessions as needed
  • injecting the broker or session factory into provider instances

Generic example (host-managed auth, provider-agnostic):

# A step can request an auth session by name and optional options.
$workflowStep = @{
  Name = 'Ensure attributes (example)'
  Type = 'IdLE.Step.EnsureAttributes'
  With = @{
    Provider           = 'Identity'
    AuthSessionName    = 'AD'
    AuthSessionOptions = @{ Role = 'Tier0' }

    IdentityKey = '{{Request.IdentityKeys.EmployeeId}}'
    Attributes  = @{ Department = '{{Request.Intent.Department}}' }
  }
}

# Host configures a broker and supplies it alongside providers.
$adCred   = Get-Credential
$exoToken = '<token-or-object-from-your-exo-login-flow>'

$authSessionBroker = New-IdleAuthSession -SessionMap @{
  @{ AuthSessionName = 'AD' }  = @{ AuthSessionType = 'Credential'; Credential = $adCred }
  @{ AuthSessionName = 'EXO' } = @{ AuthSessionType = 'OAuth';       Credential = $exoToken }
}

$providers = @{
  Identity          = New-IdleMockIdentityProvider
  AuthSessionBroker = $authSessionBroker
}

# In a real host, $request would typically be created earlier from your JML/event payload.
$request = New-IdleRequest -LifecycleEvent 'Joiner' -IdentityKeys @{ EmployeeId = '12345' } -Intent @{ Department = 'IT' }
$plan = New-IdlePlan -WorkflowPath ./joiner.psd1 -Request $request -Providers $providers
Invoke-IdlePlan -Plan $plan

During execution, the step will call Context.AcquireAuthSession(AuthSessionName, AuthSessionOptions) and pass the returned AuthSession to the provider method (if the provider supports an AuthSession parameter).

:::warning Do not store credentials, tokens, or executable ScriptBlocks in workflow files. Keep workflows and requests data-only. :::

Provider-specific authentication variants and required options are documented in the provider reference. For authentication patterns and provider contracts, see:

Next steps

  • If you have not done so yet, start with the Quick Start.
  • For the full end-to-end flow, follow the Walkthrough.
  • For full specifications and examples, use the Reference section.