Skip to content

provider-entraID.md

Latest commit

 

History

History
180 lines (123 loc) · 6.93 KB

provider-entraID.md

File metadata and controls

180 lines (123 loc) · 6.93 KB
title Provider Reference - Microsoft Entra ID (IdLE.Provider.EntraID)
sidebar_label Entra ID

import CodeBlock from '@theme/CodeBlock';

import EntraJoiner from '@site/../examples/workflows/templates/entraid-joiner.psd1'; import EntraLeaver from '@site/../examples/workflows/templates/entraid-leaver.psd1';

Summary

  • Module: IdLE.Provider.EntraID
  • What it’s for: Entra ID user lifecycle + group entitlements (Microsoft Graph API)
  • Targets: Microsoft Entra ID (formerly Azure AD) via Microsoft Graph (v1.0)

When to use

Use this provider when your workflow needs to manage Entra ID user accounts, for example:

  • Joiner: create or update a user, set baseline attributes, assign baseline groups
  • Mover: update org attributes and managed groups (covered as optional patterns inside the Joiner template)
  • Leaver: disable account, revoke sessions, optional cleanup (groups, delete)

Non-goals:

  • Obtaining tokens or storing secrets (handled by your runtime + AuthSessionBroker pattern)
  • Exchange Online mailbox configuration (use the Exchange Online provider/steps)

Getting started

Requirements

  • Your runtime must be able to supply a Microsoft Graph auth session (token/session object) to IdLE
  • Graph permissions must allow the actions you intend to run (users + groups)

Install (PowerShell Gallery)

Install-Module IdLE.Provider.EntraID -Scope CurrentUser

Import

Import-Module IdLE.Provider.EntraID

Quickstart

Create provider (safe defaults):

$provider = New-IdleEntraIDIdentityProvider

Typical alias pattern:

$providers = @{
  Identity = $provider
}

In a workflow template, reference your auth session via steps (example):

With = @{
  AuthSessionName    = 'MicrosoftGraph'
  AuthSessionOptions = @{ Role = 'Admin' }
}

Keep tokens/secrets out of workflow files. Resolve them in the host/runtime and provide them via the broker.

Authentication

This provider expects Graph authentication to be supplied at runtime (AuthSessionBroker pattern). Common session shapes used by hosts include:

  • raw access token string (Bearer token)
  • object with an AccessToken property
  • object that can produce a token (e.g., GetAccessToken())

Recommended wiring in examples:

  • AuthSessionName = 'MicrosoftGraph'
  • AuthSessionOptions = @{ Role = 'Admin' } for routing (optional)
  • Use a more privileged role only for privileged actions (e.g. delete)

Context Resolvers

This provider supports Context Resolvers for the allowlisted, read-only capabilities below.

Capability: IdLE.Identity.Read

Writes to scoped path: Request.Context.Providers.<ProviderAlias>.<AuthSessionKey>.Identity.Profile
Engine-defined View: Request.Context.Views.Identity.Profile
Type: PSCustomObject (PSTypeName = 'IdLE.Identity')

Top-level properties:

Property Type Notes
PSTypeName string Always IdLE.Identity.
IdentityKey string The identity key used by the workflow (typically the Entra user id).
Enabled bool Derived from Entra user accountEnabled.
Attributes hashtable Key/value bag; keys are strings; values are typically string.

Attributes keys populated by this provider (when present on the user object):

Attribute key Type Source (Graph field)
GivenName string givenName
Surname string surname
DisplayName string displayName
UserPrincipalName string userPrincipalName
Mail string mail
Department string department
JobTitle string jobTitle
OfficeLocation string officeLocation
CompanyName string companyName

Attribute access: Profile attributes are nested under the Attributes key. In Conditions, use Request.Context.Views.Identity.Profile.Attributes.DisplayName (or the scoped Request.Context.Providers.<ProviderAlias>.<AuthSessionKey>.Identity.Profile.Attributes.DisplayName), not Request.Context.Views.Identity.Profile.DisplayName (or Request.Context.Providers.<ProviderAlias>.<AuthSessionKey>.Identity.Profile.DisplayName).

Capability: IdLE.Entitlement.List

Writes to scoped path: Request.Context.Providers.<ProviderAlias>.<AuthSessionKey>.Identity.Entitlements
Engine-defined View: Request.Context.Views.Identity.Entitlements
Type: object[] (array of PSCustomObject, PSTypeName = 'IdLE.Entitlement')

Each element represents one Entra ID group membership:

Property Type Notes
PSTypeName string Always IdLE.Entitlement.
Kind string Always Group.
Id string Entra group id.
Mail string or $null Group mail (if returned by the adapter).

Notes:

  • The output paths are fixed by the engine and cannot be changed.
  • Each entry is automatically annotated with SourceProvider and SourceAuthSessionName metadata.
  • Use the global View (Request.Context.Views.Identity.Entitlements) in Conditions when you don't need to filter by provider. Use the scoped path when you need results from a specific provider only.
  • See Context Resolvers for the full path reference.

Configuration

Provider constructor / factory

  • New-IdleEntraIDIdentityProvider

High-signal parameters

  • -AllowDelete — opt-in to enable the IdLE.Identity.Delete capability (disabled by default for safety)

Provider-specific options reference

This provider has no provider-specific option bag. Configuration is done through constructor parameters; authentication is handled by your runtime via the broker.

Required Microsoft Graph permissions

At minimum, you typically need:

  • Users: read/write (create/update/disable/delete if enabled)
  • Groups: read/write memberships (if you use entitlement steps)

Exact permission names depend on your auth model (delegated vs application) and what operations you enable.

Examples (canonical templates)

These are the two canonical Entra ID templates, intended to be embedded directly in documentation. Mover scenarios are integrated as optional patterns in the Joiner template.

{EntraJoiner}

{EntraLeaver}

Troubleshooting

  • 401/403 from Microsoft Graph: token missing/expired or insufficient Graph permissions for the requested operation.
  • Auth session not found: check AuthSessionName matches your runtime/broker configuration.
  • Delete doesn’t work: deletion is opt-in. Create the provider with -AllowDelete and only use delete with a privileged auth role.
  • Group cleanup is disruptive: only enable revoke/remove operations when you fully understand the impact (prefer managed allow-lists).